M1 PR-2: dspack surface → A2UI emitter + library exports

[ryandmonk]

What this is

PR-2 of Milestone 1 (governed generation vertical slice; depends on aestheticfunction/dspack#9 for the v0.3 spec, though this repo carries its own contract copy). This repo becomes consumable as the A2UI emitter target of the pipeline.

Contents

• Input contract → dspack v0.3: same governance blocks as the spec repo's example (1 intent, 3 rules, worked ex.delete-account-confirmation example). Catalog emission verified byte-identical — the transformer ignores unknown blocks per dspack conformance rules (only report timestamps changed).
• src/targets/a2ui/surface.ts — dspack surface (CSR, surface schema v0.1) → A2UI v0.9 messages (createSurface with dspack-token theme + flat updateComponents). All projection knowledge is data in the profile (surfacePlan directives); the engine has no component-name-specific code (matches the existing engine+profile architecture — no engine changes). Compound composition flattens per the documented MAPPING.md casualties; A2UI's required declarative actions are synthesized with deterministic event slugs; every synthesis/drop is a recorded warning — nothing silent.
• CLI --emit-surface — emits and instance-validates (gate A3) against the freshly generated catalog; exit 4 on unknown component / unprojectable structure.
• Library exports — transform, emitSurface, validateCatalog, extractInstances, shadcnProfile via an exports map; tsc build with declarations; no npm publish in M1 (per revised plan): dspack-gen consumes a pinned git dependency; boundary verified by a pack-and-install test.
• Gate naming: README documents A1/A2/A3 as the emitter-side names for the existing three ajv gates (S1–S3 run upstream in dspack-gen).

Acceptance (machine-verifiable)

npm test          # 30 tests: A1–A3 pass over the emitted worked example (both A2UI versions),
                  # AlertDialog flattening golden, unknown component → typed error,
                  # missing title → A3 FAILS (gate proven non-vacuous), determinism
npm run test:pack # npm pack → install into temp project → import smoke via exports map only
npm run transform -- --in input/shadcn-ui.dspack.json --a2ui-version 0.9.1 --out out \
  --emit-surface surface/delete-account.dsurface.json   # exit 0; bad CSR → exit 4

All run in CI (.github/workflows/test.yml, new — this repo previously had no workflow).

Hand-review focus

SurfacePlanDirectives in src/transform/profiles.ts (the public projection vocabulary) and the emitSurface signature — the rest is gate-verified.

ADRs: 2 (CSR compiled down by emitters), 4 (emitter repo + git-dep consumption), 5 (v0.9 envelope; instances validate against both catalogs).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes dspack-to-a2ui consumable as an A2UI emitter library and adds a new dspack surface (CSR) → A2UI v0.9 message emitter, including CLI support, tests, packaging boundary checks, and CI to verify the milestone’s machine-checkable gates.

Changes:

• Add emitSurface (dspack surface v0.1 → A2UI v0.9 createSurface + flat updateComponents) driven by profile surfacePlan directives.
• Expose a stable public library API via src/index.ts + package.json exports, and enable TS declaration output.
• Add acceptance tests + pack/install smoke test + GitHub Actions workflow to run gates and surface emission.

Reviewed changes

Copilot reviewed 12 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.json	Enables declaration output to support library consumption.
surface/delete-account.dsurface.json	Adds a concrete dspack-surface v0.1 input used for surface emission.
src/types.ts	Introduces DspackSurface / SurfaceNode types for the new surface protocol.
src/transform/profiles.ts	Adds surface projection vocabulary (surfaceSynthesis, surfacePlan) to profiles and wires it into shadcnProfile.
src/targets/a2ui/surface.ts	Implements the surface emitter, warnings, and deterministic ID/event synthesis.
src/surface-emit.test.ts	Adds emitter-focused tests: projection behavior, determinism, failure modes, and gate validation.
src/index.ts	Defines the public library surface and re-exports emitter + validation APIs.
src/cli.ts	Adds --emit-surface flow (emit + instance-validate against generated catalog; exit code 4 on failure).
scripts/pack-test.sh	Adds pack-and-install boundary test for exports-only consumption.
README.md	Documents emitter gates naming and how to run surface emission via CLI.
package.json	Adds exports map + build/prepare/test:pack scripts; updates package name/description.
out/validation-report.v1_0.json	Updates generated timestamp in emitted validation report artifact.
out/validation-report.v0_9_1.json	Updates generated timestamp in emitted validation report artifact.
out/delete-account.surface.json	Adds emitted surface output artifact for the worked example.
input/shadcn-ui.dspack.json	Updates contract to dspack v0.3 and embeds intents/rules/worked surface example.
.github/workflows/test.yml	Adds CI to run tests, transform emission, and pack/install boundary checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.