What's New
Release notes and changelog for all packages.0.6.0
Breaking Changes
- Add ordered environmental adaptations to
defineThemeThemes 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:tsdefineTheme({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.fromis inclusive,width.belowis 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.AppShellnow acceptsxland2xlformobileNav.breakpointand 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.defineThemenow 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 rootcomponents; a rule may not be the only place a custom value is enrolled, because generated type augmentation is unconditional.astryx theme buildtreats 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/coreand emits the same CSS as before. A theme that does carry adaptation intent — valid rules, a customwidthBreakpointsmap, or present-but-malformed adaptation metadata — fails against such a core before any output is written, withERR_CORE_INCOMPATIBLEnaming the missinggenerateAdaptationCSSexport. A complete default width map with no rules asks for nothing and still builds. Where an older core'sdefineThemedrops adaptations while resolving, the build records each rawdefineTheme()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.blackandneutralPalettes.whitefor 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, soresultCount,emptyResult,resultKind, anddirectMatchare now populated forcomponent,docs,hook,template,theme list/add/targets,discover,blog,swizzle --list,upgrade --list,layout grammar, andmanifest, not justsearchandbuild.resultKindgainstheme,integration,migration,command, andnone; 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 nowschemaVersion: 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 integrationchecks 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 upgradetransforms 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 --applymigration for the Core bare selector-class removal. The transform parses.cssselector 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
@pathagent 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-specifieraffect 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.mjsexport default {debug: event => appendFileSync('runs.ndjson', JSON.stringify(event) + '\n'),};That is the whole feature. Setting
debugopts in; the function receives oneDebugEventper 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 — underoutput— 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 aprocess.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--helpshort-circuit before any hook runs.eventis a published contract:DebugEventis exported from@astryxdesign/cli/debugwith a sealed zod validator,parseDebugEvent, drift-locked to the type so the recorder cannot add a field without publishing it.schemaVersionis 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--jsonenvelope stays valid. (#5929)Nothing changes for a project that has not setdebug. Startup is unmoved: the environment probe is deferred to delivery rather than run inbegin, because its firstIntlcall initialises ICU and that alone was ~9% of the CLI's startup for everyone. Nor does the config run:Project.loadevaluates 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 worddebugappears 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_keyand--apiKeyare one rule;key,patandpware matched whole so they do not take--keyboardand--pathwith them.argvis scrubbed pairwise, so--token hunter2loses its value the way--token=hunter2does. 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 bypassedcliErrorbeing indistinguishable from a classified failure, a signal-terminated run leaving no record at all, a sensitive--flag=valuescrubbed inargvbut 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-keyand--token valuereaching a handler intact, and the two startup costs above.One change reaches beyond this feature:installJsonShimnow 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--jsoncontract. - CLI:
astryx init --jsonnow works. It emits the install receipt as a standard envelope —init.runwith the mode, the features that ran, the agent-doc files written, any softdocsError, and the template outcome, orinit.removefor--remove-agents. Human output is suppressed so stdout carries only the envelope, and the exit code is unchanged from human mode. (#4812)initwas the last side-effecting command still refused by the--jsongate. That gate existed to stop a command writing half a project and only then reporting that--jsonwas unsupported; sinceinit()already returned a typed receipt, the fix was to emit it rather than to keep refusing.themeandlayoutremain 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
debughandler, so installing it turns on its debug logs with no change to the app. Exportdebugfromastryx.integration.*; the app's owndebugstill 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-pagetemplate 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
isFullBleedprop 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'sisFullBleed, 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 apaddingBlockEndper-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 meetshasDividerat any header padding. Thedetail-pagetemplate 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-detailpage 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"returnedlogin,contact-formanddocumentation-designat 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, soscoreQuerynow reports the coverage it already computed:matchedTerms/queryTermson 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 currentmain, which landed integration search (#5259) and the scorer-level false-direct-match fix (#5614) while this was open. Both aremain's implementations, untouched here — this branch no longer rewritesgatherComponents, 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 Corebuttonsearch into an empty success. - A thin
buildkit 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 failurebuildexists to prevent.Below three offerable results the kit carries ahintnaming 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:hasResultsis already true for a query that matched things and then filtered them all out, and that is the case most likely to be misread.hintis 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 hardcodedastryx component --listdoes not resolve in a pnpm workspace, where every other command in this output renders aspnpm exec astryx. The renderer formats them throughformatCliCommand, so they are runnable as printed, and a JSON caller gets the parts rather than prose to re-parse.hintis present only when it applies, so a healthy kit is byte-identical to before. The CLI renders it last, as aFEW MATCHESsection 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 theBuildKitResponsetype both updated. - The shared CLI blog adapter (
blog.list,blog.detail) cleared its 15-second abort timer as soon asfetchreturned 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
DebugEventclaimedredacted: truewhileenvhad never been through the scrubbing pass, and it stored the rawagentSessionIdbeside 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 onDebugEventEnv: no identity, attribution only from positive evidence, and free text scrubbed.env.agentSessionIdis always null — join runs onenv.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.redactedis set only on the sealed copy, after every pass has actually run.DebugSchemaVersionwidens to1 | 2and the CLI emits2, so code that switches on it is forced to handle both rather than silently reading a field that no longer means what it did.parseDebugEventis 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:debugand the wholeDebugEventsurface 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 anunknown_manifest_keywarning 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
packageManageryour project declares. (#6051) Oneyarn installinside a pnpm project leaves ayarn.lockbehind forever. A single lockfile used to outrank thepackageManagerfield, so the CLI answered "yarn" for a project that says pnpm — and printedyarn astryx …in every command it suggested, including the invocation line written into agent docs, where agents copy it.astryx doctorcalled that setup healthy.The declaredpackageManagerfield now decides, whatever lockfiles sit beside it. The documented fallbacks are unchanged: with nothing declared, a single lockfile still answers, a committedpnpm-workspace.yaml/.yarnrc.yml/bunfig.tomlstill breaks a multi-lockfile tie, an unbroken tie still resolves to the neutralnpxform with a doctor FAIL, and the runner is still consulted only when the whole walk found nothing.astryx doctornow WARNs when a lockfile contradicts the declaration, names the file, and says what to delete — instead of reporting the project as fine. astryx search(andastryx 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 forOutline, even thoughOutline.doc.mjsdeclares'table of contents'verbatim as a keyword, becauseTable-related templates each matchedtableandcontentsseparately 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.- CLI:
searchandbuildnow report how many results MATCHED, not how many were returned. (#6051)matchCounton abuild.kitenvelope, andoutput.resultCounton a recorded run, were both the length of the list after--limithad 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 --jsonnow carriesmatchCountalongsideresults, and the text view saysResults for "x" (2 of 57)when the list was cut short. The payloads themselves are unchanged:resultsis 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, anddashboard-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. Thetemplatecommand and machine-readable schema are unchanged. (#5927) Two categories move with their slugs:dashboard-comparisontakesDashboard - Comparison(it previously sharedDashboard - Analyticsverbatim with thedashboardtemplate, so neither owned the keyword) anddashboard-scorecardtakesDashboard - Scorecard. Both values are added to theTemplateCategoryunion; the superseded values stay reserved. Domain vocabulary — portfolio, holdings, monitoring, uptime, executive summary — is untouched in eachdescription, which is where retrieval actually reads it from.Also fixes a typo in the scorecard template'snamefield ("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)
detectPackageManagerchecked lockfiles in a fixed order and returned the first hit, so a directory holding more than one lockfile was resolved by array position.yarn.lockis first in that array, which means a singleyarn installinside 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 explicitpackageManagerdeclaration 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 strayinstalldrops a lockfile; it writes none of those.The runner (npm_config_user_agent) deliberately does NOT break that tie. An agent handed the wrongyarn astryxline 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.detectPackageManagerreturns the neutralnpx, which is correct under every package manager, and the newexplainPackageManagerreportsambiguouswith the tied candidates.astryx doctorturns that into a FAIL naming the directory and the fix — add apackageManagerfield, or delete the lockfile that does not belong. It is the refusalfindConfigPathalready 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)
searchindexes a component's usage guidance, one tier below its description. (#5937) A component's best practices are where the reader's vocabulary lives.Bannerdescribes 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,sourcesandattentioneach 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 putToastbehindCard,DialogandItemon "notification".It sits deliberately BELOWMIN_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 movingnested menufrom SideNav to List, andexplain why a field is requiredfrom 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 reasonweakKeywordsare 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
SideNavItemactionsprop 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.mjsis now GENERATED byte-for-byte from the CLI's dependency-free leafpackages/cli/foundation/agent-docs/agent-doc-state.mjs, andpnpm check:setup-contract— wired intocheck: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 theshouldNudgedecision 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.shouldNudgeand 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-contractalso fails if core stops listing the generated file infiles, 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.accessibilityrequirements, andastryx componentrenders 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:stepperDownwithout widening the requiredIconRegistrykeys (#5466)<Icon icon>,useIcon, anddefineTheme({icons})accept keys such asnumberInput:stepperDownandrichtext:bold; misspelled built-in names remain type errors. NumberInput keeps a compact centered Core fallback, while themes can override its steppers independently from the sharedchevronDownsemantic. - Rebuild the
settings-dialogpage template with searchable navigation, responsive grouped controls, live appearance previews, configurable keyboard shortcuts, and docsite gallery visibility. (#5568) - New
table-filterpage 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 aComplexSelectorwrapping a rangeSlider— that swaps toPowerSearchfor anything the tokens can't express. Both modes read and write the samePowerSearchFilter[], 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 anIntersectionObserver, 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 theTable - Filteringcategory, already reserved in theTemplateCategoryunion.
Fixes
build/searchno 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,findComponentSourceandfindHookDocprobed candidate paths withfs.existsSync, which answers through the filesystem's own case folding. On a case-insensitive filesystemastryx component buttonresolved toButtoninstead of reporting an unknown component with suggestions, andfindHookDoc(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:rootin@layer astryx-base, so nested themes inherit parent overrides andastryx theme buildmatches<Theme>whilegenerateThemeCSSkeeps 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 whenNumberInputmoved totype="text"for formatted display: a text input's defaultsize=20made the field ~200px instead of ~65px, and the template was pinning it with astyleminWidth(a floor, not a cap) plusflexShrink: 0. The field now usesNumberInput'swidthprop, 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-5card 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,useDevWarninganduseIndicatorFocusRingare now discoverable. The CLI's hook index is built from the.doc.mjsfiles next to each hook, and these seven shipped without one; soastryx hook <name>answered "No hook named",astryx hookomitted them andastryx searchnever 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; foruseAnnouncethat means a hand-builtaria-liveregion, 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
buildandsearchretrieve them from a description of the problem rather than a guess at the slug. (#5615)
Contributors
Thanks to everyone who contributed to this release: