Provider and Contract Handoffs

The package-only handoffs of the owned UI pack and the component contract.

Keep the handoffs distinct

The owned UI pack and the component contract are different release identities. The pack supplies the runtime component set and CSS; the contract supplies the framework-neutral package API that a host and a pack share. Both live in this repository and each leaves it through its own package-only handoff. Do not substitute one handoff for the other.

The UI-pack handoff

ui-handoff.json records the package-only external handoff:

The package metadata version, pack protocol version and package commit answer different questions. None can stand in for the immutable package commit. Inside this monorepo the pack is a workspace:* development dependency; the tool never lists it as a runtime or peer dependency and never bundles it.

Updating the UI pack

An update is a new package-only commit:

1. Change packages/ui and regenerate the pack with corepack pnpm ui:pack.

2. Create a commit whose tree equals HEAD:packages/ui, parented on the previous package commit so package/ui-v1 fast-forwards, and push that ref.

3. Record the full SHA in scripts/ui-pack-identity.mjs and everywhere else git grep <previous SHA> finds it, so that grep then returns nothing, and run corepack pnpm ui:external-install -- --exact. styleguide/sample/pnpm-lock.yaml is one of those places and the one that is never hand-edited: its entry carries a tarball integrity hash that changes with the SHA, so update styleguide/sample/package.json and let corepack pnpm -C styleguide/sample install rewrite the lockfile.

4. Run the full unit, artifact, and browser gates, including the 12-component runtime/CSS/focused-WASM proof.

External hosts must never resolve the pack through a branch or moving tag, sibling checkout, workspace:, file:, link:, or path: relationship, copied source, or a pnpm Git subdirectory selector. The tool never falls back to the pack: a host themeset remains swappable through the host's package pack value and stylesheet import.

The component-contract handoff

contract-handoff.json records the package-only external handoff:

Inside this monorepo the contract source is intentionally a workspace:* development dependency. The published zudo-composer manifest declares it as the ^1.0.0 peer so an installed host supplies one contract instance. That local workspace relationship is not an external handoff and must not be copied into a consumer's package-only install.

Verify the handoffs and negative scans

Run the focused gates when changing either package:

corepack pnpm contract:conformance
corepack pnpm contract:negative-scan
corepack pnpm contract:external-install -- --exact
corepack pnpm ui:external-install -- --exact

contract:conformance checks the versioned package's exports, built runtime and declarations, packed file allowlist, and consumer boundary. contract:negative-scan rejects workspace/file/link protocols, sibling or root-workspace preparation, and application dependencies in generic contract sources. The exact external-install proof checks the advertised branch and package tree, creates a package-only temporary consumer with the full Git SHA, performs a frozen install, and imports both the contract and ./fixtures. ui:external-install does the same for @zudo-composer/ui, then checks that the installed files and package.json bytes match packages/ui, that @takazudo/zfb-md-wasm resolves at 5.0.1, and that the pack declares its twelve sidecars.

provider:boundary performs the corresponding pack identity, workspace link, pack/sidecar, and public-source checks on a bare checkout. dist:boundary performs the build-dependent runtime/CSS/WASM checks. A failed gate is a handoff problem to diagnose, not a reason to shorten a SHA or relax a negative scan. The packed-install guide shows how the exact contract is exercised in a real installed host.