@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/assets/templates/blocks/components/Hooks/useStreamingTextHookUsage.tsx

@@ -2,29 +2,85 @@
 
 'use client';
 
+import {useCallback, useEffect, useRef, useState} from 'react';
 import {useStreamingText} from '@astryxdesign/core/hooks';
+import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
-import {VStack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+const CHUNKS = [
+  'Astryx hooks keep behavior reusable ',
+  'while components keep visuals consistent. ',
+  'Streaming text arrives in bursts; ',
+  'the hook smooths it into a steady reveal.',
+];
 
-const response =
-  'Astryx hooks keep behavior reusable while components keep visuals consistent.';
+// A fake stream: chunks land in bursts, the way a model streams tokens.
+// Starting again stops the stream in progress, and the last chunk ends it.
+function useFakeStream(onChunk: (chunk: string) => void, onEnd: () => void) {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const start = useCallback(() => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+    }
+    let index = 0;
+    const tick = () => {
+      onChunk(CHUNKS[index]);
+      index += 1;
+      if (index < CHUNKS.length) {
+        timer.current = setTimeout(tick, 350);
+      } else {
+        timer.current = null;
+        onEnd();
+      }
+    };
+    timer.current = setTimeout(tick, 350);
+  }, [onChunk, onEnd]);
+  useEffect(
+    () => () => {
+      if (timer.current) {
+        clearTimeout(timer.current);
+      }
+    },
+    [],
+  );
+  return start;
+}
 
 export default function UseStreamingTextHookUsage() {
-  const displayedText = useStreamingText(response, false, {
-    speed: 'fast',
-  });
+  const [target, setTarget] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
+
+  const appendChunk = useCallback((chunk: string) => {
+    setTarget(previous => previous + chunk);
+  }, []);
+  // When the last chunk has landed, end the stream so the hook snaps to the
+  // full text.
+  const endStream = useCallback(() => setIsStreaming(false), []);
+  const startStream = useFakeStream(appendChunk, endStream);
+
+  const regenerate = useCallback(() => {
+    setTarget('');
+    setIsStreaming(true);
+    startStream();
+  }, [startStream]);
+
+  const displayedText = useStreamingText(target, isStreaming, {speed: 'fast'});
 
   return (
     <Card width={420} padding={4}>
-      <VStack gap={2}>
+      <VStack gap={3}>
         <Text type="body" weight="bold">
           Assistant response
         </Text>
         <Text type="body">{displayedText}</Text>
-        <Text type="supporting" color="secondary">
-          Complete
-        </Text>
+        <Button
+          label={isStreaming ? 'Streaming…' : 'Regenerate'}
+          variant="secondary"
+          size="sm"
+          onClick={regenerate}
+        />
       </VStack>
     </Card>
   );

package/assets/templates/blocks/components/Link/useLinkifyHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useLinkify',
+  name: 'useLinkify — Links in a Comment Thread',
+  displayName: 'useLinkify — Links in a Comment Thread',
+  description:
+    'Plain-text comments where useLinkify turns the URL and the email address into Links, and a custom pattern turns issue references like #123 into tracker links — the patterns option in action. The comment without matches stays plain text.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Link', 'Layout', 'Text'],
+};

package/assets/templates/blocks/components/Link/useLinkifyHookUsage.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLinkify, type LinkifyPattern} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const COMMENTS = [
+  'See https://example.com/spec or email support@example.com.',
+  'Fixed by #123, tracking the regression in #456.',
+  'No links here, just a plain note.',
+];
+
+// Issue references like #123 link into the tracker; the capture group maps
+// onto its URL scheme, showing the patterns option.
+const ISSUE_PATTERN: LinkifyPattern = {
+  pattern: /#(\d+)/g,
+  href: match => `https://example.com/issues/${match[1]}`,
+};
+
+function Comment({children}: {children: string}) {
+  const nodes = useLinkify(children, {patterns: [ISSUE_PATTERN]});
+  return (
+    <Text type="body" color="secondary">
+      {nodes}
+    </Text>
+  );
+}
+
+export default function UseLinkifyHookUsage() {
+  return (
+    <VStack gap={3} style={{width: '100%', maxWidth: 360}}>
+      {COMMENTS.map(comment => (
+        <Comment key={comment}>{comment}</Comment>
+      ))}
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/PowerSearch/usePowerSearchConfigHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'usePowerSearchConfig',
+  name: 'usePowerSearchConfig — Filtered Directory Table',
+  displayName: 'usePowerSearchConfig — Filtered Directory Table',
+  description:
+    'A people directory with a PowerSearch bar over a Table: typed field definitions feed usePowerSearchConfig, returning the search config and an applyFilters helper that updates Table rows.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['PowerSearch', 'Table', 'Layout'],
+};

package/assets/templates/blocks/components/PowerSearch/usePowerSearchConfigHookUsage.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {VStack} from '@astryxdesign/core/Layout';
+import {
+  PowerSearch,
+  usePowerSearchConfig,
+} from '@astryxdesign/core/PowerSearch';
+import type {PowerSearchFilter} from '@astryxdesign/core/PowerSearch';
+import {Table} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+const statusValues = [
+  {value: 'active', label: 'Active'},
+  {value: 'on-leave', label: 'On Leave'},
+  {value: 'contractor', label: 'Contractor'},
+];
+
+const fieldDefs = [
+  {key: 'name', type: 'string', label: 'Name'},
+  {key: 'status', type: 'enum', label: 'Status', enumValues: statusValues},
+  {key: 'startDate', type: 'date', label: 'Start date'},
+] as const;
+
+interface Person extends Record<string, unknown> {
+  id: string;
+  name: string;
+  status: string;
+  startDate: number;
+}
+
+const people: Person[] = [
+  {id: '1', name: 'Alice Chen', status: 'active', startDate: 1672531200},
+  {id: '2', name: 'Bob Dylan', status: 'on-leave', startDate: 1680307200},
+  {id: '3', name: 'Charlie Kim', status: 'active', startDate: 1688169600},
+  {id: '4', name: 'Dana Scully', status: 'contractor', startDate: 1696118400},
+  {id: '5', name: 'Evan Wright', status: 'active', startDate: 1704067200},
+];
+
+const columns: TableColumn<Person>[] = [
+  {key: 'name', header: 'Name'},
+  {
+    key: 'status',
+    header: 'Status',
+    renderCell: (person: Person) =>
+      statusValues.find(s => s.value === person.status)?.label ?? person.status,
+  },
+  {
+    key: 'startDate',
+    header: 'Start Date',
+    renderCell: (person: Person) =>
+      new Date(person.startDate * 1000).toLocaleDateString('en-US', {
+        timeZone: 'UTC',
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }),
+  },
+];
+
+export default function UsePowerSearchConfigHookUsage() {
+  const [filters, setFilters] = useState<PowerSearchFilter[]>([]);
+  const {config, applyFilters} = usePowerSearchConfig(
+    fieldDefs,
+    'PeopleDirectory',
+  );
+  const filteredPeople = applyFilters(filters, people);
+
+  return (
+    <VStack gap={4}>
+      <PowerSearch
+        config={config}
+        filters={filters}
+        onChange={newFilters => setFilters([...newFilters])}
+        placeholder="Filter directory by name, status, start date..."
+        resultCount={filteredPeople.length}
+      />
+      <Table data={filteredPeople} columns={columns} idKey="id" hasHover />
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableRowsVirtualization',
+  name: 'useTableRowsVirtualization - Fixed Height Rows',
+  displayName: 'useTableRowsVirtualization - Fixed Height Rows',
+  description:
+    'A Table with 1,000 product rows in a fixed-height viewport. Scroll vertically to mount the visible rows. The caller keeps all data and columns; this hook does not virtualize columns.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  Table,
+  useTableRowsVirtualization,
+  type TableColumn,
+} from '@astryxdesign/core/Table';
+
+interface Product extends Record<string, unknown> {
+  id: string;
+  name: string;
+}
+
+const products: Product[] = Array.from({length: 1000}, (_, index) => ({
+  id: `product-${index}`,
+  name: `Product ${index + 1}`,
+}));
+const columns: TableColumn<Product>[] = [{key: 'name', header: 'Product'}];
+
+export default function RowsVirtualizationHookUsage() {
+  const virtualization = useTableRowsVirtualization({
+    rowHeight: 56,
+    viewportHeight: 320,
+  });
+  return (
+    <Table
+      data={products}
+      columns={columns}
+      idKey="id"
+      virtualization={virtualization}
+    />
+  );
+}

package/assets/templates/blocks/components/Table/useTableColumnSettingsStateHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableColumnSettingsState',
+  name: 'useTableColumnSettingsState — Column Visibility Picker',
+  displayName: 'useTableColumnSettingsState — Column Visibility Picker',
+  description:
+    'A Table toolbar with a Columns menu of checkboxes: toggling Email updates active columns, Reset restores defaults, and the config is passed directly to useTableColumnSettings.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Button', 'CheckboxInput', 'Popover', 'Table', 'Layout'],
+};

package/assets/templates/blocks/components/Table/useTableColumnSettingsStateHookUsage.tsx

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Popover} from '@astryxdesign/core/Popover';
+import {
+  Table,
+  useTableColumnSettings,
+  useTableColumnSettingsState,
+} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+interface Member extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const members: Member[] = [
+  {id: '1', name: 'Alice', email: 'alice@example.com', role: 'Engineer'},
+  {id: '2', name: 'Bob', email: 'bob@example.com', role: 'Designer'},
+  {id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'Manager'},
+];
+
+const allColumns: TableColumn<Member>[] = [
+  {key: 'name', header: 'Name'},
+  {key: 'email', header: 'Email'},
+  {key: 'role', header: 'Role'},
+];
+
+const columnOptions = [
+  {key: 'name' as const, label: 'Name', isAlwaysVisible: true},
+  {key: 'email' as const, label: 'Email'},
+  {key: 'role' as const, label: 'Role'},
+];
+
+const defaultKeys = ['name', 'email', 'role'];
+
+export default function UseTableColumnSettingsStateHookUsage() {
+  const [activeKeys, setActiveKeys] =
+    useState<ReadonlyArray<string>>(defaultKeys);
+
+  const state = useTableColumnSettingsState({
+    columns: columnOptions,
+    activeColumnKeys: activeKeys,
+    onChangeActiveColumnKeys: setActiveKeys,
+    defaultColumnKeys: defaultKeys,
+  });
+
+  const plugin = useTableColumnSettings<Member>(state.columnSettingsConfig);
+
+  return (
+    <VStack gap={3}>
+      <HStack hAlign="start">
+        <Popover
+          placement="below"
+          label="Column settings"
+          width={200}
+          content={
+            <VStack gap={2}>
+              {columnOptions.map(col => (
+                <CheckboxInput
+                  key={col.key}
+                  label={col.label}
+                  value={state.isColumnActive(col.key)}
+                  isDisabled={!state.isColumnToggleable(col.key)}
+                  onChange={() => state.toggleColumn(col.key)}
+                />
+              ))}
+              <Button
+                label="Reset"
+                size="sm"
+                variant="secondary"
+                onClick={state.resetToDefault}>
+                Reset
+              </Button>
+            </VStack>
+          }>
+          <Button label="Columns" size="sm">
+            Columns
+          </Button>
+        </Popover>
+      </HStack>
+      <Table
+        data={members}
+        columns={allColumns}
+        idKey="id"
+        plugins={{columnSettings: plugin}}
+      />
+    </VStack>
+  );
+}

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

@@ -1129,18 +1129,6 @@ const INITIAL_SAVED_VIEWS: SavedView[] = [
 const COMPACT_SURFACE_QUERY =
   '(max-width: 768px), (max-width: 1024px) and (pointer: coarse) and (hover: none)';
 
-/**
- * Top padding for whatever opens a BottomSheet, on the spacing scale.
- *
- * The panel's grab pill floats over the content instead of reserving layout
- * space for itself: it is 4px centered in a 24px band, so it covers the top
- * 10-14px of the sheet. Content that starts at the usual 16px gutter clears it
- * by 2px, which does not read as a gap — it reads as the sheet being cut off.
- * Opening at the full 24px band puts real space under the pill, and every
- * sheet here uses this one value so they all start on the same line.
- */
-const SHEET_TOP_INSET = 6;
-
 /**
  * Width the filter row holds back, in px, for the readout that trails the
  * clauses — the density toggle, the result count and Clear all.
@@ -1698,6 +1686,7 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-body-size'],
     fontWeight: typeScaleVars['--text-body-weight'],
     height: 'auto',
+    minHeight: 0,
     lineHeight: typeScaleVars['--text-body-leading'],
     paddingBlock: 0,
     paddingInline: 0,
@@ -2052,7 +2041,8 @@ function FilterOverflow({
     <VStack
       gap={2}
       padding={isCompactSurface ? 4 : 0}
-      paddingBlockStart={isCompactSurface ? SHEET_TOP_INSET : 0}>
+      // In a sheet the sheet's band under its grab bar is the top inset.
+      paddingBlockStart={0}>
       {items.map(({child, index}) => (
         <StackItem key={index} xstyle={styles.overflowItem}>
           {child}
@@ -2145,7 +2135,8 @@ function AdaptiveSavedViewForm({
         <Section
           variant="transparent"
           padding={4}
-          paddingBlockStart={SHEET_TOP_INSET}>
+          // The sheet's band under its grab bar is the top inset.
+          paddingBlockStart={0}>
           <VStack gap={4}>
             <HStack gap={2}>
               <StackItem size="fill">
@@ -4090,11 +4081,11 @@ export default function TableFilterTemplate() {
       label="View options"
       height="tall"
       // The tab strip compensates against a container inset, so the sheet
-      // publishes none and the wrapper below owns the top band.
+      // publishes none; its band under the grab bar is the only top inset,
+      // so the strip's own box starts at the tab row and its scroll arrow
+      // lands on the tabs rather than above them.
       padding={0}>
-      {/* The inset is the wrapper's, so the strip's own box starts at the tab
-          row and its scroll arrow lands on the tabs rather than above them. */}
-      <VStack gap={0} paddingBlockStart={SHEET_TOP_INSET}>
+      <VStack gap={0}>
         {/* The heading the popover puts above the pane is dropped here: it
             restates the selected tab word for word, and the strip already
             marks which one that is. On a phone that is a line of vertical
@@ -4148,14 +4139,15 @@ export default function TableFilterTemplate() {
   const detailBody =
     activeJob == null ? null : (
       <VStack gap={0} xstyle={styles.detailPanel}>
-        {/* The only part of the body that knows which host it is in: the sheet
-            needs the pill cleared, the docked panel has no pill and would just
-            sit 8px lower than the panels beside it. The two never coexist —
-            Layout drops the panel entirely on a compact surface. */}
+        {/* The only part of the body that knows which host it is in: in the
+            sheet, the sheet's band under its grab bar is the top inset; the
+            docked panel has no pill and keeps the 16px gutter of the panels
+            beside it. The two never coexist — Layout drops the panel entirely
+            on a compact surface. */}
         <Section
           variant="transparent"
           padding={4}
-          paddingBlockStart={isCompactSurface ? SHEET_TOP_INSET : 4}>
+          paddingBlockStart={isCompactSurface ? 0 : 4}>
           <VStack gap={4}>
             <HStack gap={2}>
               <StackItem size="fill">

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

@@ -1785,12 +1785,9 @@ function ComposeWindow({
       hasScrim={false}
       // The Layout below owns the inset; the sheet adds none of its own.
       padding={0}>
-      {/* The grab handle floats over the top edge, out of flow, about 12px
-          down. The Layout's own padding is not quite enough to clear it — the
-          heading came up level with the pill, four pixels under it — so the
-          sheet buys the handle its own band of space before the content
-          starts. */}
-      <VStack paddingBlockStart={3}>
+      {/* The sheet keeps a band under its grab handle at rest, so the Layout
+          starts below the pill without a band of its own. */}
+      <VStack>
         <Layout
           // auto, not fill: the sheet is sized by this Layout now rather than
           // the other way round. `fill` would stretch it to a height that

package/assets/templates/themes/butter/butterTheme.ts

@@ -260,7 +260,7 @@ export const butterTheme = defineTheme({
     '--color-tint-hover': [neutral.light[0], neutral.dark[100]],
 
     // Typography override
-    '--text-supporting-size': '12px',
+    '--text-supporting-size': '0.75rem', // 12px at the default root size
 
     // Element sizes — slightly taller defaults so the new input padding
     // (--spacing-2 block) has room to breathe.
@@ -394,8 +394,8 @@ export const butterTheme = defineTheme({
       // Radius intentionally not pinned, so buttons keep core's
       // `var(--_button-radius, --radius-element)`: standalone buttons stay 8px,
       // while the chat composer (which sets --_button-radius) rounds them fully.
+      // Inline padding only. Button sets its own block padding and height.
       base: {
-        paddingBlock: 'var(--spacing-3)',
         paddingInline: 'var(--spacing-4)',
       },
       'variant:secondary': SECONDARY_BUTTON,

package/assets/templates/themes/stone/stoneTheme.ts

@@ -240,7 +240,7 @@ export const stoneTheme = defineTheme({
     '--color-tint-hover': [neutral.light[0], neutral.dark[100]],
 
     // Typography override
-    '--text-supporting-size': '12px',
+    '--text-supporting-size': '0.75rem', // 12px at the default root size
 
     // Categorical
     // Light mode pairs pastel stop 90 surfaces with stop 30 foregrounds.

package/assets/templates/themes/y2k/y2kTheme.ts

@@ -236,7 +236,7 @@ export const y2kTheme = defineTheme({
     '--color-tint-hover': [neutral.light[15], neutral.dark[95]],
 
     // Typography override
-    '--text-supporting-size': '12px',
+    '--text-supporting-size': '0.75rem', // 12px at the default root size
 
     // Categorical colors
     '--color-background-green': [green.light[80], green.dark[80]],

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

@@ -46,7 +46,7 @@ export const doc = {
       flag: '--depth <levels>',
       param: 'options.depth',
       description:
-        'How many levels of the docs tree to read below a namespace: 0 for the namespace alone, 1 for its children (what a read without --depth shows), all for everything below it. With it, --detail sets how much of each doc below shows: brief (one line each, the default), compact (with its sections), or full',
+        'How many levels of the docs tree to read below a namespace: 0 for the namespace alone, 1 for its children (what a read without --depth shows), all for everything below it. On the topic list, where a namespace otherwise lists alone, it names the docs below each one by the route that opens them, one line each. With it on a namespace read, --detail sets how much of each doc below shows: brief (one line each, the default), compact (with its sections), or full; the topic list is one line per doc whatever the detail',
     },
   ],
   examples: [
@@ -56,6 +56,10 @@ export const doc = {
     {label: 'One section', cli: 'astryx docs theme quick-start'},
     {label: 'The CLI docs tree', cli: 'astryx docs cli'},
     {label: 'Every CLI doc, one line each', cli: 'astryx docs cli --depth all'},
+    {
+      label: 'Every route in the docs tree, one line each',
+      cli: 'astryx docs --depth all',
+    },
     {
       label: 'The integration guides as one read',
       cli: 'astryx docs authoring --depth all --detail full',

package/clients/cli/commands/docs.mjs

@@ -615,6 +615,32 @@ function summarize(result) {
 
 // ─── Command ─────────────────────────────────────────────────────────────────
 
+/**
+ * Every namespace of the list and, where a `--depth` read carried them, the
+ * docs below it, in reading order and in one flat list: each row's `topic` is
+ * the route that opens it, so the depth of a row never changes how a reader
+ * uses it, and each names the package that owns it.
+ * @param {Array<import('../../../api/docs/docs.type.mjs').DocsListNamespace | import('../../../api/docs/docs.type.mjs').DocsListChild>} rows
+ * @returns {Array<{topic: string, description: string, package: string}>}
+ */
+function flattenNamespaces(rows) {
+  return rows.flatMap(row => [
+    {
+      topic: row.topic,
+      // An experimental doc is marked here as it is wherever else it is
+      // listed, so a reader cannot take a row of this list for a stable doc.
+      description:
+        'stability' in row &&
+        row.stability === 'experimental' &&
+        !/^experimental\b/iu.test(row.description)
+          ? `[experimental] ${row.description}`
+          : row.description,
+      package: row.package,
+    },
+    ...flattenNamespaces(row.children ?? []),
+  ]);
+}
+
 /**
  * @param {import('commander').Command} program
  */
@@ -703,8 +729,10 @@ export function registerDocs(program) {
           // The text view mirrors the JSON list, with the docs tree's
           // namespaces (`meta.namespaces`) first under their own heading: that
           // is where the CLI's own docs start, and a namespace reads
-          // differently from a topic.
-          const namespaces = result.meta?.namespaces ?? [];
+          // differently from a topic. With --depth each branch is flattened
+          // into the same list, so every line is a route a reader can pass
+          // straight back to `docs`.
+          const namespaces = flattenNamespaces(result.meta?.namespaces ?? []);
           const topics = result.data;
           emit(
             ...(namespaces.length > 0

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

@@ -22,6 +22,10 @@ export const doc = {
     "is copied beside it in the package's folder layout. " +
     'Tests, stories and docs are not copied. It lists the npm packages the copy imports, ' +
     'with the ranges the owner package declares, to install if your project lacks them. ' +
+    'An output folder swizzle owns (one the copy ' +
+    'creates, an empty one, or one it marked before) gets an astryx-swizzle.json marker naming ' +
+    "each package its copies came from, so @astryxdesign/build's Babel, PostCSS and Vite " +
+    'integrations, and withAstryx() under webpack, compile the copy below your theme. ' +
     'With no name it lists the swizzlable components. ' +
     'An integration component that replaces a Core component is what that Core name ' +
     'copies; --package @astryxdesign/core copies the original. --list lists Core ' +

package/clients/cli/commands/swizzle.mjs

@@ -113,6 +113,18 @@ export function registerSwizzle(program) {
         );
       }
 
+      const {marker} = result.data;
+      if (marker) {
+        const folder = marker.path.replace(/\/?astryx-swizzle\.json$/, '') || '.';
+        out.push(
+          text(
+            marker.written
+              ? `Marked ${folder}/ with astryx-swizzle.json: with @astryxdesign/build's Babel, PostCSS and Vite integrations, or withAstryx() under webpack, every module under it compiles below your theme, so theme overrides reach the copy. Keep only swizzled copies there. Turbopack does not read the marker yet.`
+              : `Did not mark ${folder}/ with astryx-swizzle.json: it already holds ${(marker.found ?? []).join(', ')} and no astryx-swizzle.json. If it holds only swizzled copies, add ${marker.path} to mark it, so theme overrides reach them; keep the product's own components out of a marked folder.`,
+          ),
+        );
+      }
+
       // StyleX build requirement — swizzled StyleX source throws on import
       // ("Unexpected 'stylex.create' call at runtime") unless the consumer's
       // build runs a StyleX compiler, so the page does not render at all.