What's New

Release notes and changelog for all packages.

0.7.1

Fixes
  • CommandPaletteInput now exposes the semantics and name that its visible state promises. (#7321)
    • A standalone field with no popup attributes was role="combobox" with aria-expanded="true" and aria-autocomplete="list"; it is now role="searchbox" with no popup state. Pass role="combobox", or your popup's own ARIA attributes, to keep the old semantics. A field that already passes popup attributes (aria-expanded, aria-controls, aria-owns, aria-haspopup, and the like) stays a combobox and keeps them, and a field inside CommandPalette is unchanged.
    • The field's default accessible name was its placeholder (Search…, or the caller's placeholder); it is now Search commands, translated. Pass label to keep a specific name, for example label="Search…" for the old default. A caller whose custom placeholder served as the name keeps working code and hears the generic name until it passes label.
    • The CLI's async-search CommandPalette block names its field Search files.
    • endContent={true} no longer renders an empty trailing slot, and endContent={0} renders inside the trailing slot instead of after it.
  • Stone, Y2K, and Gothic set CodeBlock's diff row slots in their own syntax palettes, so a reader of a diff on those themes gets added and removed rows whose code, line numbers, and +/- glyphs stay readable: every syntax token keeps at least 4.5:1 on the tinted rows in Stone (light and dark) and Y2K (light and dark), and in Gothic the rows take a deep green and a deep red at the background's own luminance, so every token keeps the contrast it has on the plain background. Line numbers and glyphs on changed rows use each theme's own green and red. The CLI's bundled copies of the three themes (astryx theme eject) carry the same palettes. (#7428)
  • A secondary Selector, MultiSelector, or ComplexSelector now matches the theme's secondary Button: under butter, chocolate, gothic, stone, and y2k it takes that Button's border, fill, text color, and hover instead of the default borderless neutral fill, so a toolbar mixing secondary buttons and selectors reads as one set of controls. Disabled and read-only triggers keep a still fill on hover, as a disabled Button does, and a Selector or MultiSelector inside an InputGroup keeps the group's neutral fill and edges. The default theme is unchanged, the selector docs now say secondary follows the theme's secondary Button, and themes added with the CLI get the same parity. (#7548)
  • astryx theme build --watch stops as soon as it is interrupted (Ctrl-C or SIGTERM). A change saved while a rebuild was running no longer starts another rebuild after "Stopped watching.", and a rebuild in progress stops with the watcher instead of keeping the process alive. (#7508)
Performance
  • astryx search and astryx build, and the search and build API functions, read each source directory once per call instead of once per candidate. Results are unchanged. A warm search drops from about 1.9 s to 0.4 s on macOS. (#7421)
Documentation
  • The generated token docs list the five diff row slots of the syntax vocabulary — --color-syntax-added, --color-syntax-removed, --color-syntax-diff-header, --color-syntax-added-marker, --color-syntax-removed-marker — with their defaults, so astryx docs tokens describes nineteen syntax slots. (#7389)
  • The Tailwind and migration setup docs now say that globals.css (or a layers.css holding only the @layer line) must be the first import in the root layout or app entry, before the astryx-themes module or any component that imports theme CSS; otherwise Tailwind preflight overrides Astryx base styles and theme overrides lose. The Tailwind v3 coexistence snippet moves its @layer line into a layers.css imported first, because Next.js (webpack or Turbopack) hoists CSS imports above an inline @layer line. (#7534)
  • Grid's columns docs now lead with the shape that reflows: a numeric columns is exactly N columns at every width and never reflows, and columns={{minWidth, max}} is the form for columns that must survive a phone. The astryx docs layout/responsive topic gains a "Columns that reflow" section with a reflowing stat row beside a fixed week row. No behavior changes. (#7340)
  • The styling setup docs now load the prebuilt stylesheets on every path. The "StyleX from source" path becomes "StyleX for your own code": it keeps astryx.css and points the StyleX compiler at your own and swizzled source only. A new "Other Astryx packages" section lists each package's stylesheet (richtext.css, lab.css, charts.css) and where to import it. Getting started no longer lists the two example setups that compile Astryx source; the remaining examples all load astryx.css. (#7587)
Contributors
Thanks to everyone who contributed to this release:

0.7.0

Breaking Changes
  • theme add now imports built themes; use theme eject to copy theme source. (#7138) The old contract copied theme source with theme add <slug> [path] [--overwrite] [--package <package>] and returned theme.add JSON. The ThemeAddResponse type and the theme.add response type are removed, with their ThemeAddResponse.type, ThemeAddResponse.data, and ThemeAddResponse.meta fields. The replacement imports the built theme with theme add <slug> [--package <package>] and returns theme.app; --import remains an accepted no-op. Plain theme add now returns theme.app with the owner package directly after type. Local themes carry no package.
    A path after theme add now exits 1 with ERR_INVALID_ARGUMENT, and --overwrite exits 1 with ERR_INVALID_OPTION; neither writes files. To migrate a script that copied source, run theme eject with the same slug, path, --overwrite, and --package arguments. A script that already runs theme add --import keeps the same meaning and needs no change.
  • init --remove-agents says when there was nothing to remove. (#6623) Migration: a consumer reading data.removed as a boolean keeps working; a consumer that narrowed on the literal true must accept the corrected value.
  • Four commands refuse silently ignored option pairs. (#7132) Migration: remove the option the command was ignoring.
  • Refuse invalid input that used to silently succeed. (#7149) Migration: pass a valid type or package, an integer limit, or the documented arguments, and catch ERR_AMBIGUOUS_COMPONENT for a multi-package name.
  • An empty-string argument no longer discards the rest of the command. (#6620) Migration: remove the empty string from the invocation; omit the argument to list.
  • doctor integration validate exits 1 when there is no package.json. (#7150) A missing package.json now produces a no_package error, so the existing error-severity exit rule applies. A directory with package.json but no integration manifest still exits 0.
    Migration: run the command in a directory that has a package.json, or handle exit 1 for that case.
  • Move canonical data-color defaults from generated theme CSS to the public StyleX dataVars group. (#6834) Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Canvas and other non-CSS APIs continue to use resolveThemeToken() or useTheme().token(). Rebuild committed theme CSS with astryx theme build; concrete themes now emit only explicitly authored data-color overrides.
    Old usage: Generated theme CSS owned the canonical --color-data-* root defaults.
    Replacement: The public StyleX dataVars group in @astryxdesign/core/theme/dataTokens.stylex owns the defaults; concrete themes emit only explicitly authored data-color overrides.
    Migration: Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Canvas and other non-CSS APIs continue to use resolveThemeToken() or useTheme().token(). Rebuild committed theme CSS with astryx theme build.
    Codemod: astryx upgrade runs validate-data-token-ownership, which rewrites nothing and reports fallback-less var(--color-data-*) uses (whole or embedded source strings, and stylesheets) and stale generated theme CSS for manual migration.
  • Doctor fails when the CLI cannot load what astryx.config asks for (#7130) A new configured-integrations check fails when an integration named in astryx.config cannot be loaded: not installed, installed without a manifest, or a manifest that throws or fails its schema. Such an integration is withdrawn whole and contributes nothing. The config check fails, instead of warning, when astryx.config imports but the CLI cannot load the project from it.
    Unchanged: a problem inside one contribution kind (an invalid component doc, a missing or unreadable root, or an unresolved replacement) stays a warning under integration-issues, and an autolinked dependency that cannot be loaded stays informational.
    No codemod applies: nothing in a project's source changes; install the integration, repair its manifest, or edit integrations in astryx.config.
    What counts as configured is every name astryx.config lists, including a package set aside for a provider conflict and the package being authored when its own config names it. Migration: install the integration, fix its manifest, or remove it from integrations; fix the astryx.config field the message names.
  • Typeahead, Tokenizer, CheckboxList, RadioList, and Slider no longer accept root xstyle, className, or style. Style the field with containerXstyle/containerClassName/containerStyle (the Field box; no effect inside InputGroup or a horizontal-labels FormLayout) and the visual control box with controlXstyle/controlClassName/controlStyle. Base props now reach the primary semantic control: the combobox input for Typeahead and Tokenizer, the role="group"/role="radiogroup" element for CheckboxList and RadioList, and the role="slider" thumb for Slider (the role="group" control in range mode). A caller aria-describedby is kept alongside the field's own description and status, on these components and on TextInput, TextArea, and NumberInput, which previously dropped it. CLI templates use the new props. (#7339) Migration: rename root xstyle/className/style to the part they styled before: containerXstyle/containerClassName/containerStyle on all five components, except a Typeahead inside InputGroup, whose root styling painted the control surface and moves to controlXstyle/controlClassName/controlStyle. The release's astryx upgrade codemod, migrate-field-input-styling, performs these renames on JSX usage.
    Not rewritten by the codemod, so update by hand:
    • ref and id, plus data-* (except Typeahead and Tokenizer data-testid, which marked the control surface), aria-*, and DOM event handlers such as onClick, previously landed on the outer Field (or were dropped by RadioList and Slider). They now land on the primary semantic control. Update code that measured, queried, or listened on the outer field, and wrap the component in your own element when you need an outer boundary.
    • Typeahead and Tokenizer refs are now HTMLInputElement.
    • A consumer onKeyDown on Typeahead or Tokenizer still runs after the built-in key handling, cannot cancel it, and still fires for keys on the clear button and tokens; for keys on the input it now runs on the combobox input itself.
    • RadioList and Slider used to drop DOM event handlers; they now run after the component's own handling, so a Slider onPointerDown, onKeyDown, onFocus, or onBlur that never fired before now fires (on the thumb, or on the group in range mode).
    • Tokenizer's onFocus/onBlur keep their meaning: focus entering or leaving the field.
    • Styling passed through a wrapper's own props or a spread is not rewritten and now fails type-checking at that callsite.
    Untyped callers get a development warning and the value is ignored.
    From #5656 by @harjothkhara.
  • Selector, MultiSelector, and ComplexSelector no longer accept root xstyle, className, or style. Style the field with containerXstyle/containerClassName/containerStyle (the Field box; no effect inside InputGroup, a horizontal-labels FormLayout, or with renderTrigger) and the visual control box with controlXstyle/controlClassName/controlStyle. Base props such as ref, id, data-* (including data-testid), aria-*, and DOM handlers reach the trigger button that carries the combobox role (or, with renderTrigger, the caller's control), and a caller aria-describedby is kept alongside the field's own description and status instead of being replaced. Handlers keep their existing order: a ComplexSelector onClick on its own trigger can still cancel opening, and newly forwarded handlers (including those reaching a renderTrigger control) run after the built-in toggle and keyboard handling. CLI templates use the new props. (#7341) Migration: rename root xstyle/className/style on these components to controlXstyle/controlClassName/controlStyle, which style the same element as before. Not a rename: a data-testid or other base prop now lands on the trigger button rather than the bordered box around it (query the box with .closest() if a test measured it), and with renderTrigger base props and ref now reach the caller's control. Rename JSX usage by hand, or run astryx upgrade; it runs migrate-field-input-styling, which does not follow styling passed through a wrapper's own props or a spread, which now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored.
    From #5656 by @harjothkhara.
  • TextInput, TextArea, NumberInput, and FileInput no longer accept root xstyle, className, or style. Style the field with containerXstyle/containerClassName/containerStyle (the Field box; no effect inside InputGroup or a horizontal-labels FormLayout) and the visual control box with controlXstyle/controlClassName/controlStyle. Base props such as ref, id, data-*, aria-*, and DOM handlers reach the native control, and a caller id is now honored there. CLI templates use the new props. (#7336) Migration: rename root xstyle/className/style on these components to controlXstyle/controlClassName/controlStyle, which style the same element as before. astryx upgrade rewrites JSX usage; styling passed through a wrapper's own props or a spread is not rewritten and now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored. Not rewritten by the codemod: a caller id used to be replaced by a generated one and now reaches the native control (the label stays associated), so remove an id you passed but relied on being ignored. Other base props already reached the native control and are unchanged.
    From #5656 by @harjothkhara.
  • matcha's and y2k's spacing steps are rem (--spacing-2: 0.75rem), so their gaps and padding follow the reader's root font size like the core scale. Every step is the same pixel value at the default 16px root; a reader with a larger root font size now sees proportionally larger spacing on these themes. The CLI's copies of both theme templates and the annotated theme template's spacing example change the same way. (#7374) Migration: nothing to change to take the new behaviour. To keep fixed pixel spacing on one of these themes, extend it and override the steps in px, which is honoured as written: defineTheme({name: 'app', extends: matchaTheme, tokens: {'--spacing-2': '12px'}}).
  • On touch devices narrower than the lg breakpoint ((width < 1024px) and (pointer: coarse)), the 14px-base first-party themes now floor their type base to 16px and re-derive the ratio so Display 1 keeps its desktop size: neutral and chocolate (base 14, ratio 1.2 → 1.1736) and butter and stone (base 14, ratio 1.25 → 1.2225). On phones, body, label and code text rise from 14px to 16px; supporting text, the headings and Display 2 and 3 grow by 1–2px; only Display 1 holds its desktop size. Desktop sizes are unchanged. gothic, matcha and y2k already use a 16px base and need no rule. The CLI's theme templates carry the same rule, so a newly scaffolded theme gets it too. (#6699) An app theme that extends one of these four themes and sets its own typography.scale or type-size tokens inherits this rule, and on touch + narrow screens the rule replaces those values (a base-18 child drops to a 16px body and a 42px Display 1). Append your own rule for the same condition with the values you want; a later rule for the same condition wins.
    Migration: nothing to change to take the new phone scale. To keep the previous 14px phone scale in an app, extend the theme and append a later rule for the same condition: defineTheme({name: 'app', extends: neutralTheme, adaptations: {rules: [{when: {pointer: 'coarse', width: {below: 'lg'}}, value: {typography: {scale: {base: 14, ratio: 1.2}}}}]}}). For butter and stone use ratio: 1.25 and also set tokens: {'--text-supporting-size': '12px'} in that rule's value, because those themes pin supporting text at 12px rather than the 11px the scale alone gives. This cannot be rewritten by a codemod: whether an app wants the floor is a product choice.
  • Stop reading the Astryx-owned agent variables ASTRYX_AGENT_ID, ASTRYX_AGENT_SESSION_ID, and ASTRYX_AGENT_METADATA (#7127) The theme-import change already stopped reading ASTRYX_THEME; these three were the last Astryx-owned agent variables. A test now fails on any process.env.ASTRYX_* read in the CLI source.
    Migration: set AGENT and AGENT_SESSION_ID, which the CLI already reads, instead of the Astryx-prefixed variants. ASTRYX_AGENT_METADATA has no replacement variable.
  • Remove the deprecated component-theming compatibility surface scheduled for 0.7.0. Components now emit only canonical target classes and reflected data-* prop/state selectors. Theme discovery and build output no longer expose deprecated targets, and ThemePropsOptions plus ComponentThemingTarget.deprecatedFor are removed. The theme targets --json response drops the ThemeTargetEntry.deprecatedFor field, because no target it lists is deprecated. (#7302) Migration: run the required codemod migrate-deprecated-theme-surface with astryx upgrade --from <your 0.6 version> --apply --path . after upgrading.
    The codemod renames removed target keys inside theme components maps (an imported defineTheme() call, an object typed as an Astryx theme, or a theme object with a static name), renames target classes in CSS, and replaces target-qualified bare prop/value/state classes with reflected data-* selectors, using every bare class the final 0.6 release emitted. It leaves dynamic/computed theme keys, unqualified or unknown classes, and CSS embedded in JavaScript/TypeScript strings for manual review. It adds TODO(astryx upgrade) when old and canonical keys coexist, and when a bare class Astryx once emitted has no known meaning on the target it qualifies.
    The four per-component clear-icon aliases all become the shared input-clear-icon, which styles every input's clear icon. In CSS the codemod keeps each rule on its component with :where(.astryx-<component> *), which adds no specificity. Theme keys cannot carry that scope, so the codemod adds a TODO naming the CSS selector to use.
    Code that passed {legacyNames} to themeProps() or set deprecatedFor in a component doc should delete that argument or field; the canonical target is unchanged.
    Rename theme keys and CSS target classes with this complete mapping:
    • base-table → table
    • checkbox → checkbox-indicator
    • codeblock → code-block
    • codeblock-copy-button → code-block-copy-button
    • codeblock-header → code-block-header
    • codeblock-title → code-block-title
    • date-input-clear-icon → input-clear-icon
    • date-range-input-clear-icon → input-clear-icon
    • hovercard → hover-card
    • multi-selector-clear-icon → input-clear-icon
    • navicon → nav-icon
    • popover-surface → popover
    • progressbar → progress-bar
    • progressbar-fill → progress-bar-fill
    • progressbar-mark → progress-bar-mark
    • progressbar-track → progress-bar-track
    • radio → radio-indicator
    • radio-dot → radio-indicator-dot
    • selector-clear-icon → input-clear-icon
    • statusdot → status-dot
    • textarea → text-area
    For custom CSS, replace removed bare selectors with the corresponding reflected attribute on a canonical target—for example, .astryx-button.primary.sm becomes .astryx-button[data-variant="primary"][data-size="sm"], and .astryx-switch.checked becomes .astryx-switch[data-checked="checked"]. Review unqualified classes such as .primary manually because they may be application-owned.
  • Remove the astryx layout command group. (#7137) Removes the deprecated astryx layout command group (expand, check, grammar), its three response types (layout.expand, layout.check, layout.grammar), and the programmatic API exports (layoutExpand, layoutCheck, layoutGrammar).
    Use astryx build to choose the template to start from, astryx template to scaffold it, and astryx docs layout for layout guidance. The layout guide is unaffected. The error codes ERR_LAYOUT_PARSE and ERR_LAYOUT_INVALID are retained.
    Removed JSON ids: LayoutBlockReference.mode LayoutBlockReference.name LayoutCheckOptions.cwd LayoutCheckOptions.form LayoutCheckOptions.loose LayoutCheckResponse.data LayoutCheckResponse.data.compact LayoutCheckResponse.data.errors LayoutCheckResponse.data.form LayoutCheckResponse.data.outline LayoutCheckResponse.data.valid LayoutCheckResponse.data.warnings LayoutCheckResponse.type LayoutExpandOptions.cwd LayoutExpandOptions.form LayoutExpandOptions.loose LayoutExpandOptions.name LayoutExpandOptions.targetPath LayoutExpandResponse.data LayoutExpandResponse.data.blocksReferenced LayoutExpandResponse.data.code LayoutExpandResponse.data.componentsUsed LayoutExpandResponse.data.demoMediaReplaced LayoutExpandResponse.data.form LayoutExpandResponse.data.states LayoutExpandResponse.data.todos LayoutExpandResponse.data.warnings LayoutExpandResponse.data.written LayoutExpandResponse.type LayoutGrammarOptions.cwd LayoutGrammarResponse.data LayoutGrammarResponse.data.aliases LayoutGrammarResponse.data.text LayoutGrammarResponse.type LayoutIssue.col LayoutIssue.formatted LayoutIssue.line LayoutIssue.message LayoutIssue.suggestions
  • Spacing tokens are rem (--spacing-2: 0.5rem), so gaps and padding follow the reader's root font size the way the type scale does. Every token value is unchanged at the default 16px root. (#7359) One change shows at the default root: the useTableRowExpansion chevron now sits centered in its fixed 40px column instead of running past its edge (its button moves from 24–48px to 8–32px of the column). Under a theme with a larger spacing scale, such as matcha, the chevron is visible again and the detail panel lines up with the first column instead of starting 20px past it.
    Old usage: The --spacing-* defaults were fixed px (--spacing-2: 8px), so useTheme().token(), resolveThemeToken(), tokenDefaults and spacingDefaults returned px strings, and spacing stayed the same size when a reader raised the browser font size.
    Replacement: The defaults are rem with the same value at a 16px root (--spacing-2: 0.5rem, --spacing-4: 1rem), and those readers return the rem string.
    Migration: CSS that reads var(--spacing-*) needs no change. Code that parses a spacing token as a px number converts the rem value with the root font size, or reads the element's computed length. A theme that wants fixed px spacing sets the tokens back, for example defineTheme({tokens: {'--spacing-2': '8px'}}).
    Codemod: None. A token read and parsed at runtime cannot be found and rewritten statically, and CSS uses need no rewrite.
  • theme build exits 1 when it reports private --_* variables. (#6872) The old contract reported private-variable errors but exited 0. The corrected contract keeps the same warnings, receipts, generated files, and --check output, but exits 1.
    To migrate, a CI step that relied on exit 0 must fix the theme's private --_* inputs.
New Features
  • astryx upgrade adds padding={0} to BottomSheet elements that do not set padding, keeping their unpadded content box now that BottomSheet pads like Dialog. Sheets whose only child is a Section or a Layout are left unchanged. A sheet with a Layout anywhere in its content also gets a TODO comment, because padding={0} removes the inset between that Layout's regions and the Layout's own padding restores only its outer edges. A shadowed BottomSheet binding is left alone, and a second run changes nothing. (#6884)
  • astryx upgrade runs migrate-field-input-styling, which renames root xstyle/className/style on Field-composed inputs to the part they styled before: controlXstyle/controlClassName/controlStyle on TextInput, TextArea, NumberInput, FileInput, DateInput, DateRangeInput, DateTimeInput, TimeInput, Selector, MultiSelector, and ComplexSelector, and containerXstyle/containerClassName/containerStyle on Typeahead, Tokenizer, CheckboxList, RadioList, and Slider. It rewrites JSX written directly on an Astryx import (named, aliased, or namespace). Spreads and wrappers that forward their own styling props are left for manual migration, and a callsite that already sets the target prop gets a TODO instead of a rename. (#7342)
  • astryx upgrade renames emptySearchResultsText to emptySearchText on Tokenizer, Typeahead, BaseTypeahead, and ChatComposerInput trigger objects, for the release that removes the old name. (#7289)
Fixes
  • template and build follow the project's package manager. The nearest directory from the target up to the workspace root that has a packageManager field or a lockfile decides. With neither, the command uses npm, whatever package manager launched the CLI. When that directory's lockfiles disagree and nothing it commits picks one, installCommand is null and the note names the missing packages, the directory, and the lockfiles that disagree, instead of guessing a command that would write a second lockfile. (#7343)
  • Teach generated palette references in the full custom-theme authoring guide. (#7268)
  • Generate Neutral's runtime palette references from the stops its theme uses, and fail verification when the package or CLI template copy drifts. (#7255)
Documentation
  • Clarify release-branch codemod promotion and version ownership. (#7293)
Contributors
Thanks to everyone who contributed to this release:

0.6.8

Fixes
  • A template that sets replaces needs @astryxdesign/cli 0.6.4, and one that sets keywords needs 0.6.6, not 0.7.0 (#7265). Published 0.6.4 applies a template's replaces, and published 0.6.6 reads its keywords. integration verify asked for ">=0.7.0" for both, a range no released CLI satisfies, and npm leaves the CLI uninstalled in an app that installs a package with that optional peer. integration verify now accepts ">=0.6.4" for replaces and ">=0.6.6" for keywords, and still refuses a range that admits an older CLI. Its messages now say what older CLIs do. Before 0.6.6 a template that sets keywords is dropped, and before 0.6.4 the package's doc topics are hidden too.
Documentation
  • Guide new theme authors to the palette generator and keep the broad color scale opt-in in generated theme templates (#6795).
Contributors
Thanks to everyone who contributed to this release:

0.6.7

New Features
  • Apps can opt into package-managed themes with astryx theme add <slug> --import. The command records the theme in one generated app module with its production CSS, optional font CSS, and default slug. Use theme remove and theme use to manage that record, and pass themes[defaultThemeSlug] to <Theme>. Plain astryx theme add keeps its released source-copy behavior, options, stdout, exit status, and every theme.add data field. It now warns that theme eject is the explicit source-fork command and theme add --import is the way to use the package-managed theme. Its machine result adds the DEP-0005 deprecation entry; the cleanup is CLN-0005 in a later scheduled minor.
    Use defineTheme({extends: importedTheme, ...}) for ordinary customization. theme eject creates an independent local fork with its descriptor. JSON callers receive theme.app from import, remove, and use, or theme.eject from eject.
    Existing bundled source copies stay where they are and keep their bytes. Run astryx upgrade --from 0.6.4 --path . --apply to add the missing unmaintained descriptor beside each bundled copy in src/themes. Until then, theme commands skip those copies and theme list and doctor name them as unmigrated. Package integration themes keep their released complete-directory copy, including the authoring descriptor.
    ASTRYX_THEME is no longer read. In a project with a generated app theme module, component metadata reads that record's default built theme. Without the module, the released package.json#astryx.theme lookup keeps its meaning. Doctor loads every recorded built module through the same theme adapter, so a broken runtime import fails theme-owners instead of passing.
    theme build also writes <out>.css.d.ts so TypeScript accepts generated CSS imports. Check mode stays compatible with released output sets that do not have this new stub yet.
    Integration themes can export built modules and stylesheets. astryx integration add theme creates those exports, and integration verify checks the exported paths against the packed package and source. Missing partner exports alone do not block packing. Every declared export must resolve; staleness is a warning for an incomplete set and an error for the complete importable module and stylesheet pair.
  • Every result now names the package it comes from. A --json result about one artifact (a component and each of its projections, a doc topic, index, section, or docs-tree node, a template, a hook, and swizzle) carries package in its envelope, directly after type. A result that lists artifacts gives each item its own package: every search hit, build's start, alternatives, blocks, and components, a doc's sections, a docs-tree node's children, --blocks entries, and the component --list and upgrade --list entries. Text names the same package; --source, --showcase, and a template's source still print only the source on stdout and name the package on stderr. Existing fields are unchanged.
  • Deprecate the astryx layout command group The astryx layout command group (expand, check, grammar) is deprecated. Use astryx build to choose the template to start from, astryx template to scaffold it, and astryx docs layout for layout guidance.
    In human mode each invocation prints a stderr warning naming the replacement. In JSON mode the response envelope carries machine-readable deprecation metadata in its meta field. Canonical stdout, exit codes, and the layout.expand / layout.check / layout.grammar response schemas are unchanged.
    Deprecation lifecycle (spec:AST-017 FR28, FR31) — removal only in a later minor whose frozen manifest carries both ids of a pair:
  • An integration component can replace a Core component, once its package opts in An @acme/nav component whose doc sets replaces: 'SideNav' takes over SideNav for unqualified component detail, batch selectors, every component --list detail level, search, swizzle, and gap-report routing, when @acme/nav declares "@astryxdesign/cli": ">=0.6.7" in peerDependencies (optional in peerDependenciesMeta). Every result names its package, --package @astryxdesign/core still selects the original Core component, and the replacement keeps answering to its own name. component SideNav --package @acme/nav also selects it.
    Any @astryxdesign/cli range that starts at 0.6.7 or later is the opt-in, including the >=0.7.0 that integration add doc --parent wrote in 0.6.4 and 0.6.5, and integration add theme in 0.6.5. A package whose range admits an earlier CLI keeps its component under its own name and Core stays selected, and an app that loads it sees no new output; its author gets warnings naming the range to add, from astryx doctor integration components and integration verify. For a package that declares the range, astryx doctor integration components reports a missing Core target, an invalid value, a component named after a different Core component, or two replacements for one target in the package as errors and exits 1. When several packages replace one target, an explicitly configured package beats an autolinked one, the later configured package wins, and Doctor warns.
  • Add the model comparison page template with responsive sticky context and accessible interactions. (#6251)
  • New table-collapsible page template: several tables on one page, each in a collapsible card with its own columns, for groups that do not share a schema. Every table sorts on its own, one time range in the page header drives all of them, and rows expand in place into a full-width history chart. Below 720px each table folds to its name and headline figure. (#6065)
Fixes
  • Printed commands name the scoped @astryxdesign/cli package whenever the astryx bin is not installed for the project
  • Compact the generated agent-docs block: fewer lines, same behavioral coverage
  • astryx doctor keeps its themes check, with the same id, label and fields, beside the new theme checks, so scripts that read it by id keep working. Without a generated theme module it reports what it did before: whether an @astryxdesign/theme-* package is installed, and whether the app's package.json names a theme in astryx.theme. Its fix now names theme add --import. With a generated module it reports the overall result of the theme checks. In a workspace, themes reads the app's own package.json, the file the CLI reads when it resolves the theme, rather than the package.json beside the root node_modules. It no longer counts the ASTRYX_THEME variable, which the CLI does not read, as a wired theme.
  • Doctor says why it skipped a check and what it checked, and doctor integration validate no longer crashes on a folder it cannot read
  • upgrade: exclude node_modules from integration codemod discovery When an integration declared its codemods root as the package root (codemods: "./"), the version-folder scan treated node_modules, .git, __tests__, and __fixtures__ as version folders and loaded their files as codemods. The same SKIP_DIRS filter that the recursive file walk already used is now also applied to the top-level version-folder enumeration.
  • Align the layout deprecation (DEP-0006) with the documented envelope and precedent The layout command's JSON envelope now emits meta.deprecations: [{id, replacements}], matching the response schema doc and the DEP-0005 theme add precedent. The deprecated CommandDoc field renders in --help and the manifest. The programmatic API exports (layoutExpand, layoutCheck, layoutGrammar) carry @deprecated in their declarations and generated types. Command and function reference pages name DEP-0006 and the replacement. The DEP-0006 record names its direct authority. All released data fields are unchanged.
  • swizzle: rewrite every .stylex import to a deep path astryx swizzle Button (and any component that imports a .stylex module from outside its own directory) emitted an import that collapsed to the directory barrel — e.g. @astryxdesign/core/utils instead of @astryxdesign/core/utils/interactionOverlay.stylex. The barrel does not re-export those StyleX symbols, so the swizzled file could not compile.
    rewriteImports now gives every *.stylex module the deep subpath. The exports generator (scripts/sync-exports.js) adds 16 specific subpath exports for the .stylex modules swizzled components actually reference across directories:
    DateInput/tokens.stylex, Icon/IconSize.stylex, Indicator/indicator.markers.stylex, Layer/layerAnimations.stylex, Layer/layerTextReset.stylex, Layer/layerViewportInset.stylex, Layout/container.stylex, Layout/edgeCompensation.stylex, Layout/padding.stylex, NavItem/navItemStyles.stylex, Selector/selectorPresentation.stylex, Stack/stack.stylex, Stack/stackItem.stylex, Text/text.stylex, utils/focusOutline.stylex, utils/interactionOverlay.stylex
    These are public API additions. Each module already ships in the npm tarball (in dist/); only the exports map entry is new. No wildcard — a future cross-directory .stylex import needs a deliberate entry in STATIC_EXPORTS. Precedent: ./theme/dataTokens.stylex (AST-066 FR2).
  • template: show a grouped summary by default instead of the full catalog Bare astryx template (no name, no --list) now shows templates grouped by category with counts — about 21 KB instead of the full 149 KB catalog. The full catalog with descriptions is still reachable via astryx template --list.
    JSON output is unchanged — --json template still returns the complete template.list response. This is a text-only rendering change under AST-017 FR11: the machine-readable response schema is the contract; text formatting is not.
    Trade-off: the grouped output still includes every template id (so template <id> works from a copy-paste), at the cost of ~21 KB. An even shorter summary (type + count only, no ids) would be ~500 bytes but would require a second step to discover any id. The current shape serves both human scanning and agent copy-paste without a round-trip.
  • template: bare template --type no longer prints an empty group header
  • A section read on a docs-tree namespace answers from the guide that has the section again, so astryx docs layout side-panels and the other layout section reads released in 0.6.6 work after the layout split. docs(route, section) returns the same docs.detail.section the guide's own section read returns, found by key, then by title, in --dense and --zh too. When no guide or more than one has the section, the read fails with ERR_UNKNOWN_SECTION and names the guides to read it from.
  • astryx search ranks a component, hook, or template that a query word names above a doc that matched only by keyword, heading, or text. font size finds Text first again instead of a typography guide. A doc the query names, such as font setup or migration, or one whose title the query holds, such as resizable side panels, keeps its place. Result scores do not change; only the order between domains moves.
  • astryx search finds a guide when the query is its route or title in the other number: side panel finds the side panels guide first again, and header and footer finds headers and footers. A section's heading still doesn't count as its topic's name, so font size keeps finding Text first.
  • Fix comparison table category from "Table - Frozen Column" to "Table - Comparison" The category described an implementation detail (the frozen label column) instead of what the template is for. Builders searching by layout type now find it under Comparison.
  • Template and build tell you what a scaffolded template needs that your project lacks. When astryx template <name> <path> scaffolds a file that imports packages your project does not have (e.g. @heroicons/react, recharts, lucide-react), the receipt now includes a ready-to-run install command with the project's package manager and version ranges from the CLI workspace. astryx build shows the same note on its start template.
    When a scaffolded template uses StyleX and the project has no compiler plugin configured, the receipt warns and points to astryx docs styling-overview. The agent-docs block no longer says "don't use xstyle" flat-out — it acknowledges that some templates need it and links the setup doc.
    detectStylingSystem now recognizes the official @stylexjs/rollup-plugin, @stylexjs/webpack-plugin, and @stylexjs/nextjs-plugin alongside the existing entries.
  • astryx theme build prints one line per built theme, plus one line naming fonts the themes do not load. Before, every theme printed the same install example and font recipe, so a build of many themes printed the same blocks again and again. --detail full prints the install example and font recipe, once for a batch instead of once per theme; for one theme it prints what the default printed before. Only the text report changes: --json output, --check, exit codes and written files are unchanged.
  • Wherever the CLI shows the <Theme> wrapper, it now also shows where Theme comes from: import {Theme} from '@astryxdesign/core'. This covers the astryx init next steps, theme add and theme build output, the doctor fix for an unimported theme module, build help, and the theme guides.
  • astryx theme add <slug> --import names the npm package that owns the added theme, in its JSON envelope (package, directly after type) and in its text output, the same way other results about one artifact do. A local theme has no package, so its result has no package, and theme remove and theme use are unchanged. astryx theme add --list keeps its JSON. Its text now names theme add <slug> --import to use a theme and theme eject <slug> to fork one, instead of the deprecated copy form.
    astryx doctor adds a theme-management check, and focused theme-* checks once a project has a generated theme module.
  • One-off commands in a classic Yarn (1.x) project use npx @astryxdesign/cli … instead of yarn dlx, which classic Yarn does not have
Documentation
  • astryx docs migration, internationalization, styling, styling-libraries, typography and tokens still work and now list focused guides. Each section is also readable under its guide, for example astryx docs tokens/tokens-spacing or astryx docs styling/tokens-and-setup stylex-setup, and astryx docs <topic> <section> keeps working: every section key these topics had still opens the same section. astryx docs tokens --depth all --detail full prints every token table, and a token-ref to tokens keeps resolving through the guide that holds the table. Integrations: these six names are now docs-tree sections, not topics, so an integration doc that declares extends or replaces with one of them is reported as naming no topic, and its content no longer shows. To keep that content, ship it as your own topic under a new name, or as a guide in your package's own section (astryx integration add doc <name> --parent <your-section>). Topics that are still flat, such as theme or color, can still be extended or replaced.
  • astryx docs layout still works and now lists the focused guides. Each section is also readable under its guide, for example astryx docs layout/side-panels or astryx docs layout/scaffold shell, and astryx docs layout <section> keeps working. (#7125)
  • astryx docs layout opens with its overview again, and astryx docs author-a-theme and use-a-theme restore guidance the theme split dropped: what a bad extends base does, how adaptation rules are validated, what __built means, the icon-registry specifier traps, registerTheme, and wiring built themes in development too. (#7204)
  • Add a choose-a-path styling overview and restore the import-based workflow across the theme guides. (#7134)
  • Split the theme documentation into focused guides for using and authoring themes, with a concise overview that points to both workflows. (#7141)
Other Changes
  • A hint uses npx astryx … (or pnpm exec, yarn, bunx) only when the astryx bin is in node_modules/.bin, in the project or a folder above it. Otherwise it prints npx @astryxdesign/cli … (pnpm dlx, yarn dlx, bunx), as it already did when the CLI ran from an npx or dlx cache.
  • A global install, or a workspace install used in a fresh package, used to print npx astryx …. The npm package named astryx is not this CLI, so following that hint fetched an unrelated package.
  • astryx blog follows the same rule, and the incident console template names the scoped package.
    Classification: contract-restoring. JSON shapes are unchanged; only hint text changes, and projects with the CLI installed keep npx astryx ….
  • deprecation DEP-0006 / cleanup CLN-0006 — astryx layout command group (expand, check, grammar)
  • A check that needs the loaded project quotes the reason the CLI could not load it, instead of only "Skipped".
  • The config check warns when astryx.config imports but the CLI cannot load the project from it. Before, it said the config loaded cleanly.
  • Integration contributions name the integrations they checked; with none loaded, the check reports info and says there is nothing to check.
  • The agent-docs check reads every file init can write (Hermes included) and looks in the project root as well as the working directory, so running doctor from a subfolder no longer reports that there are no agent docs.
  • astryx doctor integration validate names a folder it cannot read and keeps checking. A declared root that is a file or that cannot be read is reported as invalid_root or unreadable_root instead of a raw error or a crash.
    Classification: contract-restoring. No check becomes stricter: every new finding is a warning or info, and the only exit-code change is that an unreadable folder outside every root no longer crashes validation.
  • Whenever the CLI prints its scoped one-off form (it ran from an npx or dlx cache, or the astryx bin is not installed for the project), a Yarn project got yarn dlx @astryxdesign/cli …. On classic Yarn that command fails.
  • Classic Yarn is read from the declared packageManager version, the yarn.lock header (# yarn lockfile v1), a committed .yarnrc (without .yarnrc.yml), or the runner. Yarn 2 and later keep yarn dlx.
    Classification: contract-restoring. JSON shapes are unchanged; only hint text changes.
Contributors
Thanks to everyone who contributed to this release:

0.6.6

New Features
  • Add a shared upload icon, and use it for FileInput's upload affordance instead of the directional arrowUp Themes draw upload through icons.upload, separately from arrowUp, so sort arrows and every other arrowUp use stay unchanged. Every bundled theme and theme template draws upload in its own icon style. FileInput keeps its icon size, placement, color, and accessibility in both modes; a theme with no upload artwork shows the default upload-into-tray glyph there.
    A complete IconRegistry may still omit upload in this release. The next minor makes it required, so add an upload entry to any registry you type as IconRegistry.
  • Templates declare their keywords, and build tells a part of a page from a page by the components the project can use (#6805)
  • build chooses where to start with a checked-in table of word weights blended with the page ranker
  • astryx docs <route> --depth <levels> reads as far down the docs tree as you ask, from one doc to everything below it. --depth 0 reads only the namespace you name, --depth 1 adds the docs right below it (what a read without --depth shows), and --depth all goes to the bottom. With --depth, --detail sets how much of each doc below shows: brief (the default) is one line each, named by where it sits so you can open it, compact adds its sections, and full prints it whole. So astryx docs cli --depth all is a map of every CLI doc, and astryx docs cli/integrations --depth all --detail full prints the integration guides as one read. Where a read stops, a namespace says how many docs sit below it. --json returns the same tree as docs.node: each child carries its own slots while the read goes deeper, childCount where it stops, and its text at compact or full. docs() takes the same depth and detail options. Reads without --depth are unchanged.
  • Point at discover where people look for things to add Nothing an agent reads named discover, so agents asked to find a theme searched the package registry instead. The agent block astryx init writes now lists discover <words> (integrations you could add, and the ones you have), theme list ends with More themes in packages you could add: astryx discover theme, and a text search ends with More in packages you could add: astryx discover <query> (except --type hook, since no integration adds hooks). JSON output is unchanged.
  • integration add theme --from <base> forks an existing theme as the starting point instead of a blank scaffold. The new theme copies the base's source files — renamed and rewritten for the new slug — with no link back. Use --from when you want to change a lot; for a small change that stays linked, use extends in defineTheme.
Fixes
  • Say when a command did nothing: upgrade reports sourcePathFound, the integration checks report validated. Two commands could legitimately do nothing and produce an envelope identical to a clean success. Both now carry the fact in a field of their own response instead of only in human text.
    astryx upgrade defaults --path to ./src. A project laid out as app/ (or a typo) skipped every code codemod and still reported exit 0, filesChanged: 0, errors: [] and "Upgrade complete". The only warning was a log line --json suppresses by design. upgrade.run now carries sourcePathFound, and the human completion line names the directory it did not find.
    astryx doctor integration validate|components|docs|templates returned {name: null, version: null, issues: []} and exit 0 when no integration manifest was found — the same shape as a validated, healthy integration. All four envelopes now carry validated, false only when nothing was inspected.
  • astryx manifest --json now takes each command's examples from its CommandDoc and its response types from the API function it wraps, so no example differs from the documented one and upgrade lists upgrade.registry, which upgrade --registry --json already emits.
  • astryx template <name> <path> and astryx layout expand now say when they replaced Astryx demo media. The template.copy and layout.expand receipts carry demoMediaReplaced, the number of demo image and video references that became placeholders (one per reference, however many fixture paths its URL carries), and the text output names the file to update (when layout expand prints the code instead, the same line follows it as a comment, so the output is still valid TSX). Nothing about the copy itself changed.
  • astryx template <name> and template() now return the same source that astryx template <name> <path> writes, and say how many Astryx demo media references they replaced. Demo images and videos that only Astryx's own previews serve are replaced the same way in both, so code copied from the printed source no longer points at media your project doesn't have. template.show gains demoMediaReplaced (0 when the template carried none); in text mode the count is stated on stderr so the printed source stays exact.
  • A write that fails reports ERR_WRITE_FAILED instead of a raw Node errno. astryx template into an unwritable directory returned {"error": "EACCES: permission denied, open '/home/you/project/readonly/x.tsx'", "code": "ERR_UNKNOWN"}, and swizzle returned the mkdir equivalent. Two things were wrong: ERR_WRITE_FAILED is already in the frozen error registry for exactly this case, and the message carried an absolute host path where every other Astryx message names its target relative to the project.
    Both now throw ERR_WRITE_FAILED with the errno kept (it is the part that says what to fix) and the target named relative to the project. Nothing is left half-written: a swizzle that fails part-way removes the files it already copied and puts back any it replaced before it reports the error, and the message names any file it could not restore.
  • When discover --available runs without a discover source, the CLI now explains what discover sources are and where to find Astryx packages on npm, instead of the misleading message that told users to add package names they had no way to find. The base discover with no integrations also gains a pointer to npm and the integrations docs.
  • A package with a namespace doc or a placed guide needs @astryxdesign/cli 0.6.4, not 0.7.0. Published 0.6.4 reads an integration's docs tree: it lists the namespace and reads each guide placed in it. 0.6.3 rejects a namespace doc and hides every doc topic the package ships. integration add doc --parent wrote "@astryxdesign/cli": ">=0.7.0", a range no released CLI satisfies, and integration verify failed a docs-tree package whose CLI peer started at 0.6.4. integration add doc --parent now writes ">=0.6.4", marked optional, and integration verify accepts it. A template that sets replaces or keywords still needs ">=0.7.0".
  • gap-report fails when a listed integration cannot load, instead of reporting a clean result. An integration whose astryx.integration module throws on import or fails validation was left out of the handler set. With no other handler, the report fell through to the built-in GitHub fallback for Core: the command exited 0 with consent_required, printed nothing on stderr, and offered --confirm-public to file on Core's public tracker a report the integration might have been meant to receive.
    The unloadable integration now records a failed delivery in its config position, with the load error and the fix in its message. Like any handler, it turns the fallback off, so the report never goes to another package's tracker. The command exits 1, and a failed or partial report now prints each failed delivery on stderr as well as in the receipt.
  • astryx integration add theme <name> --from <base> now adds the packages the copied theme files import to dependencies. A fork of a bundled theme such as neutral copies its icons.tsx, which imports lucide-react, but the package did not declare it. So astryx theme build on the fork failed with "Cannot find module 'lucide-react'", and an app that installed the package hit the same error. --from now adds each package the copied files import, at the range the bundled themes use. It leaves out Core and React, which every Astryx app already has, and anything the package already declares.
  • astryx integration pack without --check now points only at astryx integration verify. It used to say "Pass --check to verify the integration tarball, or run astryx integration verify", which sent people to the deprecated spelling. It now says that integration pack is now integration verify, and that npm pack builds the tarball. The error code and exit code are unchanged, and integration pack --check still runs the same check as before.
  • Search: differentiate all-word matches by total quality; index themes Within the all-words tier, every candidate whose strongest token hit was a keyword scored the same (e.g. 157), regardless of how the other query words matched. A doc matching both words by keyword outranked nothing, and search "how to use a theme" put API reference docs above the consumer theme guide.
    The bonus now uses the sum of ALL token scores instead of just the strongest, so a candidate matching every word by keyword outranks one matching keyword + prose. The theme doc also gains consumer-facing keywords so it surfaces for questions like "how to use a theme" and "how to apply a theme".
    Themes are now a search domain: bundled and integration-provided themes appear in results with their slug, displayName, package, and the astryx theme add command. --type theme filters to them. Like --type doc, it works outside an app, where an open search now covers the docs and themes. Search help, the manifest, and the API reference list the new domain and its result fields.
  • Search ranks a theme's description as prose, not as keywords A word a theme shares with your query only through its description, such as minimal, focus or content, now ranks the theme like any other description instead of like a declared keyword, so it no longer lands above the components, hooks and docs that declare that word. A theme still comes first for its own slug or display name: astryx search neutral finds the Neutral theme first.
  • A package that ships a theme or a doc section id needs @astryxdesign/cli 0.6.4, not 0.7.0. Published 0.6.4 reads typed theme descriptors and section ids; 0.6.3 rejects both and hides the package's themes or doc topics. The 0.6.5 notes said a stable CLI before 0.7.0 rejects them, so integration add theme wrote "@astryxdesign/cli": ">=0.7.0", a range no released CLI satisfies, and integration verify failed a theme or section-id package whose CLI peer started at 0.6.4. integration add theme now writes ">=0.6.4", marked optional, and integration verify accepts it for themes and section ids. A template that sets replaces or keywords still needs ">=0.7.0".
  • theme build resolves real icon imports from the selected theme instead of matching comment or string contents. Generated modules preserve named, aliased, default, and namespace registry imports, plus inherited icons with child overrides. Normal builds and --check reject unsupported inline registries with ERR_THEME_INVALID before generating or writing output. Move such a registry into its own module and import it into the theme file.
  • astryx theme build in an app uses the app's installed @astryxdesign/core, and says to install Core when there is none. Run one-off with npx @astryxdesign/cli, it failed with "Build @astryxdesign/core first (e.g. pnpm -F @astryxdesign/core build)" even when the app had Core installed, because it looked for Core only next to the CLI. It now generates with the Core the project installed, the same Core the app's <Theme> runs on. In an app without Core, the error now says to install it (npm install @astryxdesign/core). The build command stays only for the Astryx repository itself. The error code (ERR_CORE_NOT_FOUND) is unchanged.
Other Changes
  • TemplateDoc gains an optional keywords list: the ideas, domains, and other names a builder might use for what the template serves. parseTemplate validates it, discovery carries it from every template source, astryx search matches it as it matches a template's description, and astryx build ranks page templates on it. Each Core page template's closing list of ideas moved out of its description into keywords, so descriptions describe the layout.
  • build starts a part of a page where it lives (spec:AST-048 FR3), and the project's own components say what a part is: an idea whose head noun is a word of a component's name or keywords, Core's or an integration's, asks for a part, unless the noun names a family of page templates or the idea lists three or more pieces. A part starts from the base template of the family the idea names, else from the app shell; a change to an existing page or part (an idea whose "existing" names a page family or a component, such as "the existing table", and that does not ask for a new page) starts from the app shell. The start's reason says which case applies and why.
  • A family's base template leads its family unless a variant matches two terms of its own; a base that cannot start on its own never displaces the variant that leads.
    Integration templates that set keywords need @astryxdesign/cli 0.7.0 or later. The template metadata object is strict, so a stable CLI before 0.7.0 rejects the field, drops that template, and hides the package's doc topics; only template --list and search print a warning. integration verify fails a package whose template sets keywords until it declares @astryxdesign/cli >=0.7.0, as it does for replaces.
  • api/build/kit/weights.mjs scores each candidate start (the app shell and every ready page template) from the idea's stemmed words using the tables in weights.json, and blends those scores with the ranker's own. The blend decides the start of every whole page; a part or an edit starts where it did before, and the ranker's pick of a template the tables do not list stands. Without a weights file the ranker's pick stands. The response's shape is unchanged.
Contributors
Thanks to everyone who contributed to this release: