EPBDS-16211 E4: generate the package's declarations from the source

[AlexSamBY]

What changes

E4: the package's declarations are generated from the source. The hand-written src/library/types folder is gone. The types a host gets are now the types the component is checked against.

The contract is an ordinary module

• src/library/contract.ts holds every published type as an export. I moved them with git mv from types/UIRender.tsx, where they were members of a declare namespace. Each declaration's text is unchanged apart from export and the indentation, JSDoc included.
• The component is typed with it. main.tsx's Render takes UIRenderProps<Data> and returns React.ReactElement | null, written out.
• Before, nothing tied the two together. The component's props were a separate, looser type, RenderProps, with every key unknown.

npm run gen-ts is now a script

scripts/gen-ts.js runs tsc on tsconfig.build.json, which now extends the typecheck config. tsc emits the declarations of the program rooted at main.tsx into a staging directory. The script publishes two files:

• dist/contract.d.ts, the contract's declaration, as tsc wrote it;
• dist/index.d.ts, written from main.tsx's declaration. It holds the component renamed UIRender, a namespace that re-exports each contract type with export import, and export =.

The script writes the second file itself because export = cannot be in the source: Babel rejects it. It also deletes any other dist/*.d.ts. webpack keeps declaration files across its clean, so the old dist/UIRender.d.ts would otherwise have shipped.

The script refuses what must not be published:

• an import other than react and the contract, since a host's compiler would have to resolve it;
• a value in the contract, since the runtime exports nothing but the component;
• a default export that is not a function. A namespace of types merges with a function and not with a const; I measured it, and the const form fails with TS2451;
• anything else in main.tsx's declaration.

scripts/__tests__/gen-ts.contract.test.js is new, with 15 tests. It pins each refusal on a declaration written in the test, without running tsc. It also counts the real contract's 27 types, so adding a public type shows up in review.

The checker now holds the engine to the contract where they meet

• MetaProblem.severity was string in the validator. It is now the two values the validator produces. Loosening it back fails main.tsx, which hands the problems to a host typed against the contract.
• The props reach the engine through one documented cast. The contract keeps a host's Data open, while the form layer types initialValues as a record. I checked that the cast is needed and that a single as suffices.

Golden diff, against master's declarations

The baseline is master's emitted dist/*.d.ts: the Phase 0.6 contract plus the changes accepted since.

• The same 27 names, on both sides.
• Every type is identical, both by an Eq identity check and by mutual assignability. The two generics were checked at their default and at a sample type.
• The callable is identical, and so is its React.ComponentProps.
• The check is not vacuous. A control that widened one prop failed 7 of the checks, and one that narrowed the return type failed 2.
• Textually, each declaration is the same apart from export. The one intended change is the component's JSDoc. It used to say only that the entry is the function itself; it now also says what the function renders.

Probes on the real source

Each one was reverted, and the files were compared byte for byte afterwards.

• A prop added to Render's signature reached dist/index.d.ts.
• Loosening MetaProblem.severity to string failed the typecheck at main.tsx.
• Loosening items in the contract failed typecheck:contract with TS2578.
• A value exported from the contract stopped gen-ts.

What else moved

• The agreement table is now src/library/contract.agreement.ts. It imports the contract as a module, so npm run typecheck covers it. typecheck:contract runs it alone and extends the same config, so the CI step keeps its name and meaning.
• The contract suite reads the vocabularies from contract.ts.
• dist/contract.d.ts is a required file of the tarball.
• The coverage log no longer reports two failures on every run. Jest could not collect coverage from UIRender.tsx or index.ts, because Babel rejected export =. The agreement file, a compile-time test that never runs, is left out of coverage.
• Docs: CLAUDE.md documents gen-ts and the contract, and docs/UPGRADE-PLAN.md records E4 and closes its items.

Measured

	master	this PR
published declaration files	index.d.ts, UIRender.d.ts	index.d.ts, contract.d.ts
published types	27	27, all identical
consumers, @types/react 16 / 17 / 18 / 19 × interop / CommonJS	8 of 8	8 of 8
corpus, 38 examples: commits at mount / translate calls	107 / 1012	107 / 1012
on an edit: commits / translate calls	27 / 64	27 / 64
DOM after mount and after an edit		identical, all 38
dist/index.js	311,527 bytes	311,539 bytes

The 12 bytes come from main.tsx's restructuring. Both bundles were built from git archive copies in directories of the same name length.

Gates

All exited 0, run on this branch:

• lint:js, lint:css, typecheck, typecheck:contract;
• docs:props:check, docs:views:check, css:fixture:check;
• test:env-flags, build;
• test:coverage, thresholds included;
• test:pack, test:pack:peers, test:types;
• test:react16, test:react17, test:react19, 2857 tests each, with no worker crash;
• test:e2e, 41 tests;
• the manifest contract.

The suite grew by the generator's 15 tests, from 2842 to 2857.

🤖 Generated with Claude Code