Stop tracking dist/ and types/, add a prepare script

Summary

dist/ and types/ are tracked in git and are not in .gitignore. That creates a workflow trap with no error signal: after editing src/, opening any examples/*.html silently exercises the previously built bundle, because all 22 example pages load dist/jsfeatNext.js directly. Nothing warns you; the example just runs old code.

Proposal: add a prepare script and stop tracking the build output.

Why it bites

The failure mode is silent, which is what makes it worth fixing rather than just remembering harder. It came up while verifying #119 on sample_orb_pinball.html: the fix was in src/, dist/ was still the 0.11.0 build, and the visual check would have exercised the unfixed code and looked fine.

Running npm run dev-ts (vite build --watch) fixes the staleness, but has its own cost: with the watcher running, dist/ and types/ are permanently dirty in the working tree, so git status fills with build output and a stray git add -A sweeps it into a source commit.

So today you pick between two failure modes — testing stale code, or committing build artefacts by accident.

What the tracked build output is actually for

Worth stating, because two of the three assumed reasons turn out not to hold:

Purpose	Still needed?
npm release	No. release.yml already runs npm run build-ts — "rebuild dist/ + types/ fresh from this tag's source" — before npm publish. The committed copies are never published.
GitHub Pages / hosted examples	No. Pages is not enabled on this repo (GET /repos/webarkit/jsfeatNext/pages → 404), and no workflow deploys the examples.
github:webarkit/jsfeatNext#<sha> installs into jsfeatNext-examples	Yes, today. There is no prepare script, so npm does not build git dependencies — which is exactly why PRs meant for pre-release testing have had to commit built artefacts.
Opening examples/*.html from a fresh clone	Yes, today.

Only the last two are real, and a prepare script removes the third.

Proposal

1. Add "prepare": "npm run build-ts" to package.json. npm runs it automatically when a package is installed from a git reference, and before npm publish.
2. Untrack dist/ and types/, and add them to .gitignore.

Effects:

• git status stops showing build output, so npm run dev-ts can just be left running.
• Build artefacts can no longer be committed by accident.
• Repository weight stops growing by a rebuilt bundle per release.
• github:webarkit/jsfeatNext#<sha> keeps working — npm builds it on install instead of relying on committed output. This removes the constraint that pre-release test PRs must commit dist/.
• The release pipeline is unaffected: it already builds from source.
• chore(release): … and rebuild dist commits become unnecessary.

Costs, stated honestly

• A fresh clone can no longer open examples/*.html without building first (npm install would cover it via prepare, but a clone without install would not). This is the one genuine regression. Mitigations: state it at the top of the examples section in the README, and/or have the pages show a clear message when the bundle is missing instead of failing with an opaque console error.
• prepare also runs on ordinary local npm install, adding a build to every install. A few seconds here, but it is not free.
• Anyone currently relying on reading dist/ straight from the GitHub repo (raw URLs) would break. CDN users are unaffected: unpkg and jsdelivr serve the npm package, not the repository.

Alternatives considered

• Leave it and rely on npm run dev-ts. Cheapest, works today, and worth doing regardless — but it makes the dirty-worktree problem permanent rather than solving it.
• A staleness banner in the examples. The browser cannot see source mtimes, so it would need a build timestamp baked into the bundle and compared against something fragile. Considerable machinery for a symptom this proposal removes outright.
• Track dist/ but not types/. Halves the noise, solves neither failure mode.

Not urgent

Nothing is blocked by this. Filing it so the trade-off is written down rather than rediscovered the next time an example is verified against a stale bundle.

Related

• Surfaced while verifying #119 on the ORB example
• Published-package contents: #60
• Release pipeline: MAINTAINERS.md, .github/workflows/release.yml

Start with package.json, .gitignore, the examples section of README, and .github/workflows/release.yml. Check how the existing build-ts script and release workflow handle dist/ and types/, then verify the prepare behavior for git installs and the fresh-clone example workflow. Done means generated output is no longer tracked, installs build it automatically, and the documentation explains the prerequisite.