Decision record for dunezone public Storybook content and isolation boundary

storybook-public-content-boundary.md

SUPERSEDED: The all-364 content decision in this record is no longer current. The content-boundary ticket was reopened after distinguishing reusable component capability stories from legacy per-output capture specimens. See ndelangen/dunezone#141

Public Storybook content and isolation boundary

Decision for dunezone issue #141, approved 2026-07-27.

Content boundary

• The production Storybook is exhaustive: every story present in the built Storybook index is public and must pass the release contract.
• The current baseline is all 364 indexed stories. Intentional empty, loading, unauthenticated, and error-state stories remain valid stories when their state is fixture-driven and renders without runtime failure.
• Excluding a story is not an accepted workaround for a broken dependency. A story leaves the public catalogue only when the story itself is intentionally removed in a normal reviewed product change.
• Private production data, secrets, authenticated browser state, and live backend state are forbidden in stories and fixtures.

Convex and authentication boundary

• Static Storybook output must not contain the real Convex React or browser client, a production Convex deployment URL, .convex.cloud, .convex.site, or a live authentication endpoint.
• Storybook globally registers convex/react and convex/browser through Storybook module mocking.
• Those registrations resolve to explicit manual package mocks under __mocks__/convex/; bare automatic sb.mock is insufficient because Convex exposes export * entry points that Storybook cannot safely automock in browser mode.
• The manual mocks retain no URL and cannot perform network I/O. Unconfigured queries render a loading state; unconfigured mutations, actions, and direct client operations throw immediately.
• Connected stories configure mocked hooks with local fixture behavior. Application components continue importing Convex normally and require no Storybook-only component variant.
• The manual mock exposes only reviewed Convex APIs. A newly imported named API must be added explicitly; otherwise the Storybook build must fail.
• Authentication state is simulated locally. Storybook must never depend on a real login, cookie, token, session, or provider callback.

Prototype evidence: branch, commit, and validation comment.

Resource and runtime boundary

• All resources required to render a story, including fonts, images, vectors, styles, scripts, and data fixtures, must be served from the same dune.zone release. External resource requests are forbidden.
• Every required resource must resolve successfully. Missing assets, malformed URLs, HTTP 4xx/5xx responses, failed requests, and broken image/font loads are release blockers.
• Console errors, unhandled promise rejections, and uncaught runtime exceptions are release blockers.
• Expected visual error states are allowed only when they are rendered intentionally as component content without producing a console or runtime failure.
• Initial story output must be deterministic. Fixtures use fixed values; ambient time, random values, production state, and request ordering may not change the initial render.

Release proof

A production release must fail unless all of the following pass:

1. Build Storybook successfully for its /__storybook/ public base path.
2. Assemble the complete static output into the same atomic Worker release as the application.
3. Scan emitted text assets for forbidden Convex/auth deployment hosts and the known production deployment identifiers.
4. Read the built Storybook index and browser-load every indexed story; no handwritten allowlist or sampled subset is sufficient.
5. For every story, verify that it reaches a settled rendered state with no failed request, HTTP 4xx/5xx response, console error, unhandled rejection, or runtime exception.
6. Reject every cross-origin render-time resource request. Ordinary user-initiated navigation links, such as the GitHub footer link, are not render-time resources and are outside this check.
7. Verify every referenced same-origin asset exists in the assembled release and works beneath the production routing contract.
8. Run the deterministic-render check with animations disabled and fixed browser settings; repeated initial captures of each story must agree.
9. Assert that the checked story count equals the number of story entries in the built index and report that count in CI.

The contract has no temporary exclusions. Any discovered failure is repaired or the production release is blocked.