An open source design system that's fully customizable and agent ready
TypeScript
spec(template-authoring): motion and gesture examples swap docs-only showcase elements for generic ones when distributed (#9419)
Cindy Zhang3f19de5d3276
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.mdindex 86317b9391..ad20fbdd18 100644--- a/docs/architecture/template-authoring.md+++ b/docs/architecture/template-authoring.md@@ -150,9 +150,12 @@ authoring check; it does not replace runtime catalog validation.own `AppShell` and global navigation because demonstrating that chrome is itspurpose. The contributor guide owns the exact root-component recipe.- **INV8 — Copying is a self-contained snapshot.** The emitted source belongs to the- adopting project. Repository-only demo assets are replaced during copy so the- scaffold does not depend on Astryx preview hosting. Later catalog updates do not- mutate copied projects.+ adopting project. Repository-only demo assets and demo-content elements are+ replaced with generic placeholders during copy; `template copy` and the+ docsite's shadcn Install item are copies. `template show` returns the same+ source a copy writes. Other example source handed out without a copy+ replaces only demo-content elements. Live previews render the originals.+ Later catalog updates do not mutate copied projects.- **INV9 — Catalog values may evolve.** Template ids, labels, metadata, categories,example data, and starter source are mutable catalog data under`spec:AST-017/DEC-2`.@@ -218,6 +221,23 @@ This record does not absorb adjacent facts:runtime template envelope.- `packages/cli/foundation/discovery/template-adapter.mjs` — current source loaders,normalization, projections, and shared template IO.+- `replaceDemoMedia` in `template-adapter.mjs` — the INV8 replacement step that+ copy and displayed code share. It replaces `/template-assets/` media URLs. In+ motion and gesture examples, where a real Astryx component wraps docs-only+ contents, such as `<Card><PlayingCardContents /></Card>`, it also replaces each+ demo-content element with a generic placeholder and keeps the outer+ component. A demo-content element is an element imported from the one+ repository-only demo-content module; the step drops that import. The module+ and the import rule are internal mechanism, not a public contract+ (`architecture:knowledge-contracts/INV18`); `spec:AST-028` FR13 states the+ outcome. `template copy`, `template show`, and the docsite's shadcn Install+ item run both passes; the copy receipt and the `template show` response+ report the element count as `demoContentReplaced`. The docsite Code tab, Open+ in Playground, the Sandbox code view, the docsite MCP server's `get()`, and+ `astryx component <Name> --showcase` run only the element pass, so they keep+ their fixture media (`spec:AST-033` FR23). Implementation gap:+ the demo-content module, the element pass, and `demoContentReplaced` are not+ built, and the shadcn Install item runs neither pass.- `packages/cli/foundation/config/project.mjs` — project diagnostics and currentintegration-template re-collection.- `packages/cli/api/template/` — list, show, skeleton, and copy operations.@@ -234,14 +254,15 @@ This record does not absorb adjacent facts:## Verification-| Scope | Current evidence | Missing before `current` |-| ------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |-| Source shapes and integration parsing | `parse.test.mjs`, `template-suffix.test.mjs`, `template-integration.test.mjs` | One corpus check that runs every shipped page and block through the normalized boundary |-| Catalog membership and diagnostics | `template-adapter.test.mjs`, `project.test.mjs` | One catalog implementation; no duplicate collection; every invalid source reported consistently |-| `init` projection | `init.test.mjs` | Selection of every named built-in page from the catalog instead of a directory scan |-| Docsite and sandbox projections | `data-extraction.test.ts`, generated registry checks | Membership parity and live-preview coverage derived from catalog metadata |-| Copy boundary | `template.test.mjs`, `template-suffix.test.mjs` | Mutation coverage for preview-only asset removal and snapshot independence |-| Rubric evidence | Versioned scorecards carrying `commit` and `rubricVersion` | None for architecture; scores remain audit evidence rather than authority |+| Scope | Current evidence | Missing before `current` |+| ------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Source shapes and integration parsing | `parse.test.mjs`, `template-suffix.test.mjs`, `template-integration.test.mjs` | One corpus check that runs every shipped page and block through the normalized boundary |+| Catalog membership and diagnostics | `template-adapter.test.mjs`, `project.test.mjs` | One catalog implementation; no duplicate collection; every invalid source reported consistently |+| `init` projection | `init.test.mjs` | Selection of every named built-in page from the catalog instead of a directory scan |+| Docsite and sandbox projections | `data-extraction.test.ts`, generated registry checks | Membership parity and live-preview coverage derived from catalog metadata |+| Copy boundary | `template.test.mjs`, `template-suffix.test.mjs` | Mutation coverage for preview-only asset removal and snapshot independence |+| Demo-content replacement | None; not built | Copy, `template show`, shadcn Install item, Code-tab, Open in Playground, Sandbox code-view, MCP `get()`, and `--showcase` output contain no demo-content element or demo-content import; copy receipt and `template show` count the elements; the shadcn Install item contains no `/template-assets/` reference; the surfaces that only hand out source keep their fixture media; a live preview renders the original |+| Rubric evidence | Versioned scorecards carrying `commit` and `rubricVersion` | None for architecture; scores remain audit evidence rather than authority |## Shipped-catalog auditdiff --git a/docs/specs/AST-028/spec.md b/docs/specs/AST-028/spec.mdindex c7acbdee15..66bed95096 100644--- a/docs/specs/AST-028/spec.md+++ b/docs/specs/AST-028/spec.md@@ -34,7 +34,10 @@ not production content or a supported consumer asset library.This contract owns static demonstration assets used by templates, includingimages, posters, and videos. It covers their authored references, maintainer-previews, copied output, and fallbacks.+previews, copied output, and fallbacks. It also owns demo-content elements:+repository-only elements that stand in for docs-only demo contents, such as a+playing-card face, that a real Astryx component wraps in a motion or gesture+example.It does not own icons. Icons may be component props, registry values, importedmodules, inline symbols, or product assets, and their conversion and portability@@ -113,6 +116,34 @@ concerns require a separate contract.tell the consumer when Astryx demonstration media was replaced and identify thegenerated file or replacement points they need to customize. The receipt MUSTnot imply that production-ready media was installed.+- **FR13 — Demo-content elements are replaced during copy.** In a motion or+ gesture example, a real Astryx component MAY wrap docs-only demo contents,+ such as `<Card><PlayingCardContents /></Card>`. A demo-content element is a+ repository-only element that stands in for those contents. Every copy MUST+ replace repository-only demo assets (FR7–FR10) and every demo-content element+ with generic placeholders, keeping the outer component and its props, and the+ copied source MUST NOT reference the repository-only code that defines a+ demo-content element. The copies are `template copy` and the docsite's shadcn+ Install item, which writes the example into the consumer's project. The copy+ receipt (FR11) MUST count the replaced elements as `demoContentReplaced`; the+ shadcn Install item's receipt is the `.astryx/<item>.json` file it already+ installs, which MUST carry `demoMediaReplaced` and `demoContentReplaced`.+ `template show` returns the same source a copy writes and MUST report+ `demoContentReplaced` in its response, as it reports `demoMediaReplaced`.+ Surfaces other than these copies and `template show` that hand out example+ source without writing it into a project replace only demo-content elements+ and keep their fixture media:+ `astryx component <Name> --showcase`, which prints the component's showcase+ source, and the docsite surfaces of `spec:AST-033` FR23. Live previews render+ the originals (FR4). A check MUST fail when copied, shown, or handed-out+ output still references a demo-content element or the code that defines it.+ How a demo-content element is marked and replaced belongs to+ `architecture:template-authoring`. Implementation gap: the element+ replacement and `demoContentReplaced` in the copy receipt and the+ `template show` response are not built; `--showcase` prints the showcase file+ as read from disk; the shadcn Install item installs block source as read from+ disk, with its fixture media, and discloses no replacement (Current-state+ impact).### Boundary with icons@@ -138,20 +169,28 @@ previously unwritten requirements for why assets are fixtures, which referencesmay be transformed, what a safe fallback means, how unsupported formats fail,and why icons are separate.+Demo-content elements (FR13) are not built: the copy and show paths replace no+elements, and neither the copy receipt nor the `template show` response has a+`demoContentReplaced` count. `astryx component <Name> --showcase` prints the+showcase file as read from disk. The shadcn Install item installs block source+as read from disk, so it writes `/template-assets/` references into the+consumer's project and discloses no replacement.+This specification-only change alters no package, template, asset, preview,runtime, or public CLI behavior. Remaining implementation and verificationfollow separately.## Verification-| Contract | Verification | Representative cases | Failure expectation |-| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |-| FR1–FR3 | Template-source and copy-boundary tests | built-in page, block, integration template; Astryx fixture; consumer path; third-party URL | Copied source retains a preview runtime dependency or rewrites consumer-owned content |-| FR4–FR6 | Real preview request and rendered-media checks | local, docsite, main sandbox, PR preview; image and video; missing fixture | Representative media 404s, resolves to another file, or silently uses the wrong kind |-| FR7–FR8 | End-to-end CLI copy tests | image-only, video-only, and no-media template | Generated source retains `/template-assets/` or does not parse/render without setup |-| FR9–FR10 | Classifier and mixed-source mutation tests | upper/lower case; multi-dot filename; image poster plus video; unknown suffix | Last suffix is misread, image data enters video, or an unsupported kind is guessed |-| FR11 | Human and structured copy-receipt tests | no replacement; one image; mixed media | The consumer is not told what must be replaced or is told assets were installed |-| FR12 | Scope guard tests and review | Icon prop, registry icon, imported SVG component, static hero image | Icon behavior is silently folded into the static-fixture transformer |+| Contract | Verification | Representative cases | Failure expectation |+| -------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | Template-source and copy-boundary tests | built-in page, block, integration template; Astryx fixture; consumer path; third-party URL | Copied source retains a preview runtime dependency or rewrites consumer-owned content |+| FR4–FR6 | Real preview request and rendered-media checks | local, docsite, main sandbox, PR preview; image and video; missing fixture | Representative media 404s, resolves to another file, or silently uses the wrong kind |+| FR7–FR8 | End-to-end CLI copy tests | image-only, video-only, and no-media template | Generated source retains `/template-assets/` or does not parse/render without setup |+| FR9–FR10 | Classifier and mixed-source mutation tests | upper/lower case; multi-dot filename; image poster plus video; unknown suffix | Last suffix is misread, image data enters video, or an unsupported kind is guessed |+| FR11 | Human and structured copy-receipt tests | no replacement; one image; mixed media | The consumer is not told what must be replaced or is told assets were installed |+| FR12 | Scope guard tests and review | Icon prop, registry icon, imported SVG component, static hero image | Icon behavior is silently folded into the static-fixture transformer |+| FR13 | End-to-end CLI copy, show, and `--showcase` tests, a shadcn install test, and a real preview check | a motion or gesture example whose `Card` wraps one demo-content element; one with two; an example with none; its `template show` response; its `--showcase` output; its shadcn install into a project and its `.astryx/<item>.json` receipt; its live preview | Copied, shown, or installed output still references a demo-content element, the code that defines it, or `/template-assets/`; `--showcase` output references a demo-content element or changes its fixture media; the outer component or its props change; the copy receipt or the `template show` response omits or miscounts `demoContentReplaced`; the live preview stops rendering the original; or the shadcn install receipt lacks `demoMediaReplaced` or `demoContentReplaced` |### Completion criteria@@ -162,7 +201,9 @@ This spec moves from `accepted` to `shipped` only when:- copied templates retain no Astryx preview-only media reference;- image, poster, and video fallbacks are kind-safe and covered end to end;- unsupported static fixture formats fail with an actionable reference;-- copy receipts identify replaced demonstration media; and+- copy receipts identify replaced demonstration media;+- copied and installed templates retain no demo-content element or reference+ to the code that defines it, and the receipt counts the replaced elements; and- icon sources are proven outside this transform and linked to a separatecontract before any icon conversion is introduced.@@ -201,12 +242,33 @@ repository-only fixture URLs in generated projects.**Decider:** `cixzhang`, `2026-09-04`-This contract covers static image and video fixtures only. Icons have distinct+This contract covers static image and video fixtures and the demo-content+elements of DEC-4; it does not cover icons. Icons have distinctsemantic, import, registry, and conversion concerns; grouping them with demomedia would silently decide another public boundary.Rejected: classifying every SVG or image-like source as a template fixture.+### DEC-4 — Demo-content elements are fixtures that copy replaces++**Reference:** `spec:AST-028/DEC-4`++**Decider:** `cixzhang`, `2026-11-01`++Motion and gesture examples can show docs-only demo contents, such as a+playing-card face, inside a real Astryx component without a second copy of each+example to maintain. Those contents are fixtures in the DEC-1 sense: copy+replaces each demo-content element with a generic placeholder and keeps the+outer component, and previews render the originals (DEC-2). The shadcn Install+item writes the example into the consumer's project, so it is a copy and+replaces fixture media and demo-content elements as `template copy` does.+`template show` returns the same source a copy writes; other surfaces that+only hand out source replace demo-content elements alone. Examples without+demo-content elements keep their source, except that their shadcn install+replaces fixture media like any copy (FR7).++Rejected: a docs-only duplicate of each example, which adds documents to keep in sync.+## Open questionsNone.diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.mdindex 4f07c6fd94..8c53d10c12 100644--- a/docs/specs/AST-033/spec.md+++ b/docs/specs/AST-033/spec.md@@ -275,6 +275,29 @@ for each bug.examples. Test fixture posts under `src/content/blog/fixtures/` are servedon the canary only and never listed in the blog index, feed, or sitemap.+### Example code++- **FR23 — Example source replaces demo contents the way copy does.** In a+ motion or gesture example, a real Astryx component may wrap docs-only demo+ contents, such as `<Card><PlayingCardContents /></Card>`. The live example+ renders the original. Every surface that hands out the example's source+ carries it after the demo-content element replacement of `spec:AST-028`+ FR13: each demo-content element becomes a generic placeholder, the source+ keeps no reference to the code that defines it, and the outer component keeps+ its props and behavior. Surfaces that only hand out source run that+ replacement alone, so each keeps its fixture media:+ the Code tab and its copy action; Open in Playground, which opens and runs+ that replaced source, so the playground shows the placeholder; the Sandbox+ code view and its Copy source action; and the MCP server's `get()`, whose+ component result carries the showcase example's source and one more+ example's source and whose template result carries the template's example+ sources or, without them, its page source. The shadcn Install item writes+ the example into the consumer's project, so it is a copy under+ `spec:AST-028` FR13 and its registry item carries the source with fixture+ media and demo-content elements both replaced. Implementation gap: not+ built; each surface carries block source as read from disk (Current-state+ impact).+### Authority routing`architecture:knowledge-contracts` owns public-delta routing and change disposition.@@ -325,7 +348,11 @@ Known conformance gaps remain implementation work:source, type, tab, view, and toggle-value fields, and nested template-previewactivation can reach the same semantic action twice;- existing interaction tests do not yet cover the complete primary-selection,- Back/Forward, close, cancellation, and supersession matrix.+ Back/Forward, close, cancellation, and supersession matrix; and+- the Code tab, Open in Playground, the Sandbox code view, the MCP server's+ `get()`, and the shadcn Install item carry block source as read from disk,+ with no demo-content element replacement, and the shadcn Install item also+ keeps its fixture media (FR23).Stable Storybook and Sandbox currently use a split deployment: pull-requestpreviews are staged inside the Vercel Docsite, while stable main is rebuilt and@@ -340,16 +367,17 @@ exact source already serving those public surfaces.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |-| FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree |-| FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history |-| FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |-| FR13–FR15 | analytics schema and interaction tests with transport spies | navigation intent, successful/failed copy, cancel, URL restoration, render/effect, duplicate activation | event names/properties drift, free-form/high-cardinality data is logged, a passive lifecycle emits, success logs on failure, or one action emits twice |-| FR16 | production-browser playground isolation and recovery tests | direct load, reload, hostile navigation, storage and parent-DOM denial | preview code reaches parent/storage or trusted recovery restores stale source/theme |-| FR17–FR21 | exact-head Vercel build, route/asset probes, metadata checks, and Pages landing contract | production and PR Preview; Storybook manager/frame; Sandbox route/embed; old root/deep path; desktop/mobile; light/dark | one app is absent or stale, a direct asset/route fails, metadata claims the wrong owner, identity drifts, or Pages hosts more than the compatibility page |-| FR22 | `e2e/blog-live-examples.spec.ts` (real-browser post, plain-text route, feed, sitemap, and index checks) and `blog-live-examples.test.tsx` (fence rule, static fallback, fixture listing, runner) | a post with a `tsx live` block; that post's plain-text route; a block importing a post-local asset; a block that fails to compile or throws; live fences in a blockquote, a list item, and quoted inside a longer fence | the live block does not run in the browser, the text route shows anything but the source fallback for a fence the page runs, a post-local import fails to resolve, a broken example breaks the page outside its frame, or the feed, sitemap, or index lists the fixture |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |+| FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree |+| FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history |+| FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |+| FR13–FR15 | analytics schema and interaction tests with transport spies | navigation intent, successful/failed copy, cancel, URL restoration, render/effect, duplicate activation | event names/properties drift, free-form/high-cardinality data is logged, a passive lifecycle emits, success logs on failure, or one action emits twice |+| FR16 | production-browser playground isolation and recovery tests | direct load, reload, hostile navigation, storage and parent-DOM denial | preview code reaches parent/storage or trusted recovery restores stale source/theme |+| FR17–FR21 | exact-head Vercel build, route/asset probes, metadata checks, and Pages landing contract | production and PR Preview; Storybook manager/frame; Sandbox route/embed; old root/deep path; desktop/mobile; light/dark | one app is absent or stale, a direct asset/route fails, metadata claims the wrong owner, identity drifts, or Pages hosts more than the compatibility page |+| FR22 | `e2e/blog-live-examples.spec.ts` (real-browser post, plain-text route, feed, sitemap, and index checks) and `blog-live-examples.test.tsx` (fence rule, static fallback, fixture listing, runner) | a post with a `tsx live` block; that post's plain-text route; a block importing a post-local asset; a block that fails to compile or throws; live fences in a blockquote, a list item, and quoted inside a longer fence | the live block does not run in the browser, the text route shows anything but the source fallback for a fence the page runs, a post-local import fails to resolve, a broken example breaks the page outside its frame, or the feed, sitemap, or index lists the fixture |+| FR23 | Output checks for each surface plus real-browser live-example check | a motion or gesture example whose `Card` wraps a demo-content element; its Code tab and copied text; its Open in Playground source; its Sandbox code view and copied source; its MCP `get()` component and template results; its shadcn registry item and the `.astryx/<item>.json` receipt it installs; an example with fixture media; its live preview | any of those surfaces still references a demo-content element or the code that defines it; the outer component or its props change; fixture media changes on a surface that only hands out source; the shadcn registry item still references `/template-assets/`, or its installed receipt lacks `demoMediaReplaced` or `demoContentReplaced`; or the live preview stops rendering the original |## Decision log@@ -475,6 +503,22 @@ and outside every package and catalog.Rejected: a second blog-only renderer that would need its own isolation.+### DEC-10 — Example code replaces demo contents the way copy does++**Reference:** `spec:AST-033/DEC-10`+**Decider:** `cixzhang`, `2026-11-01`++Motion and gesture examples may show docs-only demo contents, such as a+playing-card face, inside a real Astryx component, without a second copy of+each example to maintain. Every surface that hands out example source runs the+CLI copy's demo-content element replacement (`spec:AST-028/DEC-4`), so the demo+contents a person or agent reads, copies, opens, or installs are the generic+placeholders a CLI copy writes. Surfaces that only hand out source run no other+copy step. The shadcn Install item writes into the consumer's project, so it is+a copy and also replaces fixture media.++Rejected: a docs-only duplicate of each example, which adds documents to keep in sync.+## Open questionsNone.