Repository navigation
Conversation
0.3.0 dropped the old FAQ rather than editing it, because every question in it
was about a runtime that had just been removed: "Does RainfallJS use React's
Context API?", "Can I use it with class components?", "How is this different
from Redux?". It was written pre-AI, for a data-provider library, and none of
it described this package any more.
Nothing replaced it, which left the most important question unanswered: does
this work with a frontend that is not JavaScript?
It does, and the new FAQ leads with it. The two artifacts are JSON — the
manifest and schema/components.json, the component-shape catalogue — so a
SwiftUI, Flutter, Blazor, Django, Rails, Android or Unity frontend reads them
like any other JSON and implements the shapes natively. `rainfall components
--json` prints one, `condense` prints the other, and neither output contains a
line of JavaScript. The JS mapper is one implementation of the catalogue, not
the definition of it.
Also answered, with the limits stated rather than glossed:
- What actually requires Node: only the CLI, at build time, like a linter.
Nothing at runtime in any language.
- `scan` reads React/Next source only, and will find nothing in a Swift or Go
project. Verified: cli/scan.js walks .js/.jsx/.ts/.tsx and no other
extension. It matters less than it sounds, because scan only ever produces
the skeleton — `rainfall prompt` plus an assistant is the recommended path
on every stack, including JS.
- Backends are declared, not introspected, so they can be anything.
- Why this is not OpenAPI: OpenAPI describes the API, not which screen calls
it or which requirement it serves. They compose.
- It is useful without AI — validate catches drift whether or not an agent is
involved.
Claims checked against the code before writing: the endpoint `reads` field
exists in schema/rainfall.schema.json, and the example JSON matches the shape in
examples/manifest/rainfall.json.
Rides along with the unpublished 0.3.1; no further bump.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two problems, and the second is the more embarrassing one.
THE DEMO WAS UNREFERENCED
examples/fintech-demo/ landed on main with 25 files, a full Next.js finance app
and a rainfall.json describing it — and the README mentioned it zero times. The
one piece of reproducible evidence for the central claim was unfindable unless
you already knew the path. Added a section with the numbers, the commands to
re-run them, and a pointer to GROK_PROMPT.md, which is the part that tests
whether an agent given only the digest can actually make the change.
THE NUMBERS WERE STALE
TOKENS.md called itself "real, reproducible" and was neither. It reported:
All project source files: ~4977 tokens (19 files)
Savings vs exploring: 6.9x
Running it now gives:
All project source files: ~3699 tokens (17 files)
Savings vs exploring: 5.1x
The two files are `.gitignore` and a `.claude/` skill doc. The walker excludes
dotfiles now, which is the more honest count — neither is source an agent reads
to understand a data layer — and the headline multiple fell from 6.9x to 5.1x
accordingly. The focused figure moved the same way: ~21x became ~16x.
Nothing was wrong with the tool. A measurement was written down once and never
re-run, and the document kept asserting it after it stopped being true. That is
precisely the failure this package exists to catch, in this package's own demo,
in a file whose title claims reproducibility.
TOKENS.md is now the literal output of `rainfall report`, with a note saying to
regenerate rather than trust it, and recording that it already drifted once. The
README section carries the same corrected figures, verified to match the live
output line for line.
Also in this commit: the FAQ answering how to use this from a non-JavaScript
frontend (see the preceding commit on this branch).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The logo existed in the repo and appeared nowhere. Now at the top of the README, so it shows on both GitHub and npmjs.com. Two things had to be fixed first. IT WAS NOT TRANSPARENT RainfallJS_logo_transparent.png has an alpha channel and does not use it: the corner pixel is (216, 227, 216), a pale grey baked in behind the mark. On a dark background — GitHub in dark mode, npm's dark theme — it renders as a grey square with a logo inside it. assets/logo.png is the fixed version. The background is cleared by flood fill from the border rather than by colour match, which matters: the circuit traces in the mark are near-white too, and a plain colour match would have punched holes through them. 57% of the image was background. Then cropped to the mark and resized to 512px: 500 KB down to 221 KB, which is a more reasonable thing to serve at the top of every README view. THE URL HAD TO BE ABSOLUTE npmjs.com does not resolve relative image paths — a `` that works on GitHub renders as a broken image there. It points at raw.githubusercontent.com/.../main/assets/logo.png, which works in both places. Also removes the duplicate copies at the repo root. The PNG and the DALL·E webp existed twice, once at root and once under assets/, for about 1 MB of duplication in a public repo. assets/ keeps the originals. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
murffious
added a commit
that referenced
this pull request
Sep 15, 2026
0.3.1 was published from main before #41 merged. The npm tarball got the badge fixes; the repo at the same version number also had the logo, the FAQ, the demo section and the corrected token numbers. Same version string, two different contents — which is its own small instance of the thing this package exists to prevent. This bump makes the published README match the repo again. No code change: 72 tests, 0 vulnerabilities, 0 runtime dependencies. Worth noting for next time, and now written down in CONTRIBUTING: npm renders the README from the published tarball, so a docs change reaches GitHub on merge and npm only on publish. Publishing and merging are not interchangeable, and publishing first silently pins a version number to content that no longer exists anywhere. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
0.3.0 dropped the old FAQ rather than editing it — every question in it was about a runtime that had just been removed ("Does RainfallJS use React's Context API?", "Can I use it with class components?", "How is this different from Redux?"). Written pre-AI, for a data-provider library.
Nothing replaced it, which left the most important question unanswered: does this work with a frontend that isn't JavaScript?
It does, and the FAQ now leads with it. Both artifacts are JSON — the manifest and
schema/components.json— so SwiftUI, Flutter, Blazor, Django, Rails, Android or Unity read them like any other JSON and implement the shapes natively. Neitherrainfall condensenorrainfall components --jsonemits a line of JavaScript. The JS mapper is one implementation of the catalogue, not its definition.Also answered, with limits stated rather than glossed:
scanread my Swift/Go project?validatecatches drift regardlessClaims checked against the code first: the endpoint
readsfield exists inschema/rainfall.schema.json, and the example JSON matchesexamples/manifest/rainfall.json.Rides along with the unpublished 0.3.1 — no further bump.
🤖 Generated with Claude Code