An open source design system that's fully customizable and agent ready
TypeScript
spec(docsite): blog posts render runnable example blocks (#9409)
Cindy Zhang2a660f751c85
diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.mdindex 2b76792d0d..a4514fc99e 100644--- a/docs/specs/AST-033/spec.md+++ b/docs/specs/AST-033/spec.md@@ -251,6 +251,25 @@ for each bug.fragment, but the compatibility page MUST NOT automatically redirect, buildeither application, or host CI evidence.+### Blog posts++- **FR22 — Blog posts render runnable example blocks.** A fenced code block in+ a blog post's Markdown whose info string is `tsx live` renders a runnable+ example through the Docsite's existing live-example renderer, the playground+ preview frame (`/playground/preview`), which compiles the block's source in+ the browser and resolves its imports against the generated preview scope.+ The example runs sandboxed so a post cannot break the page: each block gets+ its own frame with the FR16 boundary, an `allow-scripts`-only sandbox with an+ opaque origin, so its styles and scripts stay inside that frame, and a+ compile or runtime error shows inside the frame while the rest of the post+ renders. An example may import published Astryx packages and post-local+ example assets that live beside the post's Markdown file, such as docs-only+ demo components like tarot cards; those assets are not Astryx components,+ are not exported from any package, enter no catalog, and resolve only for+ their own post. The plain-text post route and the RSS feed show a static+ fallback in place of the running example: the block's source as an ordinary+ code block. Implementation gap: not built (Current-state impact).+### Authority routing`architecture:knowledge-contracts` owns public-delta routing and change disposition.@@ -299,9 +318,12 @@ Known conformance gaps remain implementation work:navigation that owns it;- analytics still permits unrestricted string context for item, package, category,source, type, tab, view, and toggle-value fields, and nested template-preview- activation can reach the same semantic action twice; and+ activation 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+- blog posts render every fenced code block as static code: no `tsx live`+ block runs an example, the preview scope holds no post-local assets, and the+ plain-text route and RSS feed have no live-block fallback (FR22).Stable Storybook and Sandbox currently use a split deployment: pull-requestpreviews are staged inside the Vercel Docsite, while stable main is rebuilt and@@ -316,15 +338,16 @@ 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 |+| 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 | real-browser blog post checks plus plain-text route and RSS feed checks | a post with a `tsx live` block; that post's plain-text route and RSS item; a block importing a post-local asset; a block that fails to compile or throws | the live block does not run in the browser, the text route or feed shows anything but the source fallback, a post-local import fails to resolve, or a broken example breaks the page outside its frame |## Decision log@@ -436,6 +459,20 @@ endpoint equal to `astryx search --json` for the site's project.Rejected: a site-owned index or ranking, and a browser copy of the CLI's searchdata that has to track every CLI release.+### DEC-9 — Blog posts run examples in the existing sandboxed renderer++**Reference:** `spec:AST-033/DEC-9`+**Decider:** `cixzhang`, `2026-11-01`++Blog posts support runnable HTML blocks inside the post, so a post can+demonstrate Astryx with demo material that is not an Astryx component, such as+tarot cards. A `tsx live` fence runs through the playground preview frame and+its FR16 isolation, so a post example and a playground session share one+renderer and one sandbox boundary. Post-local demo assets stay beside the post+and outside every package and catalog.++Rejected: a second blog-only renderer that would need its own isolation.+## Open questionsNone.