Skip to content

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.mjs
index 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/.gitignore
index 3b7cdf4ff8..ce61231a97 100644
--- a/apps/docsite/.gitignore
+++ b/apps/docsite/.gitignore
@@ -13,9 +13,10 @@ public/playground-types.json
public/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 are
diff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjs
index 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.mjs
index 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.mjs
index 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 a
test('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.tsx
index 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.md
index 9b0bfdb372..16ec57fab7 100644
--- a/docs/specs/AST-033/spec.md
+++ b/docs/specs/AST-033/spec.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-09
+approved_at: 2026-09-29
phase: accepted
owners: [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 playground
guarantee.
+### 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 questions
None.