What's New

Release notes and changelog for all packages.

0.6.0

Breaking Changes
  • Add ordered environmental adaptations to defineTheme Themes can now opt into CSS-first token, theme-local token, and component changes for named viewport widths, primary-pointer precision, contrast preference, and motion preference:
    ts
    defineTheme({
    name: 'acme',
    adaptations: {
    widthBreakpoints: {sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536},
    rules: [
    {
    when: {width: {from: 'lg', below: 'xl'}, pointer: 'coarse'},
    value: {tokens: {'--size-element-md': '44px'}},
    },
    ],
    },
    });
    Condition fields are ANDed. width.from is inclusive, width.below is exclusive, and rules cascade in declaration order so later matching writes win. Theme extension preserves the effective breakpoint map and inherited rule order; static builds retain the metadata needed for source-equivalent extension.
    AppShell now accepts xl and 2xl for mobileNav.breakpoint and resolves all five names through the nearest Theme. Mobile mode now uses the documented exclusive boundary (width < breakpoint), so an AppShell exactly at the named point renders the wider layout instead of the mobile layout.
    defineTheme now validates the token values authored inside an adaptation rule, rejecting non-string scalars and arrays with a length other than two instead of emitting them. Root and on-media token input keeps its existing acceptance unchanged, so themes that pass values through casts or spreads keep building. It also validates the combined portable and theme-local token graph for every reachable set of matching adaptation rules, rejecting cycles before CSS is emitted. Component writes in a rule use the same target, axis, value-domain, and extension validation as root components; a rule may not be the only place a custom value is enrolled, because generated type augmentation is unconditional.
    astryx theme build treats the adaptation generator as a core capability rather than a baseline requirement, so a theme with no adaptation intent still builds against an older installed @astryxdesign/core and emits the same CSS as before. A theme that does carry adaptation intent — valid rules, a custom widthBreakpoints map, or present-but-malformed adaptation metadata — fails against such a core before any output is written, with ERR_CORE_INCOMPATIBLE naming the missing generateAdaptationCSS export. A complete default width map with no rules asks for nothing and still builds. Where an older core's defineTheme drops adaptations while resolving, the build records each raw defineTheme() input and associates it with the theme it produced, so only the selected theme's lineage decides. An unobservable selected ancestor (including a CommonJS source package whose ESM core namespace cannot be wrapped) fails closed; an unused adaptive theme elsewhere in the import graph does not affect a plain build. The same capture preserves raw typography, color, radius, and motion axis metadata in old-core-built artifacts, allowing later current-core children to resolve partial adaptation axes exactly as if they extended the source theme.
New Features
  • Let integration manifests add managed agent guidance
  • Add an authoring-time OKLCH palette generator with a pure API, terminal and HTML previews, typed palette output, custom stops, deterministic receipts, and overwrite protection. [feat] Expose exact solid black and white values as neutralPalettes.black and neutralPalettes.white for use in semantic theme tokens.
  • Every command now reports what it returned in its debug logs, and a new command cannot skip it. A command's action returns a CommandResult — either {kind: 'results', count, resultKind, ...} or {kind: 'none'} for the commands whose work is an effect (build, init, upgrade, doctor). The CommandDoc converter records it centrally, so resultCount, emptyResult, resultKind, and directMatch are now populated for component, docs, hook, template, theme list/add/targets, discover, blog, swizzle --list, upgrade --list, layout grammar, and manifest, not just search and build. resultKind gains theme, integration, migration, command, and none; a null now means the run never reached an answer rather than "this command has nothing to say". That is a change of meaning on an existing field, so recorded runs are now schemaVersion: 3 — a consumer that counted nulls as "commands with nothing to report" should branch on the version before mixing old rows with new ones.
  • Add doctor integration checks for structural validation and Core template, component, and doc overlaps (#6173).
  • Add an experimental shadcn Registry compatibility guide and doc-derived registry identity metadata. It explains the package boundary, stable organized paths, copied composition model, upgrade behavior, and when to use the richer Astryx CLI.
  • Add astryx upgrade transforms for the Core 0.6 deprecated-API removals: focus direction overrides, the hooks-path IME helper import, and Resizable pixel-bound aliases.
Fixes
  • Prevented removed Resizable bounds from being silently ignored and kept ambiguous spread migrations behavior-preserving (#6124)
  • Add a conservative astryx upgrade --apply migration for the Core bare selector-class removal. The transform parses .css selector syntax, rewrites exact v0.5.4 target/value pairs to behavior-preserving old-class/data-attribute unions, covers unbounded values that v0.5.4 emitted, and leaves unknown consumer classes unchanged.
  • Preserve @path agent doc imports and remove previously duplicated managed blocks (#6164)
  • Refresh the Collapsible block templates with complete, current examples for single, multiple, controlled, divided, standalone, and grouped usage. The controlled step example keeps one valid step open so its progress label and Previous/Next actions never enter an invalid “Step 0” state.
  • Report the fixture path when a template demo asset has an unsupported format (#6039)
Documentation
  • Align Doctor help and README examples with the shipped command tree and output format (#6197).
  • Clarify how to build themes with imported icon registries, including the current omission of inline registries and the separate registry compilation step. The theme guide distinguishes a missing compiled registry from an extensionless source import: the former breaks both loading and bundling, while the latter can resolve in a bundler when the source remains beside the generated module. English, dense, and Chinese guidance now explains how output paths and --icons-specifier affect resolution.
Contributors
Thanks to everyone who contributed to this release:

0.5.4

New Features
  • Preserve block showcase metadata from CLI integrations so packages can ship their own docsite previews. Charts now includes its primary bar-chart showcase alongside the package.
Contributors
Thanks to everyone who contributed to this release:

0.5.3

New Components
  • Add popover, bottom-sheet, and adaptive presentation options to Selector and MultiSelector, with docsite examples for both bottom-sheet variants. (#5395)
  • Reuse Neutral-owned local tokens for semantic status fills across badges, status dots, step indicators, and progress bars. (#5854)
  • Add Neutral's reproducible, theme-owned OKLCH palette without changing its runtime token mappings. The request, receipt, generated result, and CLI template artifacts are committed together for review. (#5987)
  • Add the opt-in theme-local token contract for maintained theme families. (#5844)
New Features
  • Add structured accessibility requirements and theme coverage support to component documentation. (#5713)
  • Add the checkout wizard page template. (#5660)
  • CLI: record every command run and hand it to a function you supply. (#4812)
    js
    // astryx.config.mjs
    export default {
    debug: event => appendFileSync('runs.ndjson', JSON.stringify(event) + '\n'),
    };
    That is the whole feature. Setting debug opts in; the function receives one DebugEvent per invocation and decides what happens to it. The CLI stores nothing.
    Each event carries the command, its arguments and flags (with their Commander source, so you can tell a typed flag from a default), the outcome, exit code, duration, error code, a coarse environment snapshot including which coding agent invoked the CLI, and — under output — everything the command printed to stdout and stderr. That last part is the answer the user actually got, which is what makes a record useful for improving the output rather than just counting invocations. Streams are captured separately with their true byte counts, and truncated past 32KB per stream so a command that prints a whole file does not dominate the record. Coverage is the point: handled errors, parse errors, --help, rejected invocations, uncaught throws, and Ctrl-C all report. The event is delivered from a process.on('exit') listener because the CLI's error path exits synchronously — anything hooked to normal completion would report successes and almost no failures — and the handler is loaded before parsing, because parse errors and --help short-circuit before any hook runs.
    event is a published contract: DebugEvent is exported from @astryxdesign/cli/debug with a sealed zod validator, parseDebugEvent, drift-locked to the type so the recorder cannot add a field without publishing it. schemaVersion is a literal, so widening it turns every consumer's branch into a compile error rather than a silent misread.
    The handler runs synchronously at exit — a returned promise is never awaited, so network delivery from inside it will not work; write a file or spawn a detached child. It receives a copy, so a handler that throws, or mutates what it was given, can neither fail the command nor affect anything else. Follow-up hardening keeps a handler from replacing the command's exit code and routes handler writes away from stdout so a --json envelope stays valid. (#5929)
    Nothing changes for a project that has not set debug. Startup is unmoved: the environment probe is deferred to delivery rather than run in begin, because its first Intl call initialises ICU and that alone was ~9% of the CLI's startup for everyone. Nor does the config run: Project.load evaluates the config module and loads its integrations, which most commands never did, so the file is read as text first and only loaded when the word debug appears in it. Measured across eight commands, no command evaluates a config that did not already.
    Values are scrubbed before delivery: home paths, absolute paths inside stack frames, email addresses, URL credentials, credential-shaped strings, and the value half of a sensitive assignment wherever it appears — including where an error message, a stack frame and the captured stderr all quote the flag that was rejected. Sensitive names are matched with - and _ stripped, so --api-key, --api_key and --apiKey are one rule; key, pat and pw are matched whole so they do not take --keyboard and --path with them. argv is scrubbed pairwise, so --token hunter2 loses its value the way --token=hunter2 does. Oversized values are clamped.
    Hardened against three adversarial chaos runs and an independent review, each finding mutation-tested before its fix landed: a __proto__ key silently reparenting the record that carried it, one oversized value discarding the whole event, an exit that bypassed cliError being indistinguishable from a classified failure, a signal-terminated run leaving no record at all, a sensitive --flag=value scrubbed in argv but written back out in full through the error message and captured stderr that quote it, absolute paths surviving inside stack frames — where nothing puts whitespace in front of them — and taking the machine's username with them, a graceful Ctrl-C recorded as a failure with an exit code the process never returned, --api-key and --token value reaching a handler intact, and the two startup costs above.
    One change reaches beyond this feature: installJsonShim now shims commands as they join the command tree rather than in a single walk at startup, so a command registered later can no longer silently fall out of the --json contract.
  • CLI: astryx init --json now works. It emits the install receipt as a standard envelope — init.run with the mode, the features that ran, the agent-doc files written, any soft docsError, and the template outcome, or init.remove for --remove-agents. Human output is suppressed so stdout carries only the envelope, and the exit code is unchanged from human mode. (#4812) init was the last side-effecting command still refused by the --json gate. That gate existed to stop a command writing half a project and only then reporting that --json was unsupported; since init() already returned a typed receipt, the fix was to emit it rather than to keep refusing. theme and layout remain off the allowlist, but both are command groups with no output of their own.
  • Add result and agent-session context to DebugEvent (#5971)
  • Add the dialog wizard page template. (#5798)
  • Let themes add typed Heading visual roles with a safe semantic-level fallback when the owning theme styles are unavailable. (#6026)
  • Add the form wizard page template. (#5664)
  • Add the inline wizard page template. (#5797)
  • An integration can now supply a debug handler, so installing it turns on its debug logs with no change to the app. Export debug from astryx.integration.*; the app's own debug still runs, both get every event, and a handler that throws cannot affect the command. Opt out with {"astryx": {"inheritDebug": false}}. (#5998)
  • Mute the low-tone edge of Neutral's dark chromatic palette while preserving its light and neutral ramps. (#6069)
  • Rebuild the table-page template as a searchable, filterable, sortable table pattern with filter-aware totals, row detail, a scrolling document masthead, and guidance organized around narrowing, sorting, and communicating filtered state. (#5865)
  • TabList: add an isFullBleed prop so a tab bar can bleed out to its container's inline content edges instead of requiring hand-written negative-margin CSS (#2622). Like Divider's isFullBleed, it cancels the nearest padded Layout container's --container-padding-inline-* custom properties with negative margins; the inner strip pads back by the amount the bleed exceeds a tab stop's own padding so edge labels remain aligned to the content inset. It is inline-only: TabList owns the inline full bleed, and the container owns the block-end dock. For that, LayoutHeader gains a paddingBlockEnd per-edge override in Section's existing spelling — paddingBlockEnd={0} docks the header's last child on its bottom edge so a tab strip's underline meets hasDivider at any header padding. The detail-page template now uses both props, aligns its ghost panel toggle with the container inset, and no longer carries any hand-written tab-row CSS.
  • Add the vertical wizard page template. (#5672)
  • Add the work-item-detail page template for task, ticket, issue, story, bug, card, and request detail surfaces. It includes responsive main-content and details-rail layouts, editable metadata, subtasks, attachments, comments, activity, and a narrow-viewport details dialog. (#5926)
Fixes
  • build: a page that matched one word of the query is no longer offered as a direct match. A page template's keywords include every component its source renders, so build "actionable warning banner" returned login, contact-form and documentation-design at 95 apiece — an exact keyword hit on "banner" alone, plus the coverage garnish, landing exactly on the direct-match threshold. Three pages that are not warnings, presented as the page to start from. Coverage now gates the pages group rather than garnishing its score. Score alone could not carry the gate, so scoreQuery now reports the coverage it already computed: matchedTerms / queryTerms on every search result, with a whole-phrase hit reporting full coverage. A single strong hit and a broad weak one land on the same score, so a caller cannot tell "one of three concepts" from "three of three" without it.
    Rebased onto current main, which landed integration search (#5259) and the scorer-level false-direct-match fix (#5614) while this was open. Both are main's implementations, untouched here — this branch no longer rewrites gatherComponents, so the two regressions that rewrite caused are gone with it: an integration result reports its own package again, and a broken config no longer turns a Core button search into an empty success.
    The other two pieces this branch used to carry now ship separately, as asked: the guidance-tier indexing in #5937 and the thin-kit hint in #5938.
  • A thin build kit now says what to try instead of looking empty. build "quantum flux capacitor telemetry" returned one incidental component and the always-on frame list, and said nothing else. An agent reading that does not conclude its wording was wrong — it concludes the package has nothing and falls back on its own memory of what Astryx contains, which is the failure build exists to prevent.
    Below three offerable results the kit carries a hint naming the two commands that browse rather than search, and saying plainly that this is keyword matching, not semantic. The threshold counts what SURVIVED the score floors, not what search returned: hasResults is already true for a query that matched things and then filtered them all out, and that is the case most likely to be misread.
    hint is structured — {reason, commands} with bare subcommands — not a sentence with commands baked into it. The API cannot know how a project invokes the CLI, and a hardcoded astryx component --list does not resolve in a pnpm workspace, where every other command in this output renders as pnpm exec astryx. The renderer formats them through formatCliCommand, so they are runnable as printed, and a JSON caller gets the parts rather than prose to re-parse.
    hint is present only when it applies, so a healthy kit is byte-identical to before. The CLI renders it last, as a FEW MATCHES section listed in the legend's section order, so it is the line the reader leaves with.
    Split out of #5320 at review request. Public response doc (build.doc.mjs) and the BuildKitResponse type both updated.
  • The shared CLI blog adapter (blog.list, blog.detail) cleared its 15-second abort timer as soon as fetch returned response headers, leaving the later body read unbounded in time, and buffered the entire response before checking the 5 MB size limit, so the limit didn't actually cap how much was read into memory. (#5286) The abort timer now stays active through body consumption. The body is read as a stream where available, checking decoded size after each chunk and aborting the read as soon as it exceeds the limit, instead of buffering the full response first.
  • CLI: recorded runs no longer carry a raw agent session id, and the environment snapshot is scrubbed like every other value. (#6051) A DebugEvent claimed redacted: true while env had never been through the scrubbing pass, and it stored the raw agentSessionId beside its hash. A session id follows one person across every run they make, and a handler may forward these records anywhere — so the record shipped a stable identifier, and an agent name pasted in from the environment went out verbatim, under a flag that said neither had.
    The contract is now explicit on DebugEventEnv: no identity, attribution only from positive evidence, and free text scrubbed. env.agentSessionId is always null — join runs on env.agentSessionIdHash, which is what the raw value was for. Everything the CLI derives itself (platform, CI provider, locale, the hash) is still recorded verbatim, because a scrubbed snapshot is not worth keeping. redacted is set only on the sealed copy, after every pass has actually run.
    DebugSchemaVersion widens to 1 | 2 and the CLI emits 2, so code that switches on it is forced to handle both rather than silently reading a field that no longer means what it did. parseDebugEvent is version-aware to match: a v1 record may carry the raw id, a v2 record may not and is rejected if it does.
    Not a breaking change: debug and the whole DebugEvent surface are unreleased — they land in this same release — so no published consumer ever saw the raw identifier.
  • A manifest key this CLI does not know no longer discards the whole integration. astryx.integration.* was parsed with a strict schema, so one unrecognized field failed the parse — and an integration whose manifest fails to parse contributes nothing, taking its components, templates and codemods down with it. Since an integration is published once and installed against many CLI versions, a field added by a newer CLI reached every older consumer as total, silent loss of that package (#5119). Unknown fields are now ignored with an unknown_manifest_key warning naming them, and the rest of the manifest still applies; a known field of the wrong type is still an error. (#5311 follow-up)
  • CLI: a stray lockfile no longer overrides the packageManager your project declares. (#6051) One yarn install inside a pnpm project leaves a yarn.lock behind forever. A single lockfile used to outrank the packageManager field, so the CLI answered "yarn" for a project that says pnpm — and printed yarn astryx … in every command it suggested, including the invocation line written into agent docs, where agents copy it. astryx doctor called that setup healthy.
    The declared packageManager field now decides, whatever lockfiles sit beside it. The documented fallbacks are unchanged: with nothing declared, a single lockfile still answers, a committed pnpm-workspace.yaml / .yarnrc.yml / bunfig.toml still breaks a multi-lockfile tie, an unbroken tie still resolves to the neutral npx form with a doctor FAIL, and the runner is still consulted only when the whole walk found nothing.
    astryx doctor now WARNs when a lockfile contradicts the declaration, names the file, and says what to delete — instead of reporting the project as fine.
  • astryx search (and astryx build, which shares its ranking) never surfaced a component whose exact multi-word keyword phrase was searched, if enough other unrelated candidates happened to each contain one of the query's individual words. Searching "table of contents" returned no results for Outline, even though Outline.doc.mjs declares 'table of contents' verbatim as a keyword, because Table-related templates each matched table and contents separately and their combined per-word score outranked Outline's single exact match. A query that exactly matches a candidate's declared keyword (or name) verbatim is now promoted to a top-tier score, so it always outranks a candidate that only coincidentally contains several of the query's individual words. Single-word queries and queries that don't exactly match a keyword are unaffected.
    Follow-ups #6001 and #5994 preserve the coverage counts needed by build ranking while keeping them out of the public search result shape.
  • CLI: search and build now report how many results MATCHED, not how many were returned. (#6051) matchCount on a build.kit envelope, and output.resultCount on a recorded run, were both the length of the list after --limit had cut it. A query matching two hundred things and one matching exactly twenty filed the same number, so nothing downstream could tell a capped answer from a complete one — and a thin kit read as "the package has nothing" when it was really "the cap hid the rest".
    search --json now carries matchCount alongside results, and the text view says Results for "x" (2 of 57) when the list was cut short. The payloads themselves are unchanged: results is still bounded by --limit, and the kit still surfaces at most 3 pages, 5 blocks, and 6 components.
  • Rename five dashboard page template catalog slugs to reusable pattern names, per the naming convention in Contributing Templates: dashboard-data → dashboard-comparison, dashboard-executive-summary → dashboard-scorecard, dashboard-portfolio → dashboard-composition, dashboard-project-status → dashboard-progress, and dashboard-service-monitoring → dashboard-alert-rail. Each old slug named the data or task rather than the reusable pattern, so it under-served neighbouring requests: the composition-over-time shape is not specific to portfolios, and the alert-rail shape is not specific to service monitoring. The old slugs no longer resolve because catalog lookup is exact-match; use the new current-catalog values above. The template command and machine-readable schema are unchanged. (#5927) Two categories move with their slugs: dashboard-comparison takes Dashboard - Comparison (it previously shared Dashboard - Analytics verbatim with the dashboard template, so neither owned the keyword) and dashboard-scorecard takes Dashboard - Scorecard. Both values are added to the TemplateCategory union; the superseded values stay reserved. Domain vocabulary — portfolio, holdings, monitoring, uptime, executive summary — is untouched in each description, which is where retrieval actually reads it from.
    Also fixes a typo in the scorecard template's name field ("Executive Summary Dashoard").
  • Deduplicate parent-owned theming targets in CLI discovery while preserving each child component's direct documentation. (#5767)
  • Preserve anatomy when loading localized component docs directly (#5761) The validated component-doc loader now applies the same full-overlay fallback as the CLI loader, so omitted localized anatomy inherits the canonical structure while explicit localized anatomy still wins.
  • Package-manager detection: don't let a stray lockfile decide (#5301) detectPackageManager checked lockfiles in a fixed order and returned the first hit, so a directory holding more than one lockfile was resolved by array position. yarn.lock is first in that array, which means a single yarn install inside a pnpm project silently switches the CLI's answer to yarn — permanently, because the stray lockfile stays on disk.
    Every command the CLI prints is then wrong, including the invocation line written into the agent-docs block, which agents copy verbatim into their own runs.
    An explicit packageManager declaration is authoritative even when the project also contains one or several lockfiles. Without a declaration, a single lockfile remains decisive. When several lockfiles sit in one directory, the tie is broken only from other evidence the project owns: a committed package-manager config file (pnpm-workspace.yaml, .yarnrc.yml, bunfig.toml). A stray install drops a lockfile; it writes none of those.
    The runner (npm_config_user_agent) deliberately does NOT break that tie. An agent handed the wrong yarn astryx line runs the CLI through yarn, so the runner agrees with the mistake and regenerating agent docs writes the wrong line again — the failure reproduces itself. The same holds for an installed binary invoked from that shell. Both now have regressions that start from the wrong line.
    When nothing project-owned decides it, the CLI does not guess. detectPackageManager returns the neutral npx, which is correct under every package manager, and the new explainPackageManager reports ambiguous with the tied candidates. astryx doctor turns that into a FAIL naming the directory and the fix — add a packageManager field, or delete the lockfile that does not belong. It is the refusal findConfigPath already makes for coexisting config files.
  • LayoutPanel: add playground wrapper and default children for docsite preview (#5919) Prevents the properties-tab preview on the docsite from rendering an empty stage by wrapping LayoutPanel inside a Layout scaffold with representative panel content in start slot.
  • Preserve canonical anatomy in localized component docs (#5753) Localized component docs now inherit canonical anatomy when they omit it, while explicit localized anatomy still takes precedence.
  • Make the table-filter page template usable on narrow and touch surfaces: View options, the detail panel, the saved-view dialogs and the filter overflow adapt to bottom sheets, the filter and saved-view rows hold one line, and column freezing is dropped where there is too little width to scroll the rest. (#5829)
  • Correct Neutral Banner interaction tints so light mode uses translucent light overlays and dark mode uses translucent dark overlays. (#5936)
  • Use palette-backed red interaction overlays for Neutral destructive buttons, solid dark-palette tone-25 backgrounds (tone 20 for gray), and calmer dark-mode text colors. Use a palette-backed muted blue tint for dark info banners while preserving the existing light-mode non-semantic color mappings. (#6049)
  • Give Neutral segmented controls a roomier inset while preserving their outside height. (#5851)
  • Rename built-in syntax theme identifiers. (#5847)
  • Remap Neutral's semantic, syntax, and categorical color tokens to the reviewed theme-owned palette through named stop references. Keep the maintained CLI template synchronized. (#6034)
  • Keep query-coverage metadata internal to build ranking while preserving it for promoted exact-phrase matches. (#5994)
  • search indexes a component's usage guidance, one tier below its description. (#5937) A component's best practices are where the reader's vocabulary lives. Banner describes itself as "a persistent message"; only its guidance says "caution", "problems", "form errors". None of those words found it, because guidance was never read — 97 core components ship guidance, and all of it was invisible to search.
    Measured on the real registry, before and after: caution, problems, sources and attention each now return the component whose guidance defines them, and each returned nothing relevant before.
    Guidance scores 45, below description's 50, so a component that IS the answer still outranks one whose advice merely mentions the term — the ordering that put Toast behind Card, Dialog and Item on "notification".
    It sits deliberately BELOW MIN_TOKEN_SCORE, so it never counts as a matched concept in a multi-word query. That is not a detail: letting it count was measured moving nested menu from SideNav to List, and explain why a field is required from Field to TextInput — a component whose guidance happens to mention the other word displacing the one that is the answer. Breadth is not relevance, the same reason weakKeywords are capped. With the floor left at 50, a 28-query sweep shows zero top-result changes and zero regressions, while the single-word gains above are kept.
  • Table inbox replies now preserve an unsent body only for the same conversation, preventing text from following changed recipients. (#5934)
Documentation
  • The namespaced-icon rationale and the add-a-semantic-icon intro in the icons guide, and the SideNavItem actions prop description, now use a comma and a colon in place of prose em dashes. Meaning unchanged. (#5647)
  • The description prose of 12 page templates now uses parentheses, commas, and colons in place of em dashes. These strings feed the CLI template list and the doc site, so plain punctuation reads better there. Meaning unchanged. (#5679)
Other Changes
  • Core's postinstall no longer hand-mirrors the setup contract. packages/core/scripts/agent-doc-state.mjs is now GENERATED byte-for-byte from the CLI's dependency-free leaf packages/cli/foundation/agent-docs/agent-doc-state.mjs, and pnpm check:setup-contract — wired into check:repo — fails the build when the two differ. (#4162) The previous guard compared two hand-edited constant lists. That caught a new agent-doc path or a new marker, and nothing else: the predicate itself, and the shouldNudge decision matrix duplicated in both postinstall scripts, could still drift and leave layer 1 and layer 2 disagreeing about "is this project set up?" with the test green. shouldNudge and the nudge string move into the contract as well, so all four things — paths, markers, predicate, decision — now have one definition and one place to edit.
    Behavior is unchanged, and verified rather than assumed: the nudge text is byte-identical, legacy <!-- XDS:START --> blocks still count as set up, all six agent-doc locations are still detected, and both scripts still exit 0 on every path including failure. Core loads its copy with a dynamic import, so a packaging mistake degrades to "no nudge" instead of throwing out of module evaluation and failing a consumer's install. check:setup-contract also fails if core stops listing the generated file in files, so it cannot go missing in the first place.
Contributors
Thanks to everyone who contributed to this release:

0.5.2

Fixes
  • Rename the Data Input component category to Form Controls (#5686)
Contributors
Thanks to everyone who contributed to this release:

0.5.1

New Features
  • Component docs can declare structured usage.accessibility requirements, and astryx component renders them as a dedicated Accessibility section in full and compact output. Translated and dense documentation overlays preserve the base accessibility guidance unless they explicitly replace it. (#5646)
  • Icon APIs and themes accept namespaced extension keys, and NumberInput steppers use numberInput:stepperDown without widening the required IconRegistry keys (#5466) <Icon icon>, useIcon, and defineTheme({icons}) accept keys such as numberInput:stepperDown and richtext:bold; misspelled built-in names remain type errors. NumberInput keeps a compact centered Core fallback, while themes can override its steppers independently from the shared chevronDown semantic.
  • Rebuild the settings-dialog page template with searchable navigation, responsive grouped controls, live appearance previews, configurable keyboard shortcuts, and docsite gallery visibility. (#5568)
  • New table-filter page template: a table page built around a filter token list (#5448) Ports the feature set of the internal XDS table page pattern onto Astryx primitives. The filter row is a token list of quick-filter toggles and field controls — Selector, MultiSelector, and a ComplexSelector wrapping a range Slider — that swaps to PowerSearch for anything the tokens can't express. Both modes read and write the same PowerSearchFilter[], so a filter built in either survives the swap. Controls carry field chrome when unset and a pressed fill once they hold a value, so the row reads as one family whether a clause came from a toggle or a selector.
    Around that: saved views that capture the filters and the whole table configuration, a bulk-edit bar that slides in on selection, and a view options popover with four panels — a drag-and-drop column transfer list, density, sticky edges, and grouping — that apply instantly. Clicking a row opens a resizable detail panel. The list pages in by infinite scroll against an IntersectionObserver, with skeleton rows aligned to the table's own column grid standing in for the batch in flight, and empty states for the no-results and no-data paths. The toolbar wraps to a second row under a container query rather than a viewport one, so it responds to the width the detail panel leaves it.
    Uses the Table - Filtering category, already reserved in the TemplateCategory union.
Fixes
  • build/search no longer rank a partially-matched template above one matching every term, no longer index TypeScript generic arguments as rendered components, and no longer treat breadth of rendered components as full-strength relevance. (#5614)
  • Component and hook names resolve case-exactly on macOS and Windows, matching Linux (#5478) findComponentReadme, findComponentSource and findHookDoc probed candidate paths with fs.existsSync, which answers through the filesystem's own case folding. On a case-insensitive filesystem astryx component button resolved to Button instead of reporting an unknown component with suggestions, and findHookDoc(core, 'mediaquery') returned .../hooks/useMediaquery.doc.mjs — a spelling that exists nowhere, and that breaks any consumer reading it on Linux. The probes now verify each path segment against its parent's real directory listing, so these component and hook lookups resolve the same names to the same real paths on every host. The deliberate case-insensitive hook lookup is unchanged; it now returns the file's true casing.
  • The 56 --color-data-* defaults now reach runtime CSS and built themes from the same source, while dashboard template fallbacks match those defaults (#5562, #5566) The defaults live once at :root in @layer astryx-base, so nested themes inherit parent overrides and astryx theme build matches <Theme> while generateThemeCSS keeps its existing return shape.
    Visual change. A chart or template that previously painted nothing or used a mismatched hex fallback now paints the data token's default. Pin an explicit color to preserve a previous fallback.
  • The theme-showcase page no longer clips its own controls. In the store's product cards the quantity field and "Add to cart" button spilled out of both sides of the card; in the checkout card the card number truncated mid-number (1234 1234 12), the country selector ellipsized, and the pay button was left with only a few pixels of slack. (#5539) The product-card row is the more visible of the two. It had no width of its own — the enclosing stack centers rather than stretches its children — so it sized to its contents and, being centered, overflowed the card at both edges once those contents outgrew it. That stayed hidden while the quantity field was narrow, and surfaced when NumberInput moved to type="text" for formatted display: a text input's default size=20 made the field ~200px instead of ~65px, and the template was pinning it with a style minWidth (a floor, not a cap) plus flexShrink: 0. The field now uses NumberInput's width prop, which is what actually sizes a field, and the row is pinned to the card width and allowed to wrap so the button drops to its own full-width line instead of ellipsizing on a narrow card.
    The checkout sat in a grid track with a 200px minimum, so its width was a fraction of however many tracks happened to fit — it swung between 208px and 328px as the viewport resized, and the narrow end is well under what the form needs. Themes with a large spacing scale suffered most: Matcha's --spacing-5 card padding alone spends 60px of that budget.
    The checkout and chat panels are now a wrapping flex row. They share a row at roughly 1:2 while both flex bases fit, then the chat drops to its own full-width row, which makes 300px a floor for the checkout rather than an accident of the track count. Raising the track minimum instead would have left a tall gap beside the checkout at mid widths, since a two-track row can't hold a two-track span.
    Two narrower fixes ride along, both text the card was breaking rather than fitting: the payment-method grid's minimum goes 70px to 80px so "Google" stops breaking mid-word on Matcha and Y2K, and on phones the card drops one padding step and sheds the card number's decorative start icon, which together buy back the room a 16-digit number needs at 360px.
Documentation
  • useAnnounce, useTypeahead, useInteractiveRole, useLongPress, useInputStatusIcon, useDevWarning and useIndicatorFocusRing are now discoverable. The CLI's hook index is built from the .doc.mjs files next to each hook, and these seven shipped without one; so astryx hook <name> answered "No hook named", astryx hook omitted them and astryx search never returned them, while the package exported them with full TSDoc. Agents following the documented discovery workflow concluded the primitives did not exist and hand-rolled replacements; for useAnnounce that means a hand-built aria-live region, which usually does not announce at all. A test now fails when a hook is exported from the barrel without a doc, so the index cannot silently go stale again. (#5109)
  • rewrite all 46 page template descriptions to describe layout, container, data shape and behaviour — the things that actually differentiate one template from its siblings — instead of the sample data they happen to ship with, so build and search retrieve them from a description of the problem rather than a guess at the slug. (#5615)
Contributors
Thanks to everyone who contributed to this release: