@astryxdesign/cli 0.3.0-canary.fbc60c5 → 0.3.0-canary.fcbc342

package/authoring/doctypes/template/template.doc.mjs

@@ -150,13 +150,13 @@ export const doc = {
       type: 'list',
       style: 'unordered',
       items: [
-        "PageTemplateDoc (type: 'page') — a full page template; `name` doubles as its display value.",
-        "BlockTemplateDoc (type: 'block') — an example of a component; requires `exampleFor` and `aspectRatio`.",
+        "PageTemplateDoc (type: 'page'): a full page template; `name` doubles as its display value.",
+        "BlockTemplateDoc (type: 'block'): an example of a component; requires `exampleFor` and `aspectRatio`.",
       ],
     },
     {
       type: 'prose',
-      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template — unused values are reserved so authors get autocomplete for the full taxonomy.",
+      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template; unused values are reserved so authors get autocomplete for the full taxonomy.",
     },
   ],
 };

package/clients/cli/commands/build-theme.registry.test.mjs

@@ -60,7 +60,10 @@ function renderedClassLiterals() {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (entry.name.endsWith('.tsx') && !entry.name.endsWith('.test.tsx')) {
+      } else if (
+        (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) &&
+        !entry.name.includes('.test.')
+      ) {
         const text = fs.readFileSync(full, 'utf8');
         for (const re of [
           /themeProps\(\s*'([^']+)'/g,
@@ -71,6 +74,16 @@ function renderedClassLiterals() {
             classes.add(m[1]);
           }
         }
+        // Renamed targets emit their old name too, via themeProps'
+        // `legacyNames`. Those classes are just as rendered as the primary
+        // one, so a doc entry for the old name is still backed by real output.
+        const legacyRe = /legacyNames:\s*\[([^\]]*)\]/g;
+        let lm;
+        while ((lm = legacyRe.exec(text)) !== null) {
+          for (const nm of lm[1].matchAll(/'([^']+)'/g)) {
+            classes.add(nm[1]);
+          }
+        }
       }
     }
   };

package/clients/cli/commands/build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Build a page: composition kit for an idea, or the workflow playbook (no args)',
   description:
     'The assemble-a-page entry point. With no query it returns the how-to-build-a-page ' +
-    'playbook; with a query it groups the unified search hits into a composition kit — ' +
+    'playbook; with a query it groups the unified search hits into a composition kit: ' +
     'the closest templates, drop-in blocks, and idea-specific components and hooks.',
   fn: 'build',
   args: [{name: 'query', param: 'query', required: false}],

package/clients/cli/commands/component.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown component, category, or package — or @astryxdesign/core cannot be resolved',
+      when: 'unknown component, category, or package, or @astryxdesign/core cannot be resolved',
     },
   ],
   related: ['search', 'hook', 'docs', 'template', 'swizzle'],

package/clients/cli/commands/doctor.doc.mjs

@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Diagnose your XDS setup and report problems with fixes',
   description:
-    'Runs read-only diagnostics — Node version, @astryxdesign/core install and version ' +
-    'alignment, installed themes, config validity, agent docs, and the package manager — ' +
+    'Runs read-only diagnostics: Node version, @astryxdesign/core install and version ' +
+    'alignment, installed themes, config validity, agent docs, and the package manager, ' +
     'and reports pass/warn/fail with an actionable fix for each problem. Safe as a CI gate.',
   fn: 'doctor',
   examples: [

package/clients/cli/commands/layout-expand.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
-    'ready-to-use XDS TSX — routing children into slots, scaffolding typed useState for ' +
+    'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [

package/clients/cli/commands/layout.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — expand an expression into ' +
+    'subcommand list; the work happens in the subcommands: expand an expression into ' +
     'TSX (expand), validate one (check), or print the grammar cheatsheet (grammar).',
   subcommands: ['expand', 'check', 'grammar'],
   examples: [

package/clients/cli/commands/manifest.doc.mjs

@@ -3,7 +3,7 @@
 /**
  * @file CommandDoc for `astryx manifest`. A CLI-only capability manifest with no
  * wrapped API function (so no `fn`); it emits the full command surface — args,
- * flags, subcommands, and JSON response types — as a single typed envelope.
+ * flags, subcommands, and JSON response types, as a single typed envelope.
  * @position packages/cli/clients/cli/commands — command documentation
  */
 
@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
-    'Emits the complete CLI surface — every command with its arguments, options, ' +
-    'subcommands, and JSON response types — as a single typed envelope for agents and ' +
+    'Emits the complete CLI surface: every command with its arguments, options, ' +
+    'subcommands, and JSON response types, as a single typed envelope for agents and ' +
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},

package/clients/cli/commands/search.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
-    'Terminal front-end to search() — prints one ranked, greppable list across ' +
+    'Terminal front-end to search(): prints one ranked, greppable list across ' +
     'every content domain, each row carrying a follow-up command to act on it.',
   fn: 'search',
   args: [{name: 'query', param: 'query', required: true}],

package/clients/cli/commands/theme-add.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Scaffold a theme into your project as editable source',
   description:
-    "Copies a bundled theme's source into your project so you own it — no theme package " +
+    "Copies a bundled theme's source into your project so you own it, no theme package " +
     'needed. Writes are staged then renamed, rolling back on failure. Running it with no ' +
     'slug, or with --list, lists the bundled themes instead.',
   fn: 'themeAdd',

package/clients/cli/commands/theme-build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Compile a defineTheme file to CSS + JS',
   description:
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
-    'type declarations — the exact CSS the <Theme> runtime emits. With --check it writes ' +
+    'type declarations: the exact CSS the <Theme> runtime emits. With --check it writes ' +
     'nothing and instead reports whether the committed outputs have drifted from source.',
   fn: 'themeBuild',
   args: [{name: 'file', param: 'file', required: true}],

package/clients/cli/commands/theme-list.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'List themes available to add',
   description:
-    'Lists the themes bundled with this CLI build — the ones theme add can scaffold — ' +
+    'Lists the themes bundled with this CLI build (the ones theme add can scaffold), ' +
     'each with its slug, display name, description, and maintained flag.',
   fn: 'themeList',
   examples: [{label: 'List bundled themes', cli: 'astryx theme list --json'}],

package/clients/cli/commands/theme.doc.mjs

@@ -13,10 +13,10 @@ export const doc = {
   name: 'theme',
   displayName: 'astryx theme',
   namespace: 'cli',
-  summary: 'Theme tools — build, export, and manage themes',
+  summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — compile a theme (build), ' +
+    'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
     'scaffold one into your project (add), or list the bundled themes (list).',
   subcommands: ['build', 'add', 'list'],
   examples: [

package/clients/cli/commands/validate-integration.doc.mjs

@@ -16,8 +16,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Validate an Astryx integration package (manifest + contributions)',
   description:
-    'Validates ONE integration at a time — the local package rooted at cwd, or an ' +
-    'installed package resolved by name — schema-checking its manifest, verifying each ' +
+    'Validates ONE integration at a time: the local package rooted at cwd, or an ' +
+    'installed package resolved by name, schema-checking its manifest, verifying each ' +
     'declared contribution root, and reporting every finding. Safe as a CI gate.',
   fn: 'validateIntegration',
   args: [{name: 'package', param: 'pkg', required: false}],

package/foundation/agent-docs/agent-docs.mjs

@@ -341,10 +341,9 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
 
   // Rules — the top error-preventers.
   lines.push('RULES:');
-  lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
-  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
-  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
-  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
+  lines.push('- No <div> — components do all layout/spacing, page frame included.');
+  lines.push('- Frame first: read `astryx docs layout` before writing any page or screen — page frame, region widths, breakpoint behavior.');
+  lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.

package/foundation/agent-docs/agent-docs.test.mjs

@@ -46,6 +46,14 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/never override --color-/);
   });
 
+  it('sends frame choice to the layout doc rather than naming a shell', () => {
+    const result = generateCompressedIndex('1.0.0');
+    const frameRule = result.split('\n').find(l => l.includes('Frame first'));
+    expect(frameRule).toContain('astryx docs layout');
+    expect(result).not.toMatch(/AppShell/);
+    expect(frameRule).not.toMatch(/https?:/);
+  });
+
   it('includes the post-generation self-check rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toContain('SELF-CHECK before you finish');

package/foundation/discovery/template-adapter.d.mts

@@ -11,11 +11,14 @@ export function pkgOf(t: {
     package?: string;
 }): string;
 /**
- * Replace demo image references with a self-contained placeholder data URI so
- * scaffolded pages render with zero setup. Builders drop in their own images.
+ * Replace demo asset references with a placeholder so scaffolded pages
+ * render with zero setup. Images get a self-contained data URI; videos
+ * (which have no equivalent inline placeholder — see VIDEO_EXTENSIONS) are
+ * stripped to an empty src instead of being mis-replaced with image data.
+ * Builders drop in their own media either way.
  *
  * @param {string} source - Template source code.
- * @returns {string} Source with demo image references replaced.
+ * @returns {string} Source with demo asset references replaced.
  */
 export function stripTemplateAssetRefs(source: string): string;
 /**

package/foundation/discovery/template-adapter.mjs

@@ -153,15 +153,33 @@ const PLACEHOLDER_IMAGE =
   'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20400%20300%22%20preserveAspectRatio%3D%22xMidYMid%20slice%22%3E%3Crect%20width%3D%22400%22%20height%3D%22300%22%20fill%3D%22%23f5f6f8%22%2F%3E%3Cg%20transform%3D%22translate%28200%20150%29%22%20fill%3D%22none%22%20stroke%3D%22%23c2cad6%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Crect%20x%3D%22-44%22%20y%3D%22-44%22%20width%3D%2288%22%20height%3D%2288%22%20rx%3D%2216%22%2F%3E%3Ccircle%20cx%3D%2218%22%20cy%3D%22-18%22%20r%3D%222.5%22%20fill%3D%22%23c2cad6%22%20stroke%3D%22none%22%2F%3E%3Cpath%20d%3D%22M-34%2030%20L-8%200%20L10%2018%20L20%208%20L34%2024%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E';
 
 /**
- * Demo-image sources to strip from scaffolded projects — Meta's lookaside CDN
- * (a Meta-only network dependency). Genuine third-party URLs (e.g. brand logos
- * from paypalobjects.com) are intentionally left untouched.
+ * Extensions that need a video-safe placeholder rather than the image data
+ * URI (see stripTemplateAssetRefs). There's no equivalent self-contained
+ * inline placeholder for video: unlike an SVG data URI, a `<video src>`
+ * needs actual encoded media, and hand-authoring a valid tiny MP4/WebM
+ * blob isn't something we can do reliably here — an unverifiable, possibly
+ * still-broken binary would just trade one silent failure for another.
+ * Rather than mis-render image data as video (the original bug) or guess at
+ * binary bytes, video sources are stripped to an empty string so the
+ * scaffolded example is honest about needing the builder to supply their
+ * own file, instead of silently pointing at something that can't play.
  *
- * @type {RegExp[]}
+ * @type {Set<string>}
  */
-const DEMO_IMAGE_PATTERNS = [
-  /https?:\/\/(?:[\w-]+\.)*lookaside\.facebook\.com\/[^\s'"`)]+/g,
-];
+const VIDEO_EXTENSIONS = new Set(['mp4', 'webm', 'mov', 'ogv']);
+
+/**
+ * Demo-asset sources to strip from scaffolded projects. Template demo imagery
+ * is self-hosted under the docsite's `/template-assets/*` dir (committed there,
+ * mirrored into the sandbox preview by scripts/sync-templates.js). Those paths
+ * only resolve inside the Astryx docsite/sandbox, so on scaffold they're
+ * replaced — a scaffolded project has no `/template-assets/` dir and would
+ * otherwise 404. Genuine third-party URLs (e.g. brand logos from
+ * paypalobjects.com) are intentionally left untouched.
+ *
+ * @type {RegExp}
+ */
+const DEMO_ASSET_PATTERN = /\/template-assets\/[\w-]+\.(\w+)/g;
 
 /**
  * Normalize path into Unix path (using forward slashes) for consistent comparison
@@ -175,16 +193,18 @@ function toPosixPath(p) {
 }
 
 /**
- * Replace demo image references with a self-contained placeholder data URI so
- * scaffolded pages render with zero setup. Builders drop in their own images.
+ * Replace demo asset references with a placeholder so scaffolded pages
+ * render with zero setup. Images get a self-contained data URI; videos
+ * (which have no equivalent inline placeholder — see VIDEO_EXTENSIONS) are
+ * stripped to an empty src instead of being mis-replaced with image data.
+ * Builders drop in their own media either way.
  *
  * @param {string} source - Template source code.
- * @returns {string} Source with demo image references replaced.
+ * @returns {string} Source with demo asset references replaced.
  */
 export function stripTemplateAssetRefs(source) {
-  return DEMO_IMAGE_PATTERNS.reduce(
-    (out, pattern) => out.replace(pattern, PLACEHOLDER_IMAGE),
-    source,
+  return source.replace(DEMO_ASSET_PATTERN, (match, extension) =>
+    VIDEO_EXTENSIONS.has(extension.toLowerCase()) ? '' : PLACEHOLDER_IMAGE,
   );
 }
 /**

package/foundation/response/response-types.doc.mjs

@@ -21,7 +21,7 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        'The component catalog grouped by category: `detail` (the level — names | compact | full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.',
+        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.',
     },
     {
       value: 'component.detail',
@@ -61,14 +61,14 @@ export const doc = {
     {
       value: 'docs.detail.section',
       description:
-        'A single ReferenceSection of a topic — the first whose title contains the section query.',
+        'A single ReferenceSection of a topic: the first whose title contains the section query.',
     },
 
     // blog (read from the published RSS feed)
     {
       value: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.',
+        'The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.',
     },
     {
       value: 'blog.detail',
@@ -89,7 +89,7 @@ export const doc = {
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
     },
     {
       value: 'discover.search',
@@ -154,7 +154,7 @@ export const doc = {
     {
       value: 'hook.list',
       description:
-        'The hook catalog grouped by category: `detail` (the level — names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.',
+        'The hook catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.',
     },
     {value: 'hook.detail', description: "One hook's full authored HookDoc."},
     {
@@ -176,7 +176,7 @@ export const doc = {
     {
       value: 'theme.list',
       description:
-        'Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.',
+        'Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.',
     },
     {
       value: 'theme.add',
@@ -193,7 +193,7 @@ export const doc = {
     {
       value: 'upgrade.status',
       description:
-        'A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.',
+        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.',
     },
     {
       value: 'upgrade.run',

package/foundation/response/response.doc.mjs

@@ -47,7 +47,7 @@ export const doc = {
           name: 'data',
           type: 'unknown',
           description:
-            "The command's payload. Structural by design — narrowed by the " +
+            "The command's payload. Structural by design, narrowed by the " +
             'per-command return type, not by a map in the serializer.',
           required: true,
         },
@@ -63,7 +63,7 @@ export const doc = {
       name: 'Error envelope',
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
-        'Emitted for every failure in --json mode — including uncaught throws ' +
+        'Emitted for every failure in --json mode, including uncaught throws ' +
         'and Commander parse errors, which are converted to this shape.',
       fields: [
         {
@@ -86,7 +86,7 @@ export const doc = {
           name: 'code',
           type: 'ErrorCode',
           description:
-            'Stable, machine-readable identifier — always present, append-only, ' +
+            'Stable, machine-readable identifier; always present, append-only, ' +
             'and never changes meaning. Branch on this.',
           required: true,
           example: "'ERR_UNKNOWN_COMPONENT'",
@@ -95,7 +95,7 @@ export const doc = {
           name: 'suggestions',
           type: 'Suggestion[]',
           description:
-            'Optional "did you mean…" hints, present only when candidates exist.',
+            'Optional "did you mean..." hints, present only when candidates exist.',
           fields: [
             {
               name: 'suggestions[].name',
@@ -146,7 +146,7 @@ export const doc = {
     {
       type: 'prose',
       text:
-        '`code` is the stable contract — see the error-codes enum (ErrorCode) ' +
+        '`code` is the stable contract; see the error-codes enum (ErrorCode) ' +
         'for the full append-only list. Branch on `code`, never on the `error` ' +
         'prose, which can be reworded or localized at any time.',
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.3.0-canary.fbc60c5",
+  "version": "0.3.0-canary.fcbc342",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/core": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/lab": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.fbc60c5",
+    "@astryxdesign/charts": "0.3.0-canary.fcbc342",
+    "@astryxdesign/core": "0.3.0-canary.fcbc342",
+    "@astryxdesign/lab": "0.3.0-canary.fcbc342",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.fcbc342",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/core": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/lab": "0.3.0-canary.fbc60c5",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.fbc60c5",
+    "@astryxdesign/charts": "0.3.0-canary.fcbc342",
+    "@astryxdesign/core": "0.3.0-canary.fcbc342",
+    "@astryxdesign/lab": "0.3.0-canary.fcbc342",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.fcbc342",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {