@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f2b60a0

package/assets/docs/tree/quick-start.doc.mjs

@@ -34,20 +34,22 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',
+          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, make it an ES module, then install the Astryx CLI, Core, and TypeScript for development.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",
+          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets type=module\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
+            'Set `"type": "module"`: the `.js` files the CLI generates, such as a built theme, are ES modules, and Node fails to load them in a package marked `"type": "commonjs"`, which `npm init -y` writes on npm 11.',
             'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
             'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
             'Component commands read Core, so they need `@astryxdesign/core` installed.',
+            "The checks compare your docs with your code through TypeScript's JavaScript compiler API, so they need `typescript` 5.0 through 6 installed. TypeScript 7 does not ship that API, and with it the checks skip those comparisons.",
           ],
         },
         {
@@ -86,6 +88,33 @@ export const docs = {
           type: 'prose',
           text: 'You now have an integration package with one exported component.',
         },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Check it in every build (required)',
+        },
+        {
+          type: 'prose',
+          text: 'Every integration runs `integration check --strict` in its own build, so a doc, prop, template, or link that stops matching the code fails your build instead of reaching the apps that install your package. Set it up now, as the `typecheck` script, and run it.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm pkg set scripts.typecheck="astryx integration check --strict"\nnpm run typecheck',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '[ok] 0 errors, 0 warnings, 0 skipped. Every check passed.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Run `typecheck` in CI and before every publish. When you add a `tsconfig.json`, put `tsc --noEmit && ` in front of the check so the same script checks your types.',
+            'What each check covers, and what `--strict` adds: {@link generic:checks}.',
+          ],
+        },
         {
           type: 'heading',
           level: 3,
@@ -172,19 +201,19 @@ export const docs = {
             ],
             [
               '`peerDependencies`',
-              '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+              '`@astryxdesign/core` when your code imports it; `@astryxdesign/cli`, optional, when you ship a feature that needs a newer CLI ({@link generic:versioning})',
               'The app supplies these packages for your integration.',
             ],
             [
               '`devDependencies`',
-              '`@astryxdesign/cli` and `@astryxdesign/core`',
-              'Lets you run the CLI and build components while working on the integration.',
+              '`@astryxdesign/cli`, `@astryxdesign/core`, and `typescript`',
+              'Lets you run the CLI, build components, and run the checks while working on the integration.',
             ],
           ],
         },
         {
           type: 'prose',
-          text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}.',
+          text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}. Add `"typecheck": "tsc --noEmit && astryx integration check --strict"` to `scripts` so each run checks your types and that your docs, props, and links still match the code. It needs `typescript` and a `tsconfig.json`; see {@link generic:checks}.',
         },
       ],
     },
@@ -226,21 +255,8 @@ export const docs = {
           text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
         },
         {
-          type: 'reference',
-          target: 'schema:integration',
-          projection: {
-            fields: [
-              'providerId',
-              'components',
-              'templates',
-              'codemods',
-              'docs',
-              'themes',
-              'agentDocs',
-              'issuesUrl',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:integration}.',
         },
         {
           type: 'heading',

package/assets/docs/tree/replace-a-core-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/replace-a-core-component`:
  * intentionally make an integration component the default for a Core identity.
  */
 
@@ -65,10 +65,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
         {
           type: 'prose',
@@ -87,7 +85,7 @@ export default {
           type: 'list',
           style: 'unordered',
           items: [
-            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that earlier `integration add theme` and `integration add doc --parent` wrote.',
+            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that `integration add doc --parent` wrote in published 0.6.4 and 0.6.5, and `integration add theme` in published 0.6.5.',
             'Without such a range, the component keeps its own name, the Core component stays selected (a component named like its target stays ambiguous by that bare name, as before), and `doctor integration components` warns with the range to add. Apps that load such a package see no change.',
             '`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
             'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',

package/assets/docs/tree/replace-a-core-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template`:
  * deliberately replace one Core template through template metadata.
  */
 
@@ -54,7 +54,7 @@ export const docs = {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-app-shell.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'page',
   name: 'acme-app-shell',
@@ -67,10 +67,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
@@ -84,7 +82,7 @@ export default {
       content: [
         {
           type: 'prose',
-          text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+          text: 'Declare the CLI floor that `integration verify` names as an optional peer ({@link generic:versioning}).',
         },
         {
           type: 'code',
@@ -103,7 +101,7 @@ export default {
         },
         {
           type: 'prose',
-          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, published 0.6.3 and earlier drop that template and hide your doc topics.',
         },
       ],
     },

package/assets/docs/tree/sections-and-placement.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/sections-and-placement`: give an
- * integration package its own section in the docs tree, place guides in it,
- * and fix a placement that fails.
+ * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * give an integration package its own section in the docs tree, place guides
+ * in it, and fix a placement that fails.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -62,9 +62,7 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "`parent` is `namespace:<name>`, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.",
-            "`slot` is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.",
-            '`order` is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.',
+            'Every field is in {@link schema:authored-doc-graph-fields}.',
             'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
           ],
         },

package/assets/docs/tree/see-it-in-an-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs cli/integrations/building-blocks/components/see-it-in-an-app`: inspect an
  * integration component from an app that installs the package.
  */
 
@@ -33,7 +33,9 @@ npx astryx search carousel`,
         {
           type: 'code',
           lang: 'text',
-          code: `# AcmeCarousel
+          code: `package: @acme/astryx-widgets
+
+# AcmeCarousel
 
 Cycles through slides one at a time. Use it for a small set of related cards.
 

package/assets/docs/tree/short-and-findable.doc.mjs

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/short-and-findable`: keep each read
- * short, lead each section with its summary, and write docs that search finds.
+ * @file `astryx docs cli/integrations/building-blocks/docs/short-and-findable`:
+ * keep each read short, lead each section with its summary, and write docs
+ * that search finds.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -58,7 +59,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder to your host.',
+          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder.',
         },
       ],
     },
@@ -68,14 +69,14 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.',
+          text: 'In a topic with more than one section, search ranks a section whose title matches the query, or that names it in backticks, above words in body text. Title each section with the task a reader searches for.',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".',
-            'Write field names, file names, and error codes in backticks, such as `deployTarget`: search treats each one as a keyword.',
+            'Write field names, file names, and error codes in backticks, such as `deployTarget`: in a topic with more than one section, search treats each one as a keyword.',
             'Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.',
           ],
         },

package/assets/docs/tree/single-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/single-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/single-component`:
  * write and maintain the default ComponentDoc for one public component.
  */
 
@@ -56,14 +56,13 @@ export default {
           style: 'unordered',
           items: [
             'Keep `props` on the top-level doc. Private implementation helpers do not need entries.',
-            'Keep the doc beside the source and change both in the same pull request.',
+            'Name the doc after the source file beside it, such as `AcmeCarousel.doc.mjs` beside `AcmeCarousel.tsx`, and change both in the same pull request.',
             'If the module later exposes several related public exports, adapt this doc with {@link generic:component-family}.',
           ],
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          presentation: 'summary',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
       ],
     },
@@ -87,6 +86,15 @@ export default {
   ],
 },`,
         },
+        {
+          type: 'prose',
+          text: "Set `keywords` to the words people search for: synonyms and the task the component does, such as `keywords: ['slider', 'slideshow', 'rotating cards']`. `astryx search` ranks a match on a component's name or keywords above one in its description, so without keywords a search for the component's task can list Core components first. Check with the words a person would type:",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx search "rotating cards" --type component',
+        },
       ],
     },
     {
@@ -122,6 +130,7 @@ export default {
             'Set `required: true` only when every caller must pass the prop.',
             'Write `default` exactly as the value should appear in documentation.',
             'Skip styling escape hatches such as `xstyle`, `className`, and `style`.',
+            '`npx astryx doctor integration components` lists a documented prop the code lacks, a public prop the doc misses, and a wrong `required`. See {@link generic:check-the-props}.',
           ],
         },
       ],
@@ -157,7 +166,7 @@ export default {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx component AcmeCarousel\nnpx astryx integration verify',
+          code: 'npx astryx component AcmeCarousel\nnpx astryx doctor integration components\nnpx astryx integration verify',
         },
       ],
     },

package/assets/docs/tree/start-a-template.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/start-a-template`: what a
- * template is, why an integration shares one, whether it is a page or a
- * block, and how to add one.
+ * @file `astryx docs cli/integrations/building-blocks/templates/start-a-template`:
+ * what a template is, why an integration shares one, whether it is a page or
+ * a block, and how to add one.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */

package/assets/docs/tree/subcomponent.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/subcomponent`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/subcomponent`:
  * give one member of a component family its own ComponentDoc.
  */
 
@@ -51,6 +51,7 @@ export default {
   type: 'component',
   name: 'AcmeDialog',
   displayName: 'Acme Dialog',
+  import: '@acme/astryx-widgets/components/AcmeDialog',
   usage: {description: 'Presents a focused task above the current page.'},
   components: [
     {
@@ -82,6 +83,7 @@ export default {
   type: 'component',
   name: 'AcmeDialogHeader',
   displayName: 'Acme Dialog Header',
+  import: '@acme/astryx-widgets/components/AcmeDialogHeader',
   subComponentOf: 'AcmeDialog',
   description: 'Labels an Acme Dialog and holds its close action.',
   props: [
@@ -95,10 +97,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['subComponentOf', 'description', 'props']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
         {
           type: 'list',
@@ -106,7 +106,7 @@ export default {
           items: [
             '`subComponentOf` must exactly match the parent doc\'s `name`.',
             '`description` explains this member\'s role in the family. `usage` is optional; add it when the member needs guidance beyond that sentence.',
-            'The child inherits family fields such as `group`, `category`, `keywords`, `theming`, and `playground` unless it overrides them.',
+            'The CLI does not copy family fields such as `group`, `category`, or `keywords` from the parent to the child. Set any the child needs in its own doc.',
           ],
         },
       ],

package/assets/docs/tree/template-assets.doc.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/template-assets`: make every
- * style, font, icon, and media dependency survive a template copy.
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets`:
+ * make every style, font, icon, and media dependency survive a template copy.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */

package/assets/docs/tree/template-doc-overview.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/template-doc-overview`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/template-doc-overview`:
  * the source and doc file pair, the fields every template doc shares, and how
  * to check what Astryx lists.
  */
@@ -54,22 +54,11 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
+          text: 'The fields below apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
         },
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: [
-              'type',
-              'name',
-              'displayName',
-              'description',
-              'keywords',
-              'isReady',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'list',

package/assets/docs/tree/template-fonts.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-fonts`:
  * use the app typeface by default, and ship every font file a template needs
  * when it must bring its own.
  */

package/assets/docs/tree/template-icons.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-icons`:
  * render template icons through Astryx and ship custom product icons from the
  * package.
  */

package/assets/docs/tree/template-images-media.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-images-media`:
  * keep template images and video working after the copy, or make them clear
  * placeholders.
  */

package/assets/docs/tree/template-styles.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-styles`:
  * style a template with Astryx first, keep editable styles in the file, and
  * ship shared CSS from the package.
  */
@@ -85,7 +85,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). In a TypeScript app, this import type-checks only when the app declares `*.css` modules.',
+          text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). TypeScript 6 and later check side-effect imports by default, so this import type-checks only when the app or its framework declares `*.css` modules.',
         },
       ],
     },

package/assets/docs/tree/templates.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates`: guides for adding,
+ * @file `astryx docs cli/integrations/building-blocks/templates`: guides for adding,
  * documenting, packaging, and testing templates in an integration package.
  */
 

package/assets/docs/tree/test-in-an-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/test-in-an-app`: install the packed
+ * @file `astryx docs cli/integrations/ship/test-in-an-app`: install the packed
  * package in an app and run the commands its users run.
  */
 
@@ -63,11 +63,11 @@ export const docs = {
             ],
             [
               '`template --list --package`',
-              'An `acme-dashboard` entry with `package: @acme/astryx-widgets`',
+              'An `acme-dashboard` entry whose `package` is `@acme/astryx-widgets`',
             ],
             [
               '`theme list --package`',
-              '`- ocean (maintained, @acme/astryx-widgets)`',
+              'An `ocean` entry whose `package` is `@acme/astryx-widgets`',
             ],
             ['`docs acme`', 'Your section, with guides such as `deploying`'],
             [

package/assets/docs/tree/test-template-in-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app`:
  * copy the packed template into a clean app, build it, and render it the way
  * apps will.
  */

package/assets/docs/tree/tokens-and-setup.doc.mjs

@@ -15,13 +15,7 @@ export const docs = {
   category: 'guide',
   description:
     'Using design tokens in custom styles and configuring a StyleX compiler for swizzled components.',
-  keywords: [
-    'StyleX setup',
-    'swizzle',
-    'webpack',
-    'Vite',
-    'Next.js',
-  ],
+  keywords: ['StyleX setup', 'swizzle', 'webpack', 'Vite', 'Next.js'],
 
   sections: [
     {
@@ -77,30 +71,40 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'Astryx components ship pre-compiled: `astryx.css` and each package\'s own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
+          text: "Astryx components ship pre-compiled: `astryx.css` and each package's own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one, importing the component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render. If a swizzled component throws that error, the app is missing a StyleX compiler. The same applies if you author your own StyleX with `stylex.create()`.",
         },
         {
           type: 'table',
           headers: ['Bundler', 'StyleX plugin'],
           rows: [
             ['Webpack', '@stylexjs/webpack-plugin'],
-            ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],
-            ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
-            ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],
+            [
+              'Vite / Rollup',
+              '@stylexjs/rollup-plugin (or a community Vite plugin)',
+            ],
+            [
+              'Babel (any bundler)',
+              '@stylexjs/babel-plugin + @stylexjs/postcss-plugin',
+            ],
+            [
+              'Next.js (App Router, SWC)',
+              'An SWC-based transform; see the Next.js note below',
+            ],
           ],
         },
         {
           type: 'prose',
-          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',
+          text: "Next.js (App Router) is the sharp edge. StyleX's canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.",
         },
         {
           type: 'prose',
-          text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',
+          text: "The repo's `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.",
         },
         {
           type: 'code',
           lang: 'js',
-          label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
+          label:
+            'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
           code: `import stylexPlugin from '@stylexswc/nextjs-plugin';
 
 export default stylexPlugin({
@@ -117,7 +121,7 @@ export default stylexPlugin({
           type: 'list',
           style: 'unordered',
           items: [
-            'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
+            "Symptom of a missing compiler: importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render.",
             'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',
             'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
             'Keep loading `astryx.css` with a StyleX compiler in place. The compiler builds your own and swizzled source only; never add `node_modules/@astryxdesign` to its inputs.',