@astryxdesign/cli 0.4.3 → 0.4.4-canary.2022d94

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @xds/cli
 
+# 0.4.4
+
+#### New Components
+
+- Promote `BottomSheet` and `BottomSheetSwitcher` from the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
+
+#### New Features
+
+- `astryx template --cdn` writes a working no-build-step CDN starter page (#5068).
+  A CDN starter is a template, so it joins the template family beside `--skeleton` rather than claiming a top-level command. It is a flag and not the positional `astryx template cdn` because the positional resolves against everything `discoverAll()` finds, where a `cdn` id would shadow a discovered template. `cdn.template.html` loads Astryx from jsDelivr and esm.sh with no bundler, no install and no build step, with every CDN URL pinned to the Astryx version you have installed — an unpinned CDN URL resolves to whatever is latest and is cached hard, so a page written today breaks tomorrow without being edited. An existing file is never clobbered; `--overwrite` replaces it, and `--json` returns the receipt.
+
+  The annotations are the things that are load-bearing and silent when missing: `?external=react,react-dom` (without it esm.sh bundles a second React and every hook throws `Cannot read properties of null (reading 'useState')`), `react/jsx-runtime` in the import map (the published bundle imports it; omitting it fails the page with `Failed to resolve module specifier`), and a `font-family` on `body` (nothing in the stylesheets sets a document font, so `Button` — which is `font: inherit` — otherwise renders its label in the browser's default serif).
+
+  Three more lessons came out of building a real app on it. The page now `<link>`s the theme's webfont from Google Fonts, because the theme _names_ Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in `<Theme theme={neutralTheme} mode="system">`, so light and dark follow the OS — the `data-astryx-theme` attribute alone scopes the stylesheet but cannot switch modes. And `#root:empty` carries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup is `htm`, with a comment saying it is optional and `createElement` is the dependency-free alternative.
+
+  A recipe that is only read is a recipe that is only assumed to work, so CI renders it: `.github/scripts/cdn-template-smoke-test.mjs` scaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.
+- `astryx theme build` takes any number of theme files — `astryx theme build themes/*.ts` compiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared in `engines`, so a package manager can enforce it at install instead of the build failing later (#5121).
+- `defineTheme`: `color.accent` accepts a `[light, dark]` tuple (#2279)
+  `ColorScaleConfig.accent` now takes either a single hex or a `[light, dark]` tuple, matching `TokenValue`. With a tuple, `expandColorScale` derives the light half of every generated `light-dark()` pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of the `tokens['--color-accent']` workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence between `color` and `tokens` for accent-derived values: `tokens` entries win token by token, the `var(--color-accent)` reference tokens follow a `--color-accent` override at runtime, and the baked `--color-on-accent` stays derived from the `color.accent` seed.
+
+#### Fixes
+
+- Bottom Sheet showcase block: the filter checkboxes are interactive again (#5157).
+  `CheckboxInput` is fully controlled — `value` is required and the input only moves when the owner updates it. The showcase passed a literal `value={false}` with no `onChange`, so the three filters ("In stock", "On sale", "Free shipping") rendered but could never be toggled: on the docs site the first thing a reader tries in a Bottom Sheet does nothing, and anyone copying the block inherits three dead controls. Each filter now has its own `useState` and `onChange`, matching the checkbox wiring already used in the Bottom Sheet Switcher showcase.
+- An integration whose manifest fails to load is no longer silent. A manifest that throws on import — the common case being one still calling a `create*` authoring factory, removed in 0.3.0 — contributes nothing, and the CLI treated that as if the package had never been configured: `astryx discover` answered `No integrations configured.` while `astryx.config.mjs` plainly configured one, and no command said a word. The only way to find out was to already suspect it and run `validate-integration` by name. Meta's internal `@nest/xds-meta` sat invisible to CLI discovery for a week that way, and the app team's conclusion was that the components did not exist (#5119).
+  The load error now counts as an integration issue, so the existing one-line stderr nudge fires on `component`, `template` and `upgrade`, and `discover` — the command whose whole job is listing integrations — nudges too, as does `search`. `discover` also stops reporting `configured: false` for a project that configured an integration that failed to load; the empty state now distinguishes "you configured nothing" from "what you configured contributed nothing", which is the distinction `meta.configured` was introduced to carry.
+
+  Nothing becomes fatal: the warning is best-effort, stderr-only, suppressed under `--json`, and never changes an exit code. Broken contributions are still skipped exactly as before.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @imdreamrunner
+- @jiunshinn
+
+---
+
 # 0.4.3
 
 #### Fixes
@@ -8,6 +47,7 @@
   The `theme.build` receipt now separates the two: `warnings` are defects the author should fix, `notices` are advisories about a correct theme. The font advisory moves to `notices` and to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back to `warnings` being empty, and no longer needs to know which fonts the template names.
 
   Programmatic callers reading `data.warnings` for font advisories should read `data.notices`; the message text is unchanged.
+
 - `extends` now reaches the CSS. A theme that extended another built a stylesheet holding only the declarations it stated itself: the base's tokens, component overrides and surface rules were all absent, and because each theme is `@scope`d to its own `data-astryx-theme` value, loading the base's stylesheet alongside could not fill the gap either. Every consumer of an inheritance chain silently got stock geometry, elevation and type with a new palette painted over it (#5067). Nothing warned; the loss only showed up by diffing two generated stylesheets token by token.
   The cause was `theme build` shadowing its own inputs. It writes `<name>.js` next to `<name>.ts`, and the loader resolved a plain `./<name>` specifier to that generated artifact before the source — so the second build of a family read the artifact, which carries no `components` and exports `<name>Theme` rather than whatever the source exports. A named import that missed became `extends: undefined`, and `defineTheme` treated an absent base as no base at all. The loader now resolves source extensions first, which is also the resolution the author's TypeScript sees, so the CSS a build emits matches the theme that type-checked.
 

package/README.md

@@ -383,49 +383,51 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 <!-- BEGIN GENERATED: response-types -->
 
-| Type                        | What `data` carries                                                                                                                                                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `component.list`            | 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.                                       |
-| `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                    |
-| `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                               |
-| `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                 |
-| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                               |
-| `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                           |
-| `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                              |
-| `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                        |
-| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                              |
-| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                             |
-| `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                            |
-| `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                   |
-| `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                           |
-| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                       |
-| `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                     |
-| `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                    |
-| `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                         |
-| `build.kit`                 | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.             |
-| `swizzle.list`              | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                       |
-| `swizzle.copy`              | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                       |
-| `template.list`             | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                 |
-| `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                  |
-| `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                         |
-| `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                |
-| `hook.list`                 | 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.                                                    |
-| `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                    |
-| `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                   |
-| `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                    |
-| `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
-| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                          |
-| `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
-| `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.                                        |
-| `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
-| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                     |
-| `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |
-| `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.        |
-| `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                          |
-| `integration.validate`      | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                             |
-| `layout.expand`             | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
-| `layout.check`              | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).             |
-| `layout.grammar`            | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                  |
+| Type                        | What `data` carries                                                                                                                                                                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `component.list`            | 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.                                                      |
+| `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                                   |
+| `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                              |
+| `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                                |
+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                              |
+| `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                          |
+| `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                             |
+| `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                       |
+| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                             |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                            |
+| `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                           |
+| `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                  |
+| `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                                          |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                      |
+| `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                    |
+| `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                                   |
+| `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                                        |
+| `build.kit`                 | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.                            |
+| `swizzle.list`              | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                      |
+| `swizzle.copy`              | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                      |
+| `template.list`             | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                |
+| `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                 |
+| `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                        |
+| `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                               |
+| `template.cdn`              | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success. |
+| `hook.list`                 | 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.                                                                   |
+| `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                                   |
+| `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                  |
+| `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                                   |
+| `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                |
+| `theme.build.batch`         | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                   |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                                         |
+| `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                          |
+| `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.                                                       |
+| `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                          |
+| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                    |
+| `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                         |
+| `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.                       |
+| `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                                         |
+| `integration.validate`      | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                            |
+| `layout.expand`             | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                |
+| `layout.check`              | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                            |
+| `layout.grammar`            | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                 |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->

package/api/discover/_adapter.d.mts

@@ -6,9 +6,11 @@
  *
  * External packages come from configured integrations that declare a components
  * root; each becomes a scannable package keyed by its docsDir. `configured`
- * reports whether ANY integration declared a components root — it lets an empty
- * result distinguish "nothing configured" (`false`) from "configured but
- * nothing discovered" (`true`), which the list leaf surfaces as `meta`.
+ * reports whether the project configured ANY integration — including one whose
+ * manifest failed to load, which contributes nothing but is emphatically not
+ * "nothing configured". It lets an empty result distinguish "nothing
+ * configured" (`false`) from "configured but nothing discovered" (`true`),
+ * which the list leaf surfaces as `meta`.
  *
  * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */

package/api/discover/_adapter.mjs

@@ -62,9 +62,11 @@ function validateDocs(docs) {
  *
  * External packages come from configured integrations that declare a components
  * root; each becomes a scannable package keyed by its docsDir. `configured`
- * reports whether ANY integration declared a components root — it lets an empty
- * result distinguish "nothing configured" (`false`) from "configured but
- * nothing discovered" (`true`), which the list leaf surfaces as `meta`.
+ * reports whether the project configured ANY integration — including one whose
+ * manifest failed to load, which contributes nothing but is emphatically not
+ * "nothing configured". It lets an empty result distinguish "nothing
+ * configured" (`false`) from "configured but nothing discovered" (`true`),
+ * which the list leaf surfaces as `meta`.
  *
  * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */
@@ -84,7 +86,7 @@ export async function discoverPackages() {
       docsDir: integration.components,
     }));
   if (explicitPackages.length === 0) {
-    return {packages: [], configured: false};
+    return {packages: [], configured: loadedIntegrations.length > 0};
   }
 
   const packages = scanAllPackages(

package/api/template/cdn/cdn.d.mts

@@ -0,0 +1,23 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Write the annotated CDN starter page into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run.
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../template.type.mjs').TemplateCdnResponse}
+ */
+export function templateCdn(options?: {
+    targetPath?: string;
+    overwrite?: boolean;
+    cwd?: string;
+}): import("../template.type.mjs").TemplateCdnResponse;
+/** The annotated CDN starter that ships with the CLI. */
+export const CDN_TEMPLATE_SRC: string;
+/** Where it lands when the caller does not say. */
+export const CDN_TEMPLATE_DEFAULT_PATH: "cdn.template.html";
+/** The token every CDN URL in the asset carries in place of a version. */
+export const CDN_VERSION_PLACEHOLDER: "__ASTRYX_VERSION__";

package/api/template/cdn/cdn.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `template.cdn` leaf — writes the annotated no-build-step starter page
+ * into the consumer's project.
+ *
+ * A CDN starter is a template, so it lives in the template family. It is the
+ * one member that is not discovered: it ships as an asset rather than as a
+ * `page.tsx` + `template.doc.mjs` pair, which is why the dispatcher routes to
+ * it from a flag instead of resolving a name.
+ *
+ * Every CDN URL in the asset carries the `__ASTRYX_VERSION__` placeholder, which
+ * is substituted here. An unpinned CDN URL resolves to whatever is latest and is
+ * cached hard, so a page written today can break tomorrow without being edited.
+ *
+ * @position api/template/cdn — writes the CDN starter asset; the template
+ *   dispatcher routes `--cdn` here before any discovery happens.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT, findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
+import {getXdsVersion} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+
+/** The annotated CDN starter that ships with the CLI. */
+export const CDN_TEMPLATE_SRC = path.join(CLI_ROOT, 'assets', 'cdn.template.html');
+
+/** Where it lands when the caller does not say. */
+export const CDN_TEMPLATE_DEFAULT_PATH = 'cdn.template.html';
+
+/** The token every CDN URL in the asset carries in place of a version. */
+export const CDN_VERSION_PLACEHOLDER = '__ASTRYX_VERSION__';
+
+/**
+ * Write the annotated CDN starter page into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run.
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../template.type.mjs').TemplateCdnResponse}
+ */
+export function templateCdn(options = {}) {
+  const {
+    targetPath = CDN_TEMPLATE_DEFAULT_PATH,
+    overwrite = false,
+    cwd = process.cwd(),
+  } = options;
+
+  let resolved;
+  try {
+    resolved = assertWithin(targetPath, cwd, {label: 'cdn template path'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+
+  const relative = path.relative(cwd, resolved) || targetPath;
+  // The installed @astryxdesign/core when there is one, else this CLI's own
+  // version. core, the themes and the CLI are released as one fixed group, so
+  // either answer pins a set of packages that exist together.
+  const version = getXdsVersion(findCoreDir(cwd));
+
+  if (fs.existsSync(resolved) && !overwrite) {
+    return {
+      type: 'template.cdn',
+      data: {path: relative, version, written: false, reason: 'exists'},
+    };
+  }
+
+  const source = stripCopyrightHeader(fs.readFileSync(CDN_TEMPLATE_SRC, 'utf-8'));
+  const contents = source.replaceAll(CDN_VERSION_PLACEHOLDER, version);
+  fs.mkdirSync(path.dirname(resolved), {recursive: true});
+  fs.writeFileSync(resolved, contents);
+
+  return {
+    type: 'template.cdn',
+    data: {path: relative, version, written: true, reason: null},
+  };
+}

package/api/template/cdn/cdn.test.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct API tests for `templateCdn()` — the function behind
+ * `astryx template --cdn`.
+ *
+ * Two things matter here: it never destroys work (the page lands once, a second
+ * run leaves an edited copy alone, a path that escapes the project is refused),
+ * and the page it writes is pinned — a leftover version placeholder would ship
+ * a file whose every CDN URL 404s.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  templateCdn,
+  CDN_TEMPLATE_DEFAULT_PATH,
+  CDN_VERSION_PLACEHOLDER,
+} from './cdn.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-cdn-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+const written = () =>
+  fs.readFileSync(path.join(tmpDir, CDN_TEMPLATE_DEFAULT_PATH), 'utf-8');
+
+describe('templateCdn()', () => {
+  it('writes the page and returns a template.cdn receipt', () => {
+    const res = templateCdn({cwd: tmpDir});
+
+    expect(res.type).toBe('template.cdn');
+    expect(res.data.path).toBe(CDN_TEMPLATE_DEFAULT_PATH);
+    expect(res.data.written).toBe(true);
+    expect(res.data.reason).toBe(null);
+    expect(res.data.version).toMatch(/^\d+\.\d+\.\d+/);
+    expect(written()).toMatch(/<script type="importmap">/);
+  });
+
+  it('pins every CDN url to the reported version', () => {
+    const {data} = templateCdn({cwd: tmpDir});
+    const html = written();
+
+    expect(html).not.toContain(CDN_VERSION_PLACEHOLDER);
+    const urls = html.match(/https:\/\/(?:cdn\.jsdelivr\.net\/npm|esm\.sh)\/@astryxdesign\/[^"?]+/g);
+    expect(urls?.length).toBeGreaterThan(0);
+    for (const url of urls ?? []) {
+      expect(url).toContain(`@${data.version}`);
+    }
+  });
+
+  it('loads the font family the theme names', () => {
+    templateCdn({cwd: tmpDir});
+    const html = written();
+
+    // The theme names Figtree and never loads it (#5015): without the webfont
+    // link every viewer silently gets the fallback stack instead.
+    expect(html).toMatch(/fonts\.googleapis\.com\/css2\?family=Figtree/);
+  });
+
+  it('does not carry our copyright header into the consumer tree', () => {
+    templateCdn({cwd: tmpDir});
+
+    expect(written()).not.toMatch(/Copyright \(c\) Meta Platforms/);
+    expect(written().startsWith('<!doctype html>')).toBe(true);
+  });
+
+  it('leaves an existing file alone and says so', () => {
+    const dest = path.join(tmpDir, CDN_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '<!-- mine -->\n');
+
+    const res = templateCdn({cwd: tmpDir});
+
+    expect(res.data.written).toBe(false);
+    expect(res.data.reason).toBe('exists');
+    expect(fs.readFileSync(dest, 'utf-8')).toBe('<!-- mine -->\n');
+  });
+
+  it('overwrites when asked', () => {
+    const dest = path.join(tmpDir, CDN_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '<!-- mine -->\n');
+
+    const res = templateCdn({cwd: tmpDir, overwrite: true});
+
+    expect(res.data.written).toBe(true);
+    expect(written()).toMatch(/importmap/);
+  });
+
+  it('honors a custom path and creates its directory', () => {
+    const res = templateCdn({cwd: tmpDir, targetPath: 'public/demo.html'});
+
+    expect(res.data.path).toBe(path.join('public', 'demo.html'));
+    expect(fs.existsSync(path.join(tmpDir, 'public/demo.html'))).toBe(true);
+  });
+
+  it('refuses a path that escapes the project', () => {
+    expect(() => templateCdn({cwd: tmpDir, targetPath: '../escaped.html'})).toThrow(
+      /cdn template path/,
+    );
+    expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.html'))).toBe(false);
+  });
+});

package/api/template/template.d.mts

@@ -17,6 +17,7 @@
  * @param {boolean} [options.overwrite]
  * @param {boolean} [options.list]
  * @param {boolean} [options.skeleton]
+ * @param {boolean | string} [options.cdn] - Write the no-build-step CDN starter page; a string is used as the destination path.
  * @param {boolean} [options.show]
  * @param {'page'|'block'} [options.type] - Filter list views / narrow lookups by template kind.
  * @param {string} [options.package] - Narrow lookups to a specific package (id-only matches across packages are ambiguous).
@@ -28,6 +29,7 @@ export function template(name?: string, options?: {
     overwrite?: boolean | undefined;
     list?: boolean | undefined;
     skeleton?: boolean | undefined;
+    cdn?: string | boolean | undefined;
     show?: boolean | undefined;
     type?: "block" | "page" | undefined;
     package?: string | undefined;

package/api/template/template.doc.mjs

@@ -18,11 +18,13 @@ export const doc = {
     "templates; with a name it returns that template's source, a layout skeleton, or " +
     'scaffolds it into the project. Templates are discovered across core, external ' +
     'packages, and integrations, so the same id can appear in more than one place; ' +
-    'narrow an ambiguous name with type and/or package.',
+    'narrow an ambiguous name with type and/or package. The cdn option writes the ' +
+    'annotated no-build-step CDN starter page, which ships as an asset rather than as ' +
+    'a discovered template.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'template(name?: string, options?: TemplateOptions): Promise<TemplateListResponse | TemplateShowResponse | TemplateSkeletonResponse | TemplateCopyResponse>',
-  keywords: ['template', 'scaffold', 'page', 'block', 'skeleton', 'starter'],
+    'template(name?: string, options?: TemplateOptions): Promise<TemplateListResponse | TemplateShowResponse | TemplateSkeletonResponse | TemplateCopyResponse | TemplateCdnResponse>',
+  keywords: ['template', 'scaffold', 'page', 'block', 'skeleton', 'starter', 'cdn', 'esm', 'importmap', 'no-build'],
   params: [
     {
       name: 'name',
@@ -43,6 +45,13 @@ export const doc = {
         'Return a compact layout skeleton (structural tags with spatial annotations) instead of the full source.',
       default: 'false',
     },
+    {
+      name: 'options.cdn',
+      type: 'boolean | string',
+      description:
+        'Write the annotated no-build-step CDN starter page instead of resolving a template. Answers before discovery, so no name is involved; pass a string to use it as the destination path.',
+      default: 'false',
+    },
     {
       name: 'options.show',
       type: 'boolean',
@@ -102,6 +111,11 @@ export const doc = {
       description:
         'A receipt after scaffolding the template into the project: the template id, output directory, written file name, and file count.',
     },
+    {
+      type: 'template.cdn',
+      description:
+        'A write receipt for the CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+    },
   ],
   throws: [
     {
@@ -136,6 +150,10 @@ export const doc = {
       label: 'Scaffold into the project',
       code: "await template('dashboard', {targetPath: './app/page.tsx'});",
     },
+    {
+      label: 'CDN starter page',
+      code: 'await template(undefined, {cdn: true});',
+    },
   ],
   command: 'template',
   related: ['component', 'search', 'discover', 'init'],

package/api/template/template.mjs

@@ -5,14 +5,14 @@
  *
  * This module is BOTH the template dispatcher and the stable import surface for
  * the template family. `template()` discovers the available templates, resolves
- * the requested one, and routes to a leaf (list/show/skeleton/copy). The shared
+ * the requested one, and routes to a leaf (list/show/skeleton/copy/cdn). The shared
  * discovery/IO + cross-command helpers live in `foundation/discovery/template-adapter.mjs` and are
  * RE-EXPORTED here so external import paths (`api/template/template.mjs`) —
  * used by component, layout, search, init, discover, validate-integration, and
  * lib/project — keep resolving unchanged.
  *
  * @position api/template — the template dispatcher + barrel; leaves live under
- *   ./list, ./show, ./skeleton, ./copy and shared discovery in foundation/discovery.
+ *   ./list, ./show, ./skeleton, ./copy, ./cdn and shared discovery in foundation/discovery.
  */
 
 import {discoverAll, pkgOf} from '../../foundation/discovery/template-adapter.mjs';
@@ -22,6 +22,7 @@ import {templateList} from './list/list.mjs';
 import {templateShow} from './show/show.mjs';
 import {templateSkeleton} from './skeleton/skeleton.mjs';
 import {templateCopy} from './copy/copy.mjs';
+import {templateCdn} from './cdn/cdn.mjs';
 
 // Re-export the shared discovery/IO + cross-command helpers so this module
 // stays the single import surface for the template family (same exports as
@@ -56,6 +57,7 @@ export {
  * @param {boolean} [options.overwrite]
  * @param {boolean} [options.list]
  * @param {boolean} [options.skeleton]
+ * @param {boolean | string} [options.cdn] - Write the no-build-step CDN starter page; a string is used as the destination path.
  * @param {boolean} [options.show]
  * @param {'page'|'block'} [options.type] - Filter list views / narrow lookups by template kind.
  * @param {string} [options.package] - Narrow lookups to a specific package (id-only matches across packages are ambiguous).
@@ -67,12 +69,24 @@ export async function template(name, options = {}) {
     list = false,
     skeleton = false,
     show = false,
+    cdn = false,
     targetPath,
     overwrite = false,
     type,
     package: packageFilter,
     cwd = process.cwd(),
   } = options;
+
+  // The CDN starter ships as an asset rather than as a discovered template, so
+  // it answers before discovery — nothing here needs a name resolved.
+  if (cdn) {
+    return templateCdn({
+      targetPath: typeof cdn === 'string' ? cdn : targetPath,
+      overwrite,
+      cwd,
+    });
+  }
+
   const templates = await discoverAll(cwd);
 
   if (list || (!name && !skeleton)) {

package/api/template/template.type.d.mts

@@ -68,6 +68,21 @@ export type TemplateCopyResponse = {
         filesCopied: number;
     };
 };
+/**
+ * xds --json template --cdn [path]
+ * `written: false` with `reason: 'exists'` is a success: the command is safe to
+ * re-run, and an edited page is the consumer's file to keep. `version` is the
+ * Astryx version every CDN URL in the file was pinned to.
+ */
+export type TemplateCdnResponse = {
+    type: "template.cdn";
+    data: {
+        path: string;
+        version: string;
+        written: boolean;
+        reason: "exists" | null;
+    };
+};
 /**
  * Options for `template()`.
  */
@@ -75,6 +90,10 @@ export type TemplateOptions = {
     list?: boolean | undefined;
     skeleton?: boolean | undefined;
     show?: boolean | undefined;
+    /**
+     * Write the no-build-step CDN starter page instead of resolving a template. A string is used as the destination path.
+     */
+    cdn?: string | boolean | undefined;
     /**
      * Filter templates by kind: 'page' or 'block'. Only applies to list views.
      */