An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): host stable apps in production (#6763)
Cindy Zhang9f3908b6572e
diff --git a/.github/scripts/visual-gate/workflow-concurrency.test.mjs b/.github/scripts/visual-gate/workflow-concurrency.test.mjsindex f4edb7e680..43cdb0ed2a 100644--- a/.github/scripts/visual-gate/workflow-concurrency.test.mjs+++ b/.github/scripts/visual-gate/workflow-concurrency.test.mjs@@ -155,7 +155,7 @@ describe('PR report and deployment workflow contracts', () => {);});- it('stages both static apps on Vercel while retaining separate Pages publication', () => {+ it('stages both static apps in Vercel preview and production while retaining separate Pages publication', () => {const config = JSON.parse(fs.readFileSync(path.join(ROOT, 'apps/docsite/vercel.json'), 'utf8'),);@@ -169,8 +169,9 @@ describe('PR report and deployment workflow contracts', () => {path.join(ROOT, 'apps/docsite/scripts/build-previews.mjs'),'utf8',);- expect(builder).toContain("deploymentEnv !== 'preview'");- expect(builder).toContain('buildPreviews(deploymentEnv, root');+ expect(builder).toContain("new Set(['preview', 'production'])");+ expect(builder).toContain('export function buildPreviews(');+ expect(builder).toContain('VERCEL_GIT_COMMIT_SHA');expect(builder).toContain("'@astryxdesign/storybook'");expect(builder).toContain("'@astryxdesign/sandbox'");expect(builder).toContain("SANDBOX_BASE_PATH: '/sandbox'");diff --git a/apps/docsite/.gitignore b/apps/docsite/.gitignoreindex 3b7cdf4ff8..ce61231a97 100644--- a/apps/docsite/.gitignore+++ b/apps/docsite/.gitignore@@ -13,9 +13,10 @@ public/playground-types.jsonpublic/monaco/public/vendor/-# Vercel stages both static previews beside preview/canary docs, never in source control.+# Vercel stages both static apps and deployment identity during builds, never in source control.public/storybook/public/sandbox/+public/version.json# Auto-generated by `astryx theme build` (pnpm build:theme). The theme source# lives at src/themes/astryxTheme.ts; the built JS/CSS/d.ts files arediff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjsindex fd5135a535..f107aa82c8 100644--- a/apps/docsite/next.config.mjs+++ b/apps/docsite/next.config.mjs@@ -20,13 +20,17 @@ const playgroundCookieCompatibility = readFileSync('utf8',);+const stagesStaticApps =+ process.env.VERCEL_ENV === 'preview' ||+ process.env.VERCEL_ENV === 'production';+/** @type {import('next').NextConfig} */const nextConfig = {cacheComponents: true,// Sandbox exports trailing-slash directories; Next's automatic slash- // redirect runs before rewrites. Only preview/canary needs to preserve- // those URLs. Production docs keep their existing canonical redirects.- skipTrailingSlashRedirect: process.env.VERCEL_ENV === 'preview',+ // redirect runs before rewrites. Vercel deployments preserve those URLs;+ // local builds keep the docsite's existing canonical redirects.+ skipTrailingSlashRedirect: stagesStaticApps,// A dynamic route segment can't carry a static extension, so the public// plaintext URL /blog/<slug>.txt is served by the /blog/txt/[slug] handler.// Static files (including Storybook's iframe and Sandbox's JS/CSS, embeds@@ -37,7 +41,7 @@ const nextConfig = {afterFiles: [{source: '/blog/:slug.txt', destination: '/blog/txt/:slug'},{source: '/storybook', destination: '/storybook/index.html'},- ...(process.env.VERCEL_ENV === 'preview'+ ...(stagesStaticApps? [{source: '/sandbox', destination: '/sandbox/index.html'},{diff --git a/apps/docsite/scripts/build-previews.mjs b/apps/docsite/scripts/build-previews.mjsindex 73ddfee9b1..bee614dea6 100644--- a/apps/docsite/scripts/build-previews.mjs+++ b/apps/docsite/scripts/build-previews.mjs@@ -1,9 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Build and stage Storybook and Vite Sandbox in the existing Vercel docsite preview.- * @input VERCEL_ENV, Storybook static build, and Sandbox Vite static build.- * @output apps/docsite/public/{storybook,sandbox} only in preview/canary deployments.+ * @file Build and stage Storybook and Vite Sandbox in the Vercel docsite.+ * @input VERCEL_ENV, VERCEL_GIT_COMMIT_SHA, Storybook static build, and Sandbox Vite static build.+ * @output apps/docsite/public/{storybook,sandbox} in preview and production deployments.* @position Build-time staging before the docsite Next.js build; CI retains its own visual artifact.*/@@ -12,34 +12,71 @@ import fs from 'node:fs';import path from 'node:path';import {fileURLToPath} from 'node:url';-export function stageStorybook(source, destination) {+const CANONICAL_ORIGIN = 'https://astryx.atmeta.com';+const DEPLOYED_ENVIRONMENTS = new Set(['preview', 'production']);++function documentMetadata(deploymentEnv, canonicalPath) {+ return deploymentEnv === 'production'+ ? `<link rel="canonical" href="${CANONICAL_ORIGIN}${canonicalPath}" />`+ : '<meta name="robots" content="noindex, nofollow" />';+}++function injectHead(html, markup) {+ const head = html.match(/<head(?:\s[^>]*)?>/i)?.[0];+ if (!head) throw new Error('Static app HTML must contain a head element');+ return html.replace(head, `${head}\n ${markup}`);+}++function htmlFiles(directory) {+ return fs.readdirSync(directory, {withFileTypes: true}).flatMap(entry => {+ const absolute = path.join(directory, entry.name);+ return entry.isDirectory()+ ? htmlFiles(absolute)+ : entry.name.endsWith('.html')+ ? [absolute]+ : [];+ });+}++function sandboxCanonicalPath(destination, file) {+ const relative = path.relative(destination, file).split(path.sep).join('/');+ if (relative === 'index.html') return '/sandbox/';+ if (relative.endsWith('/index.html')) {+ return `/sandbox/${relative.slice(0, -'index.html'.length)}`;+ }+ return `/sandbox/${relative}`;+}++export function stageStorybook(source, destination, deploymentEnv) {const index = path.join(source, 'index.html');if (!fs.existsSync(index) || !fs.statSync(index).isFile()) {throw new Error(`Storybook build has no index.html: ${index}`);}const html = fs.readFileSync(index, 'utf8');- const head = html.match(/<head(?:\s[^>]*)?>/i)?.[0];- if (!head || /<base\b/i.test(html)) {- throw new Error(- 'Storybook index.html must have a head without a base element',- );+ if (/<base\b/i.test(html)) {+ throw new Error('Storybook index.html must not contain a base element');}- // Next.js redirects /storybook/ to /storybook. Fix the base for relative- // manager, iframe, and asset URLs without changing Storybook's CI build.+ // Next.js serves /storybook through index.html. Pin relative manager, iframe,+ // and asset URLs to the stable route. Only the entry is canonical in+ // production; previews and standalone frames stay out of search results.fs.rmSync(destination, {recursive: true, force: true});fs.cpSync(source, destination, {recursive: true});- fs.writeFileSync(- indexPath(destination),- html.replace(head, `${head}\n <base href="/storybook/" />`),- );-}--function indexPath(directory) {- return path.join(directory, 'index.html');+ for (const file of htmlFiles(destination)) {+ const relative = path.relative(destination, file).split(path.sep).join('/');+ const metadata =+ deploymentEnv === 'production' && relative === 'index.html'+ ? documentMetadata(deploymentEnv, '/storybook/')+ : '<meta name="robots" content="noindex, nofollow" />';+ const markup =+ relative === 'index.html'+ ? ['<base href="/storybook/" />', metadata].join('\n ')+ : metadata;+ fs.writeFileSync(file, injectHead(fs.readFileSync(file, 'utf8'), markup));+ }}-export function stageSandbox(source, destination) {+export function stageSandbox(source, destination, deploymentEnv) {for (const relative of ['index.html', '404.html', '404/index.html']) {const file = path.join(source, relative);if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {@@ -47,10 +84,23 @@ export function stageSandbox(source, destination) {}}// The Vite export already uses /sandbox/ for JS, CSS, template assets and- // fullscreen embeds. Copy the physical tree unchanged: missing paths must- // stay missing rather than falling through to an SPA shell.+ // fullscreen embeds. Copy the physical tree unchanged except for discovery+ // metadata: stable routes are canonical and preview routes are noindex.fs.rmSync(destination, {recursive: true, force: true});fs.cpSync(source, destination, {recursive: true});+ for (const file of htmlFiles(destination)) {+ const relative = path.relative(destination, file).split(path.sep).join('/');+ const isRouteIndex =+ relative === 'index.html' || relative.endsWith('/index.html');+ const metadata =+ relative === '404.html' || relative === '404/index.html' || !isRouteIndex+ ? '<meta name="robots" content="noindex, nofollow" />'+ : documentMetadata(+ deploymentEnv,+ sandboxCanonicalPath(destination, file),+ );+ fs.writeFileSync(file, injectHead(fs.readFileSync(file, 'utf8'), metadata));+ }}function runPreviewBuild(run, root, name, args, env = process.env) {@@ -68,7 +118,7 @@ function runPreviewBuild(run, root, name, args, env = process.env) {.join('\n').slice(-12000);throw new Error(- `${name} preview build failed:\n${detail || error.message}`,+ `${name} static build failed:\n${detail || error.message}`,{cause: error,},@@ -76,21 +126,32 @@ function runPreviewBuild(run, root, name, args, env = process.env) {}}-export function buildPreviews(deploymentEnv, root, run = execFileSync) {+export function buildPreviews(+ deploymentEnv,+ root,+ run = execFileSync,+ commitSha = process.env.VERCEL_GIT_COMMIT_SHA,+) {const publicDir = path.join(root, 'apps/docsite/public');const storybookDestination = path.join(publicDir, 'storybook');const sandboxDestination = path.join(publicDir, 'sandbox');- if (deploymentEnv !== 'preview') {- // Release docs must never package an earlier cached preview.+ const versionFile = path.join(publicDir, 'version.json');+ if (!DEPLOYED_ENVIRONMENTS.has(deploymentEnv)) {+ // Local builds must never package an earlier cached deployment.fs.rmSync(storybookDestination, {recursive: true, force: true});fs.rmSync(sandboxDestination, {recursive: true, force: true});+ fs.rmSync(versionFile, {force: true});return;}+ if (!/^[0-9a-f]{40}$/i.test(commitSha ?? '')) {+ throw new Error('Vercel deployment is missing VERCEL_GIT_COMMIT_SHA');+ }- // Remove cached previews before either build: a failed build must not leave- // an older static tree that the subsequent Next build could accidentally ship.+ // Remove cached apps before either build: a failed build must not leave an+ // older static tree that the subsequent Next build could accidentally ship.fs.rmSync(storybookDestination, {recursive: true, force: true});fs.rmSync(sandboxDestination, {recursive: true, force: true});+ fs.rmSync(versionFile, {force: true});runPreviewBuild(run, root, 'Storybook', ['-F','@astryxdesign/storybook',@@ -103,8 +164,20 @@ export function buildPreviews(deploymentEnv, root, run = execFileSync) {['-F', '@astryxdesign/sandbox', 'build'],{...process.env, SANDBOX_BASE_PATH: '/sandbox'},);- stageStorybook(path.join(root, 'apps/storybook/dist'), storybookDestination);- stageSandbox(path.join(root, 'apps/sandbox/out'), sandboxDestination);+ stageStorybook(+ path.join(root, 'apps/storybook/dist'),+ storybookDestination,+ deploymentEnv,+ );+ stageSandbox(+ path.join(root, 'apps/sandbox/out'),+ sandboxDestination,+ deploymentEnv,+ );+ fs.writeFileSync(+ versionFile,+ `${JSON.stringify({commit: commitSha, environment: deploymentEnv})}\n`,+ );}if (diff --git a/apps/docsite/scripts/build-previews.test.mjs b/apps/docsite/scripts/build-previews.test.mjsindex e886a07f6a..f310c7129f 100644--- a/apps/docsite/scripts/build-previews.test.mjs+++ b/apps/docsite/scripts/build-previews.test.mjs@@ -24,6 +24,10 @@ function fixture() {path.join(storybook, 'index.html'),'<html><head></head><body>Storybook</body></html>',);+ fs.writeFileSync(+ path.join(storybook, 'iframe.html'),+ '<html><head></head><body>Story</body></html>',+ );fs.writeFileSync(path.join(storybook, 'assets/manager.js'), 'manager bytes');for (const dir of ['',@@ -32,9 +36,15 @@ function fixture() {'templates/login-sso',]) {fs.mkdirSync(path.join(sandbox, dir), {recursive: true});- fs.writeFileSync(path.join(sandbox, dir, 'index.html'), `<p>${dir}</p>`);+ fs.writeFileSync(+ path.join(sandbox, dir, 'index.html'),+ `<html><head></head><body>${dir}</body></html>`,+ );}- fs.writeFileSync(path.join(sandbox, '404.html'), 'not found');+ fs.writeFileSync(+ path.join(sandbox, '404.html'),+ '<html><head></head><body>not found</body></html>',+ );fs.mkdirSync(path.join(sandbox, 'assets'), {recursive: true});fs.mkdirSync(path.join(sandbox, 'template-assets'), {recursive: true});fs.writeFileSync(path.join(sandbox, 'assets/app.js'), 'app');@@ -42,7 +52,7 @@ function fixture() {fs.writeFileSync(path.join(sandbox, 'template-assets/logo.svg'), '<svg/>');fs.writeFileSync(path.join(sandbox, 'templates/login-sso/embed.html'),- 'embed',+ '<html><head></head><body>embed</body></html>',);return {root, storybook, sandbox, publicDir};}@@ -56,10 +66,16 @@ test('stages complete Storybook under a stable /storybook/ asset base', () => {const destination = path.join(publicDir, 'storybook');fs.mkdirSync(destination, {recursive: true});fs.writeFileSync(path.join(destination, 'stale.js'), 'old');- stageStorybook(storybook, destination);+ stageStorybook(storybook, destination, 'production');+ const index = fs.readFileSync(path.join(destination, 'index.html'), 'utf8');+ assert.match(index, /<base href="\/storybook\/" \/>/);assert.match(- fs.readFileSync(path.join(destination, 'index.html'), 'utf8'),- /<base href="\/storybook\/" \/>/,+ index,+ /<link rel="canonical" href="https:\/\/astryx\.atmeta\.com\/storybook\/" \/>/,+ );+ assert.match(+ fs.readFileSync(path.join(destination, 'iframe.html'), 'utf8'),+ /<meta name="robots" content="noindex, nofollow" \/>/,);assert.equal(fs.readFileSync(path.join(destination, 'assets/manager.js'), 'utf8'),@@ -73,13 +89,8 @@ test('stages physical Sandbox routes, embeds and assets without a fallback', ()const destination = path.join(publicDir, 'sandbox');fs.mkdirSync(destination, {recursive: true});fs.writeFileSync(path.join(destination, 'stale.html'), 'old');- stageSandbox(sandbox, destination);+ stageSandbox(sandbox, destination, 'production');for (const relative of [- 'index.html',- '404.html',- '404/index.html',- 'pages/motion-lab/bugs/index.html',- 'templates/login-sso/embed.html','template-assets/logo.svg','assets/app.js','assets/app.css',@@ -89,6 +100,28 @@ test('stages physical Sandbox routes, embeds and assets without a fallback', ()fs.readFileSync(path.join(sandbox, relative), 'utf8'),);}+ for (const [relative, canonical] of [+ ['index.html', '/sandbox/'],+ ['pages/motion-lab/bugs/index.html', '/sandbox/pages/motion-lab/bugs/'],+ ['templates/login-sso/index.html', '/sandbox/templates/login-sso/'],+ ]) {+ assert.match(+ fs.readFileSync(path.join(destination, relative), 'utf8'),+ new RegExp(+ `<link rel="canonical" href="https://astryx\\.atmeta\\.com${canonical}" />`,+ ),+ );+ }+ for (const relative of [+ '404.html',+ '404/index.html',+ 'templates/login-sso/embed.html',+ ]) {+ assert.match(+ fs.readFileSync(path.join(destination, relative), 'utf8'),+ /<meta name="robots" content="noindex, nofollow" \/>/,+ );+ }assert.equal(fs.existsSync(path.join(destination, 'stale.html')), false);assert.equal(fs.existsSync(path.join(destination, 'unknown/index.html')),@@ -116,7 +149,7 @@ test('rejects incomplete exports before touching staged bytes', () => {fs.mkdirSync(destination, {recursive: true});fs.writeFileSync(path.join(destination, 'index.html'), 'old');fs.rmSync(path.join(source, missing));- assert.throws(() => stage(source, destination), message);+ assert.throws(() => stage(source, destination, 'preview'), message);assert.equal(fs.readFileSync(path.join(destination, 'index.html'), 'utf8'),'old',@@ -124,47 +157,88 @@ test('rejects incomplete exports before touching staged bytes', () => {}});-test('only preview/canary builds create either static tree', () => {+test('stages versioned static apps in preview and production only', () => {+ const commit = '0123456789abcdef0123456789abcdef01234567';+ for (const deploymentEnv of ['preview', 'production']) {+ const {root, publicDir} = fixture();+ const calls = [];+ buildPreviews(+ deploymentEnv,+ root,+ (command, args, options) => {+ calls.push({command, args, options});+ },+ commit,+ );+ assert.deepEqual(+ calls.map(({command, args}) => [command, args]),+ [+ ['pnpm', ['-F', '@astryxdesign/storybook', 'build']],+ ['pnpm', ['-F', '@astryxdesign/sandbox', 'build']],+ ],+ );+ assert.equal(calls[1].options.env.SANDBOX_BASE_PATH, '/sandbox');+ for (const name of ['storybook', 'sandbox'])+ assert.equal(+ fs.existsSync(path.join(publicDir, name, 'index.html')),+ true,+ );+ assert.deepEqual(+ JSON.parse(fs.readFileSync(path.join(publicDir, 'version.json'), 'utf8')),+ {commit, environment: deploymentEnv},+ );+ const storybook = fs.readFileSync(+ path.join(publicDir, 'storybook/index.html'),+ 'utf8',+ );+ if (deploymentEnv === 'production') {+ assert.match(storybook, /rel="canonical"/);+ assert.doesNotMatch(storybook, /noindex/);+ } else {+ assert.match(storybook, /noindex, nofollow/);+ assert.doesNotMatch(storybook, /rel="canonical"/);+ }+ }+const {root, publicDir} = fixture();- const calls = [];- buildPreviews('preview', root, (command, args, options) => {- calls.push({command, args, options});- });- assert.deepEqual(- calls.map(({command, args}) => [command, args]),- [- ['pnpm', ['-F', '@astryxdesign/storybook', 'build']],- ['pnpm', ['-F', '@astryxdesign/sandbox', 'build']],- ],- );- assert.equal(calls[1].options.env.SANDBOX_BASE_PATH, '/sandbox');- for (const name of ['storybook', 'sandbox'])- assert.equal(fs.existsSync(path.join(publicDir, name, 'index.html')), true);- for (const env of ['production', 'development', undefined]) {- buildPreviews(env, root, () => {+ for (const deploymentEnv of ['development', undefined]) {+ buildPreviews(deploymentEnv, root, () => {throw new Error('should not run');});for (const name of ['storybook', 'sandbox'])assert.equal(fs.existsSync(path.join(publicDir, name)), false);+ assert.equal(fs.existsSync(path.join(publicDir, 'version.json')), false);}});-test('Next keeps generated Sandbox route rewrites preview-only and never uses a catch-all', async () => {+test('refuses a deployed build without an exact commit identity', () => {+ const {root} = fixture();+ assert.throws(+ () => buildPreviews('production', root, () => {}, ''),+ /missing VERCEL_GIT_COMMIT_SHA/,+ );+});++test('Next preserves generated Sandbox routes in preview and production without a catch-all', async () => {const configPath = path.resolve(import.meta.dirname, '../next.config.mjs');const previous = process.env.VERCEL_ENV;try {- process.env.VERCEL_ENV = 'preview';- const {default: preview} = await import(`${configPath}?preview`);- assert.equal(preview.skipTrailingSlashRedirect, true);- assert.deepEqual((await preview.rewrites()).afterFiles.slice(-2), [- {source: '/sandbox', destination: '/sandbox/index.html'},- {source: '/sandbox/:path+', destination: '/sandbox/:path+/index.html'},- ]);- process.env.VERCEL_ENV = 'production';- const {default: production} = await import(`${configPath}?production`);- assert.equal(production.skipTrailingSlashRedirect, false);+ for (const deploymentEnv of ['preview', 'production']) {+ process.env.VERCEL_ENV = deploymentEnv;+ const {default: config} = await import(+ `${configPath}?${deploymentEnv}-${Date.now()}`+ );+ assert.equal(config.skipTrailingSlashRedirect, true);+ assert.deepEqual((await config.rewrites()).afterFiles.slice(-2), [+ {source: '/sandbox', destination: '/sandbox/index.html'},+ {source: '/sandbox/:path+', destination: '/sandbox/:path+/index.html'},+ ]);+ }+ process.env.VERCEL_ENV = 'development';+ const {default: development} = await import(`${configPath}?development`);+ assert.equal(development.skipTrailingSlashRedirect, false);assert.equal(- (await production.rewrites()).afterFiles.some(rule =>+ (await development.rewrites()).afterFiles.some(rule =>rule.source.startsWith('/sandbox'),),false,@@ -177,17 +251,27 @@ test('Next keeps generated Sandbox route rewrites preview-only and never uses atest('failed preview builds do not leave cached static trees', () => {const {root, publicDir} = fixture();- buildPreviews('preview', root, () => {});+ buildPreviews(+ 'preview',+ root,+ () => {},+ '0123456789abcdef0123456789abcdef01234567',+ );assert.throws(() =>- buildPreviews('preview', root, (_command, args) => {- if (args[1] === '@astryxdesign/sandbox')- throw Object.assign(new Error('command failed'), {- stdout: 'building',- stderr: 'failed to compile',- });- }),- /Sandbox preview build failed:\nbuilding\nfailed to compile/,+ buildPreviews(+ 'preview',+ root,+ (_command, args) => {+ if (args[1] === '@astryxdesign/sandbox')+ throw Object.assign(new Error('command failed'), {+ stdout: 'building',+ stderr: 'failed to compile',+ });+ },+ '0123456789abcdef0123456789abcdef01234567',+ ),+ /Sandbox static build failed:\nbuilding\nfailed to compile/,);for (const name of ['storybook', 'sandbox'])assert.equal(fs.existsSync(path.join(publicDir, name)), false);diff --git a/apps/docsite/src/components/SiteFooter.tsx b/apps/docsite/src/components/SiteFooter.tsxindex 40aa6cd9fd..f063e5d58a 100644--- a/apps/docsite/src/components/SiteFooter.tsx+++ b/apps/docsite/src/components/SiteFooter.tsx@@ -117,6 +117,8 @@ const FOOTER_LINKS: ReadonlyArray<{{label: 'Templates', href: '/templates'},{label: 'Themes', href: '/themes'},{label: 'Playground', href: '/playground'},+ {label: 'Storybook', href: '/storybook/'},+ {label: 'Sandbox', href: '/sandbox/'},{label: 'Blog', href: '/blog'},{label: 'Community', href: '/community'},{label: 'Changelog', href: '/changelog'},diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.mdindex 9b0bfdb372..16ec57fab7 100644--- a/docs/specs/AST-033/spec.md+++ b/docs/specs/AST-033/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-09-09+approved_at: 2026-09-29phase: acceptedowners: [cixzhang]affects_architecture: []@@ -32,7 +32,13 @@ affects_consumer_docs: [docsite]"FR3","FR8","FR13",- "FR16"+ "FR16",+ "FR17",+ "FR18",+ "FR19",+ "FR20",+ "FR21",+ "DEC-7"]}}@@ -56,7 +62,7 @@ for each bug.- Defining template fixture preview and copy behavior owned by `spec:AST-028`.- Choosing visual design, animation, layout, or copy for an individual Docsite page.- Choosing a telemetry vendor, transport, retention policy, or dashboard.-- Adding a Docsite public API, package API, theme target, or consumer runtime.+- Adding a package API, theme target, or consumer runtime.- Treating one pull request, bug, or current implementation mechanism as authority.## Requirements@@ -197,6 +203,37 @@ for each bug.and parent-DOM denial, trusted recovery after reload and hostile navigation,and restoration of current code and theme/mode.+### Published surfaces and deployment identity++- **FR17 — Production has one exact-head owner.** The canonical production+ Docsite origin MUST serve the documentation, `/storybook/`, and `/sandbox/`+ from the same successful main-branch deployment. A build that cannot stage+ either static application MUST fail rather than publish a partial release.+ The Docsite MUST expose real links to both applications.+- **FR18 — Static application routes remain addressable.** Storybook manager and+ iframe URLs, Sandbox route directories and embeds, static assets, query+ parameters, and fragments MUST survive direct load on their canonical paths.+ Route normalization MAY preserve or remove a trailing slash, but MUST retain+ the selected application state and MUST NOT fall through to unrelated Docsite+ content.+- **FR19 — Canonical and indexing metadata match the surface.** Production entry+ and addressable route pages identify their `https://astryx.atmeta.com`+ canonical URL. Pull-request previews, standalone Storybook frames, Sandbox+ embeds, and compatibility pages MUST be `noindex`; a preview MUST NOT claim a+ production canonical URL.+- **FR20 — Deployment identity is exact and generated.** Every Vercel Preview+ and Production build MUST expose its complete 40-character source commit and+ deployment environment at `/version.json`. Missing source identity fails the+ build. Generated identity and staged applications MUST NOT enter source+ control.+- **FR21 — The former Pages origin is one compatibility surface.** GitHub Pages+ MUST serve only a small, accessible, responsive landing page and equivalent+ deep-path recovery page. Documentation is the primary canonical destination;+ Storybook and Sandbox are labeled secondary destinations. An old Storybook or+ Sandbox path MAY be carried into the corresponding link with its query and+ fragment, but the compatibility page MUST NOT automatically redirect, build+ either application, or host CI evidence.+### Authority routing`architecture:knowledge-contracts` owns public-delta routing and change disposition.@@ -249,19 +286,28 @@ Known conformance gaps remain implementation work:- existing interaction tests do not yet cover the complete primary-selection,Back/Forward, close, cancellation, and supersession matrix.-This proposed specification changes no Docsite code, generated data, route, analytics-event, package behavior, or public API. Change disposition remains owned by-`architecture:knowledge-contracts`.+Stable Storybook and Sandbox currently use a split deployment: pull-request+previews are staged inside the Vercel Docsite, while stable main is rebuilt and+published through a separate GitHub Pages branch. That duplicates application+builds, leaves production ownership ambiguous, and makes the former Pages origin+carry unrelated preview and evidence storage.++The accepted target makes Vercel the one production owner for all three surfaces+and reduces GitHub Pages to the FR21 compatibility page. It adds no package or+consumer runtime API; `/version.json` is deployment evidence for verifying the+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 | 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 |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory | 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 |## Decision log@@ -342,6 +388,21 @@ navigation recover a trusted preview with current editor code and theme/mode.Rejected: treating local persistence or parent-page DOM access as a playgroundguarantee.+### DEC-7 — Vercel owns every maintained production surface++**Reference:** `spec:AST-033/DEC-7`+**Decider:** `cixzhang`, `2026-09-29`++The production Docsite, Storybook, and Sandbox ship together from the exact main+commit on the canonical Vercel origin. GitHub Pages remains only as one noindex+compatibility landing for old bookmarks, with documentation first and direct+Storybook and Sandbox destinations alongside it. Pull-request previews keep the+same Vercel paths and remain non-canonical.++Rejected: continuing a second stable-app build on `gh-pages`, silently dropping+old bookmarks, automatically redirecting every old deep path without recovery+choice, and using the compatibility origin for visual or test evidence.+## Open questionsNone.