@astryxdesign/cli 0.7.2-canary.c9f2659 → 0.7.2-canary.cbb7fa3

package/assets/templates/blocks/components/Drawer/DrawerStart.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state and the logical start edge
+ * @output A Drawer that opens from the start side of the viewport
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerStart() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open start drawer" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Navigation"
+        side="start">
+        <Layout
+          header={<DrawerHeader title="Navigation" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <Text type="body">
+                The start edge follows the page's writing direction.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/Drawer/DrawerWidths.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Width budget: pixels or any CSS length',
+  displayName: 'Width budget: pixels or any CSS length',
+  description:
+    'Compare a numeric pixel width with rem and percentage lengths. The width budget also caps the drawer on mobile.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'HStack',
+    'DrawerHeader',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerWidths.tsx

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A pixel, rem, or percentage width and controlled open state
+ * @output A Drawer demonstrating the selected width budget
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {HStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerWidths() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [width, setWidth] = useState<number | string>(320);
+
+  function openAtWidth(value: number | string) {
+    setWidth(value);
+    setIsOpen(true);
+  }
+
+  return (
+    <>
+      <HStack gap={2}>
+        <Button label="320px" onClick={() => openAtWidth(320)} />
+        <Button label="32rem" onClick={() => openAtWidth('32rem')} />
+        <Button label="50%" onClick={() => openAtWidth('50%')} />
+      </HStack>
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Width budget"
+        width={width}>
+        <Layout
+          header={
+            <DrawerHeader title="Width budget" onOpenChange={setIsOpen} />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                Width: {typeof width === 'number' ? `${width}px` : width}
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'DrawerHeader',
+  displayName: 'Drawer Header',
+  description:
+    'DrawerHeader provides a structured header for drawers with slots for title, subtitle, close button, and optional start or end content.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['DrawerHeader', 'Layout', 'LayoutContent', 'Text'],
+};

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderShowcase.tsx

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Static header content: title, subtitle, a no-op close handler, and a divider
+ * @output The DrawerHeader row at the top of a square-cornered, drawer-width panel, visible without opening an overlay
+ * @position DrawerHeader's docsite showcase. Drawer has no inline mode
+ *   like Dialog's isInline, so a plain panel stands in for the drawer; in an
+ *   app, compose DrawerHeader in a Layout header slot inside a Drawer.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {DrawerHeader} from '@astryxdesign/core/Drawer';
+import {
+  Layout,
+  LayoutContent,
+  overlayPaddingReset,
+} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {
+  borderVars,
+  colorVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+  // A card-like panel with square corners, matching the drawer's own corners.
+  panel: {
+    width: 360,
+    maxWidth: '100%',
+    boxSizing: 'border-box',
+    backgroundColor: colorVars['--color-background-card'],
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: 0,
+  },
+  body: {
+    padding: spacingVars['--spacing-4'],
+    backgroundColor: colorVars['--color-background-muted'],
+    borderRadius: 0,
+  },
+});
+
+export default function DrawerHeaderShowcase() {
+  return (
+    // Like the Drawer root, the panel is a padding boundary, so the Layout
+    // regions inset by their own --spacing-4 default: the drawer's inset.
+    <div {...stylex.props(styles.panel, overlayPaddingReset.reset)}>
+      <Layout
+        height="auto"
+        header={
+          <DrawerHeader
+            title="Host details"
+            subtitle="web-prod-04"
+            onOpenChange={() => {}}
+            hasDivider
+          />
+        }
+        content={
+          <LayoutContent>
+            <div {...stylex.props(styles.body)}>
+              <Text type="body" color="secondary">
+                Drawer body content goes here.
+              </Text>
+            </div>
+          </LayoutContent>
+        }
+      />
+    </div>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderSubtitleEndContent.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'With subtitle and end content',
+  displayName: 'With subtitle and end content',
+  description:
+    'Add a subtitle under the title and put a status, such as a Badge, in endContent. The close button stays at the end of the row.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Badge',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderSubtitleEndContent.tsx

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A DrawerHeader with a subtitle, a status badge in its end slot, and a close button
+ * @position Copyable DrawerHeader example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerHeaderSubtitleEndContent() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open host details" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="web-prod-04"
+        width={360}>
+        <Layout
+          header={
+            <DrawerHeader
+              title="web-prod-04"
+              subtitle="us-east-1"
+              endContent={<Badge label="Healthy" variant="success" />}
+              onOpenChange={setIsOpen}
+            />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                All 6 instances are passing readiness checks.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderWithCloseButton.doc.mjs

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'With close button',
+  displayName: 'With close button',
+  description:
+    'Pass onOpenChange to render a close button that calls it with false. Drawer renders no close button of its own, so this is the usual visible way to close.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderWithCloseButton.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A Drawer whose DrawerHeader renders a close button because it receives onOpenChange
+ * @position Copyable DrawerHeader example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerHeaderWithCloseButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open drawer" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Details"
+        width={360}>
+        <Layout
+          header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <Text type="body">
+                Passing onOpenChange renders the close button, which calls it
+                with false.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/pages/detail-page/page.tsx

@@ -600,9 +600,9 @@ export default function DetailPage2Template() {
         }
         end={!isNarrow && showSidePanel ? <RightPanel /> : undefined}
       />
-      {/* Mobile: the side panel content opens as a full-screen dialog. (A
-          side drawer/sheet would be more idiomatic, but Astryx has no Drawer
-          component yet — #2575 — so we use the fullscreen Dialog variant.) */}
+      {/* Mobile: the side-panel content uses the full viewport so order details
+          are not squeezed beside narrow page chrome. Drawer remains available
+          for side-overlay flows that intentionally preserve page context. */}
       <Dialog
         variant="fullscreen"
         isOpen={isNarrow && isPanelDialogOpen}

package/assets/templates/pages/table-inbox/page.tsx

@@ -1652,8 +1652,8 @@ const COMPOSER_TOOLS: {
 /**
  * The compose sheet.
  *
- * **`BottomSheet hasScrim={false}`, which is the only non-modal surface in
- * core.** With the scrim off the sheet opens with `show()` rather than
+ * **`BottomSheet hasScrim={false}` keeps this bottom-edge composer non-modal.**
+ * With the scrim off the sheet opens with `show()` rather than
  * `showModal()`, so it never enters the top layer, never makes the page inert
  * and never locks body scroll: the inbox behind it stays live. That matters
  * more here than anywhere else in this template, because writing a message is
@@ -1661,12 +1661,14 @@ const COMPOSER_TOOLS: {
  * actually said, copy an order number out of a thread. A modal composer
  * answers that with "close me first".
  *
- * The trade is position, and it is worth naming. A sheet rises from the bottom
- * edge, centred: its positioner is `inset-inline: 0` with
- * `justify-content: center`, and there is no anchor, side or width prop. So
- * this cannot be docked to the inline-end corner the way a `Dialog` can be.
- * `Dialog` takes a static `position` and would put the window in that corner —
- * but `Dialog` is always modal, so buying the corner costs the live inbox.
+ * The trade is bottom-edge geometry, and it is worth naming. A non-modal
+ * `Drawer` keeps page context live from an inline edge, but it is a full-height
+ * side panel; this composer intentionally rises from the bottom. A sheet's
+ * positioner is `inset-inline: 0` with `justify-content: center`, and there is
+ * no anchor, side or width prop. So this cannot be docked to the inline-end
+ * corner the way a `Dialog` can be. `Dialog` takes a static `position` and would
+ * put the window in that corner — but `Dialog` is always modal, so buying the
+ * corner costs the live inbox.
  * `ChatComposerDrawer` is a false friend: despite the name it is an in-flow
  * disclosure tray for a ChatComposer's attachments, with no positioning of its
  * own.

package/authoring/doctypes/base/type.ts

@@ -383,6 +383,12 @@ export interface ComponentPropDoc {
    *  ```
    */
   slotElements?: ComponentSlotElement[];
+  /** Lifecycle marker for a prop outside the stable compatibility promise
+   *  (spec:AST-017 FR21). Set `'experimental'` on a stable component's
+   *  optional `experimental` prop object, and say in `description` that its
+   *  contents may change or be removed in a patch release. Omit for stable
+   *  props. */
+  stability?: 'experimental';
 }
 
 /**

package/authoring/doctypes/component/component.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
       name: 'name',
       type: 'string',
       description:
-        "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
+        "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
       required: true,
     },
     {
@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package's peer range starts at the release that applies it, `\"@astryxdesign/cli\": \">=0.6.7\"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+        'Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package\'s peer range starts at the release that applies it, `"@astryxdesign/cli": ">=0.6.7"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.',
     },
     {
       name: 'keywords',
@@ -181,13 +181,13 @@ export const doc = {
       name: 'props',
       type: 'ComponentPropDoc[]',
       description:
-        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
+        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?, stability?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
     },
     {
       name: 'components',
       type: '(ComponentEntry | ComponentRef)[]',
       description:
-        'MultiComponentDoc variant (required there): one entry per public component/hook exported from the directory. Each entry is a full ComponentEntry (inline: name, displayName, description, props | params+returns) or a name-only ComponentRef pointing at a sibling {Name}.doc.mjs.',
+        'MultiComponentDoc variant (required there): one entry per public component/hook exported from the directory. Each entry is a full ComponentEntry (inline: name, displayName, description, props | params+returns) or a name-only ComponentRef pointing at a sibling {Name}.doc.mjs. In an integration, each full entry the module named by `import` exports is a component under its own name.',
     },
     {
       name: 'subComponentOf',

package/authoring/doctypes/component/type.ts

@@ -33,9 +33,12 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   type?: 'component';
   /**
    * Stable machine identity and directory name without the Astryx prefix,
-   * PascalCase (for example `Button`, `Table`, or `AppShell`). Do not change
-   * this to edit the visible label; use `displayName` for that. Registry URLs
-   * derive from this value by default.
+   * PascalCase (for example `Button`, `Table`, or `AppShell`). For an
+   * integration component it is the export apps import: the doc sits beside
+   * the file that exports it, and when that file exports nothing under its own
+   * name, `name` may name the export it does have. Do not change this to edit
+   * the visible label; use `displayName` for that. Registry URLs derive from
+   * this value by default.
    */
   name: string;
   /** Human-readable display name with spaces between words, used by the

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -9,6 +9,9 @@
  *   - Multi-file write is atomic: if one file fails, none are left behind.
  *   - An `--out` escape, or an output directory that cannot be created, fails
  *     with a registered error code.
+ *   - Every output stays inside the working directory: an absolute `--out`
+ *     path or a theme file outside it fails before anything is written, while
+ *     absolute paths inside it build, also through a symlinked spelling.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
@@ -129,6 +132,68 @@ describe('theme build output-path failures carry registered codes', () => {
     expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
   });
 
+  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const out = path.join(outside, 'ocean.css');
+
+    for (const extra of [[], ['--check']]) {
+      const {result, envelope} = await buildJson(
+        [path.relative(project, themeFile), '--out', out, ...extra],
+        project,
+      );
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it', async () => {
+    const project = path.join(tmpDir, 'project');
+    fs.mkdirSync(project, {recursive: true});
+    const shared = path.join(tmpDir, 'shared');
+    const themeFile = writeTheme(shared, 'ocean');
+
+    for (const file of [themeFile, path.relative(project, themeFile)]) {
+      const {result, envelope} = await buildJson([file], project);
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
+
+  it('builds absolute paths inside the project, also when they reach it through a symlink', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const alias = path.join(tmpDir, 'alias');
+    fs.symlinkSync(project, alias, 'dir');
+
+    for (const [args, written] of [
+      [
+        [themeFile, '--out', path.join(project, 'dist', 'direct.css')],
+        path.join(project, 'dist', 'direct.css'),
+      ],
+      [
+        [themeFile, '--out', path.join(alias, 'dist', 'aliased.css')],
+        path.join(project, 'dist', 'aliased.css'),
+      ],
+      [
+        [path.join(alias, 'themes', 'theme.mjs')],
+        path.join(project, 'themes', 'ocean.css'),
+      ],
+    ]) {
+      const {result, envelope} = await buildJson(args, project);
+
+      expect(result.code).toBe(0);
+      expect(envelope.type).toBe('theme.build');
+      expect(fs.existsSync(written)).toBe(true);
+    }
+  });
+
   it('reports an --out path that escapes through a symlink as ERR_PATH_TRAVERSAL', async () => {
     const project = path.join(tmpDir, 'project');
     const outside = path.join(tmpDir, 'outside');
@@ -177,4 +242,23 @@ describe('theme build output-path failures carry registered codes', () => {
       code: ERROR_CODES.ERR_PATH_TRAVERSAL,
     });
   });
+
+  it('themeBuild() rejects an output outside cwd: an absolute out path, or the default beside a theme file outside cwd', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = writeTheme(path.join(project, 'themes'), 'ocean');
+    const shared = path.join(tmpDir, 'shared');
+    const outsideTheme = writeTheme(shared, 'ocean');
+    const outDir = path.join(tmpDir, 'out');
+
+    for (const [file, options] of [
+      [path.relative(project, inside), {out: path.join(outDir, 'ocean.css')}],
+      [outsideTheme, {}],
+    ]) {
+      await expect(
+        themeBuild(file, options, {cwd: project}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+    }
+    expect(fs.existsSync(outDir)).toBe(false);
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
 });

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

@@ -126,7 +126,10 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    const result = await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    const result = await runCli(
+      ['theme', 'build', themeFile, '-o', outFile],
+      tmpDir,
+    );
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(result.status).toBe(0);
@@ -148,7 +151,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    await runCli(['theme', 'build', themeFile, '-o', outFile], tmpDir);
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(css).toContain('.astryx-text-input');

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

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory (ERR_PATH_TRAVERSAL). Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). Every output must resolve inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL). Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',

package/clients/cli/lib/component-format.mjs

@@ -68,8 +68,12 @@ function formatPropsTable(props) {
   for (const p of props) {
     const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
+    // The text projection of the prop doc's `stability` field: an
+    // experimental prop is outside the stable compatibility promise.
+    const stability =
+      p.stability === 'experimental' ? ' **(experimental)**' : '';
     lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req}${stability} |`,
     );
   }
   return lines.join('\n');