What's New
Release notes and changelog for all packages.0.4.3
Fixes
- The unloaded-font advisory is a notice, not a warning. A theme file cannot load a font — Astryx sets
--font-family-*and loading is the app's job — so #5045's advisory fires on any theme naming a webfont, including a perfectly correct one. As a warning that made a clean build read as defective, and it put the shipped template permanently in violation of its own "compiles with no warnings" guard (#5079 had to allowlist the template's two font names in that assertion). Thetheme.buildreceipt now separates the two:warningsare defects the author should fix,noticesare advisories about a correct theme. The font advisory moves tonoticesand to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back towarningsbeing empty, and no longer needs to know which fonts the template names.Programmatic callers readingdata.warningsfor font advisories should readdata.notices; the message text is unchanged. extendsnow reaches the CSS. A theme that extended another built a stylesheet holding only the declarations it stated itself: the base's tokens, component overrides and surface rules were all absent, and because each theme is@scoped to its owndata-astryx-themevalue, loading the base's stylesheet alongside could not fill the gap either. Every consumer of an inheritance chain silently got stock geometry, elevation and type with a new palette painted over it (#5067). Nothing warned; the loss only showed up by diffing two generated stylesheets token by token. The cause wastheme buildshadowing its own inputs. It writes<name>.jsnext to<name>.ts, and the loader resolved a plain./<name>specifier to that generated artifact before the source — so the second build of a family read the artifact, which carries nocomponentsand exports<name>Themerather than whatever the source exports. A named import that missed becameextends: undefined, anddefineThemetreated an absent base as no base at all. The loader now resolves source extensions first, which is also the resolution the author's TypeScript sees, so the CSS a build emits matches the theme that type-checked.Three things behind it are fixed too, so the failure cannot come back by another route.defineThemethrows whenextendsis present but is not a theme, naming the likely cause, instead of inheriting nothing — the one behavior change here, and it turns a silent stylesheet into a build error. A theme'sonDark/onLightsurfaces and its__inputTokensare now inherited like its tokens and components were, so a child no longer reverts its base's inverted-surface customizations to the defaults or loses its[light, dark]tuples. And a built theme module now carries the resolvedcomponentsand surfaces alongside its tokens, so extending one — the./builtsubpath every shipped theme exposes — is no longer lossy.theme buildalso stopped hand-picking fields when it re-resolves a plain object theme file, which droppedextends,colorandsyntaxon the way in.An extended theme is flat: everything it inherits is resolved into its own output, and its stylesheet stands alone. Measured on a 14-theme family (one base, 13 palettes extending it): each palette went from 25 custom properties and no component rules to the base's full 175 and 70, with its own colours still winning.
Contributors
Thanks to everyone who contributed to this release:
0.4.2
New Features
astryx theme buildwarns when a theme names fonts it does not load. The resolved--font-family-*tokens and component-overridefontFamilyvalues are checked against CSS generics and known system families; anything else gets one warning per family in the receipt and, after the install instructions, the<link>/@font-facesnippet to add.astryx docs typographygains a Loading Custom Fonts section (Google Fonts and self-hosted recipes,font-display: swap, real fallback stacks), and the theme docs' production-build section points at it (#5015).astryx theme templatewrites an annotated theme template into your project (#5048). New sibling oftheme add: whereaddstarts you from a theme we ship,templatestarts you from a blank annotated one.astryx init --features themecalls the same leaf, so project setup writes it too — it previously printed a one-line hint and wrote nothing, which is the weakest form of the help a theme author needs, since the first problem is not knowing the command but not knowing what the theme surface contains. The file istheme.template.ts: everydefineThemefield with a note on when to reach for it, the token families, the component override syntax, and the consumption steps (providing the theme, loading the fonts you name, building for SSR), each section naming the CLI command that prints its authoritative reference. An existing file is never clobbered.This came out of a vibe test (#5047): agents given an annotated template reached twice as far into the theme surface as agents given only the docs (17 component targets vs 8, and the only arm to use interaction states, custom variants andonDark), and shipped a third of the contrast defects.A template that lies is worse than no template, so its claims are machine-checked against live sources rather than trusted:scripts/check-theme-template.test.mjsfails when adefineThemefield is added and left undocumented, when a token family is missing from the inventory, when a CSS variable or component key it names does not exist, when it cites a docs topic that does not, or when a theme source drops its SYNC reference.theme buildcompiles it warning-free in CI, and the CLI typecheck now covers it.
Fixes
- Heading's
typeis a documented theming target, and the docs stop teaching a CSS variable that does not exist (#5016).Headingreflectstypeas a theme selector —typography.scalegeneratesheading: {'type:display-1' …}rules for it — buttheming.targetslisted onlylevelandcolor, soastryx theme buildwarnedUnknown prop "type" on component "heading"on every theme that sets a type scale, including the shippedneutralTheme. The drift guard missed it twice over: it read a conditional spread ({level, color, ...(type && {type})}) as an unknown bag, and it only checked a component against a doc file in its own directory, soHeading/— documented fromText/Text.doc.mjs— was never checked at all. Both are fixed, which brings three more previously unchecked directories under the guard.Separately, the theme docs' component-override example set--button-press-scale, which no component defines: copying it produces CSS that silently never applies. It now sets a real public var, and the example no longer declares the samebuttonkey twice. - Two guards left failing on
mainby their own landings, so every PR since has been red through no fault of its own. #4963 gave Thumbnail's remove button a coarse-pointer hit-area var and did not document it, which the derived-var guard reads as an undocumented private var; the var is aninseton a::afteroverlay, so it is documented as private and listed alongside the other vars no standard CSS property maps onto. #5026 movedborderDefaultsintoCoreTokenName— the landing the theme-template guard was explicitly waiting for (its comment says "when #5017 lands, this guard starts requiring the template to cover it") — so the template's token inventory now names--border-width.
Documentation
- MobileNavToggle preview simulates a mobile AppShell instead of an empty stage: new playground.appShellMobile for components that render nothing without AppShell mobile context (#4983)
Contributors
Thanks to everyone who contributed to this release:
0.4.1
Fixes
astryx theme buildno longer warnsUnknown propfor documented state override keys. Component docs declare state-driven selectors undertheming.targets[].states(radio→checked/disabled,calendar-day→today/selected, …), but override validation only loadedvisualProps, so the state syntax the Theming Infrastructure wiki documents —components: {radio: {checked: {...}}}— warned on every build. The CSS was always generated correctly; only the warning was wrong. 30 targets across core were affected (#4778).
Contributors
Thanks to everyone who contributed to this release:
0.4.0
Breaking Changes
- DropdownMenu's two item modes are peers again. Compound mode gains a
DropdownMenuDividercomponent (aliased asContextMenuDividerandBreadcrumbMenuDivider), which the data path also renders, so{type: 'divider'}and<DropdownMenuDivider />produce identical DOM, spacing, and theme target. Data mode gainsendContentanddescription, so anitemsrow can carry a shortcut hint or secondary text without dropping to compound mode. Itslabelwidens fromstringtoReactNode, matching compound mode: the narrowing existed only because rows were keyed by label, and they no longer are (#4953). The bare names now belong to those components, so the data-mode option types take theDatasuffix their siblingDropdownMenuItemDataalready carries:DropdownMenuDivider→DropdownMenuDividerData,ContextMenuDivider→ContextMenuDividerData,BreadcrumbMenuDivider→BreadcrumbMenuDividerData. TypeScript cannot re-export a value and a type under one name from a single barrel, so the rename is what makes the components exportable at all. Runastryx upgrade --applyto rewrite the type imports; a missed one fails at compile time rather than silently.
New Features
- Add the
migrate-table-rowexpansion-to-treecodemod (runs onastryx upgrade): rewrites the removeduseTableRowExpansionStatetree pattern touseTableTreeState+useTableTreeData. Detail-panel usage (renderExpanded) is left untouched. (#4884) - Add a self-documenting layer to the CLI: typed, colocated
.doc.mjsfor every command, every@astryxdesign/cli/apifunction, and every authored schema (config, integration, codemod, the response envelope, and the doc-types themselves). Adds theFunctionDoc,SchemaDoc,CommandDoc, andEnumDocauthoring types with sealed parsers. (#4714) Every command's--helpand itsastryx manifestentry are now built from that command's colocatedCommandDocvia adefineCommandconverter, so the docs and the CLI can no longer describe different things. The migration is behavior-preserving: help text, command output, error paths, and exit codes are byte-identical.The CLI README's command, error-code, and response-type tables are now generated from the manifest and theEnumDocs, correcting real drift — the error-code table listed two codes that do not exist and omitted several that do, and the command table was missingblog,build,layout, andvalidate-integration.Kept honest by a drift harness (docs vs the live CLI),check:cli-structure(each doc-type andapi/leaf ships its full file set), and lint rules for the CLI's layering. - Add themeable indicators — the componentized check, checkbox, and radio visuals.
defineTheme({indicators: {check: RadioIndicator}})replaces one by name, and every component drawing it follows. (#4712) Theme targets now follow the component-name convention:checkbox-indicator,radio-indicator,radio-indicator-dot. The old names (checkbox,radio,radio-dot) remain emitted on the same element so existing themes keep working. New themes should use the canonical names; deprecation does not set an automatic removal deadline.Migration: menu radios use those shared targets now.dropdown-menu-radio-dotis removed — targetradio-indicator-dot;astryx upgraderewrites it for you.
Fixes
- The generated agent cheat sheet hardcoded a shell recommendation ("Full page → AppShell; sidebar nav → SideNav", "pick the shell (AppShell / Layout+LayoutPanel)"), which answers a question that depends on the app archetype and duplicates guidance
astryx docs layoutalready maintains. The two layout rules now send agents to that doc instead, so shell choice, region budgets, and the responsive contract have one source of truth. (#4772) The rule cites the command rather than the docsite URL, in the block's establishedastryx <cmd>form that the header maps to the project's real invocation (pnpm exec astryx,npx @astryxdesign/cli, …).astryx docsreads the docs shipped inside the installed version, so an agent can't be shown an API that release doesn't have. - The
migrate-grid-minchildwidth-to-columnscodemod bailed without changes when a<Grid>had bothcolumnsandminChildWidth, leaving the now-invalidminChildWidthprop in place and failing type-checking on 0.3.0. (#4792) Whencolumnsis a numeric literal, it now migrates losslessly to the 0.3.0 object form. This mirrors the old (0.2.0) Grid runtime, whereminChildWidthdominated and the numericcolumnscapped the column count underauto-fit:<Grid columns={3} minChildWidth={280}>becomes<Grid columns={{minWidth: 280, max: 3, repeat: 'fit'}}>. Object or dynamiccolumnsvalues remain a deliberate bail. - The documented
hookexample referenceduseToggle, which is not a hook in the design system — running it failed withERR_UNKNOWN_HOOK. It now usesuseFocusTrap. (#4742) This shipped in two places a consumer sees:astryx manifest --json, which agents read to learn the CLI, and thehookCommandDoc that feeds--help. Replaced in both. - CLI internals: a true
foundation/bottom layer, and generated./authoringtypes (#4736).foundation/no longer importsapi/, and ESLint now enforces that direction alongside the existingauthoring/andapi/rules. Two things were reaching upward:Projectpulled template discovery out ofapi/template, whose adapter importedProjectstraight back, and bothProjectandintegration-warningsimportedvalidateLoadedIntegrationfrom thevalidate-integrationcommand. Neither was misplaced logic, just misplaced files — the adapter now lives atfoundation/discovery/template-adapter.mjsand the validators atfoundation/integrations/validate-contributions.mjs. To be precise:Projectand the template adapter still import each other, so that module cycle remains, contained within foundation instead of spanning two layers. Behavior-preserving — the CLI's observable surface is byte-identical across 84 invocations.The published./authoringtype declarations are now generated from their JSDoc instead of hand-written, the same way./apialready works. The 13 hand-maintained.d.mtsfiles are gone;scripts/sync-api-types.mjsemits both trees atprepack, stamped@generated. A hand-written declaration shadows the JSDoc in its.mjs, so it could disagree with the implementation and still compile — and both failure modes had shipped: a missing declaration made a strict consumer resolve that parser asany, and a staleparseDocreturn union silently droppedSchemaDoc,CommandDocandEnumDoc. Also fixesparseFunction, a bare re-export ofparseHookthat publishedHookDocinstead of the generalFunctionDoc. - Scaffolding a template that references demo video (e.g.
LightboxVideo) no longer replaces the video source with the image placeholder data URI, which the generated<video>element couldn't play.stripTemplateAssetRefs()treated every demo-media reference as an image regardless of extension; video extensions (.mp4,.webm,.mov,.ogv) are now stripped to an emptysrcinstead — there's no equivalent self-contained inline placeholder for video, so the scaffolded example is honest about needing the builder to supply their own file rather than pointing at something that can't play. (#4863) - Stepper templates: the scaffolded Stepper blocks gain the a11y, theming and responsive-label hardening from the component audit, and their doc blocks match what they render (#4917).
- cli: add
theme build --icons-specifierso the generated module's icon import can be fully specified (#4620) The generated theme module imports the icon registry rather than inlining it, because the registry holds React elements.astryx theme buildscraped that specifier out of the TypeScript source and emitted it verbatim, so./icons— valid TypeScript, invalid ESM — reached the generated.js. Every published theme's/builtentry therefore failed to load in Node, including under Vite SSR and Next.js Pages Router, while bundlers papered over it by guessing the extension.No single extension is correct: the same source compiled by tsup lands aticons.mjsin a package with no"type"field and aticons.jsin one with"type": "module", and the generator runs before the compile step that produces either. The caller knows; now it can say so. Without the flag the specifier is emitted unchanged, so the default no---outflow — where the neighbour is an uncompiledicons.tsxthat only a bundler can resolve — is unaffected.The seven theme packages now declare--icons-specifier ./icons.mjsin their build scripts.
Other Changes
- The scaffolded login pages use
Center'spaddingprop instead of a hand-writtenvar(--spacing-6)style object (#4764). - Self-host template demo imagery in the repo instead of streaming it (#3973)
from the internal
lookaside.facebook.comCDN. - Template demo images are now committed under
apps/docsite/public/template-assets/and referenced by root-relative/template-assets/*paths (previously Meta-internal CDN URLs invisible to external contributors). stripTemplateAssetRefsstill swaps these paths for the inlinedata:URI placeholder on scaffold, so generated projects render with zero setup and no network dependency — no image is ever copied into a scaffolded project.
Contributors
Thanks to everyone who contributed to this release:
0.3.0
Breaking Changes
- CLI — authoring is consolidated into a single entrypoint,
@astryxdesign/cli/authoring, that exposes only TYPES (the plain objects authors write) and PARSERS (the CLI's load-boundary validators). Zod is sealed inside each parser and never exported. - Remove long-deprecated compatibility APIs from core and CLI. Run
astryx upgradefirst to migrate the supported replacements for authoring imports, Dialog logical positions, Switch label spacing, and Table root props.
New Features
- CLI human (non-
--json) output now renders through a small, documented formatter kit: consistent, plain-ASCIIkey: valuerecords/sections that mirror--jsonand are greppable by field. Every command was migrated onto it (a lint rule keeps output funneled through the singleemitsink), andastryx --helpdocuments the output contract.--jsonoutput is unchanged. (#4686) defineTheme: makecolor.accentoptional (#2279) A theme can now restyle the neutral ramp (neutralStyle,contrast) without adopting an accent. An accent-less config seeds the neutral palettes from the default accent's hue but leaves--color-accent,--color-accent-mutedand--color-on-accentungenerated, so they fall through to the token defaults — the same fall-throughexpandColorScalealready applies to status, categorical and on-dark tokens. Configs that pass an accent are unchanged, token for token.
Fixes
- theme build: generated custom Button variants now type-check through the public
@astryxdesign/core/Buttonsubpath. - Remove the
@xds/theme-default→@astryxdesign/theme-neutralcollapse from the v0.1.0 upgrade codemods (module-specifiers, css-surfaces, and declare-module).theme-defaultwas dropped at the v0.1.0 scope move, so no v0.1.x consumer imported it — the collapse was dead and could rewrite unrelated source (including@xds/theme-default/theme.cssCSS imports) to a@astryxdesign/theme-neutralpackage the app never declared. The@xds/theme-daily→theme-neutralcollapse (and itsdefaultTheme→neutralThemeexport remap) is unchanged. - cli — confine user-controlled file paths, close DoS vectors, and repair paths broken by the authoring reorg (#4637)
- cli hardening pass — validate inputs at the API layer, close path-safety gaps, and prevent agent-docs content loss. The API is a public surface (
@astryxdesign/cli/api), so guards that lived only in the CLI wrapper are pushed into the API. Path safety (the guard the write commands all depend on): - cli — rename the
search/buildverbose flag to--verbose, resync the bundled themes, and fixunwrap-authoring-factoriesedge cases (#4639) astryx doctor's peer-dependency check is now version-aware and names scoped packages correctly. Two problems are fixed: (1) the install hint was built withname.split('@')[0], which for a scoped peer like@stylexjs/stylexreturned an empty string, printing a barenpm installwith no package; and (2) the check only verified a peer was present, not that its installed version satisfied the declared range — so an out-of-range version (e.g.@stylexjs/stylex@0.10.1against a^0.19.0peer) was reported as satisfied. The check now flags out-of-range peers and its fix pins the required range, e.g.npm install @stylexjs/stylex@^0.19.0.- theme build: validate component override keys from documented theming targets so subtargets like Chat bubbles and SideNav items no longer warn as unknown.
astryx theme build: hyphenated component-override keys now resolve their built-in visual-prop values, and theKNOWN_COMPONENTSprop lists match what each component renders (#4109)loadKnownValuesmapped a theme key to its core component directory by stripping non-letters from only the directory name, so a hyphenated key (text-input,dropdown-menu,app-shell, ...) never matched itsTextInput/DropdownMenu/AppShelldir and the built-in prop values were silently dropped. It now strips non-letters from both sides before comparing, so hyphenated keys resolve. TheKNOWN_COMPONENTSvisual-prop lists are also synced to each component'stheming.targets[].visualProps(e.g.text-input/date-input/number-input/time-input:size,status;side-nav:mode;aspect-ratio:shape), correcting stale/empty entries.
Documentation
- Document the core codemod staging workflow and add release-time automation that promotes
transforms/nextcodemods into the resolved release version folder. - Document the
@astryxdesign/coreStyleX peer dependency — add@stylexjs/stylexto the Getting Started / Quick Start install commands in both READMEs, and add anastryx initnext-steps reminder to ensure the@stylexjs/stylexpeer dependency is met, with a pointer toastryx doctor. StyleX is the styling runtime every component calls, and not all package managers auto-install peers. - Surface the React 19 peer-dependency requirement everywhere a user would look for it (root README, core README, docsite hero, and the CLI getting-started guide), and add a sync test that keeps those surfaces naming the same React major as the core peer range.
Other Changes
- The
create*factories are removed (createConfig,createIntegration,createComponentDoc,createFunctionDoc,createDoc,createPageTemplate,createBlockTemplate,createCodemod,createConfigCodemod). Author a plain object and stamp itstypedirectly ({type: 'component', ...},{type: 'page', ...},{type: 'code', ...}); config and integration manifests are plain objects with no discriminant. - Import authoring types from
@astryxdesign/cli/authoring— the doc typesComponentDoc,HookDoc,ReferenceDoc,TemplateDoc, and the project-file typesAstryxConfig,AstryxIntegration,AstryxCodemod. The old split surfaces (@astryxdesign/cli/{config,doc,integration,template,codemod}and the authoring exports of@astryxdesign/core) are superseded. - Doc field types are renamed to explicit, domain-prefixed names so the surface reads clearly:
PropDoc → ComponentPropDoc,ThemingTarget → ComponentThemingTarget,ComponentVar → ComponentThemingVar,DerivedVar → ComponentThemingDerivedVar,ElementDescriptor → ComponentSlotElement,GroupDoc → ComponentGroupDoc,TranslationDoc → ComponentTranslationDoc,ExampleDoc/AnatomyElement/BestPractice/PlaygroundConfig → Component*, andContentBlock/TokenPreviewType → Reference*. The authorable entry types (ComponentDoc/HookDoc/ReferenceDoc/TemplateDoc) are unchanged. astryx upgrademigrates you automatically. Three codemods ship in this release:unwrap-authoring-factoriesrewrites everycreate*call to the plain stamped object,migrate-authoring-importsrepoints the import specifiers to@astryxdesign/cli/authoring, andrename-authoring-doctypesapplies the doc field-type renames (imports, type references, and JSDoc@typerefs).- CLI — the public
@astryxdesign/cli/apitype surface is now generated from the runtime JSDoc, and the injectable logger is consolidated into oneLogger. Consumer-visible changes to@astryxdesign/cli/api(types only — runtime imports are unchanged): - Precise return types.
component,docs,blog,discover,build,swizzle,upgrade,init, andthemeBuildpreviously resolved toPromise<any>; they now return their precise{ type, data }response unions. Code that leaned onanymay surface new (correct) type errors. - Response types are now exported by name — e.g.
ComponentDetailResponse,SearchResponse,UpgradeRunResponse— alongsidethemeAdd/themeList/listThemesand a new sharedloggervalue +Loggertype. - Breaking: the per-command return-union aliases
ComponentResult,DiscoverResult,DocsResult,HookResult, andTemplateResultare no longer exported. UseAwaited<ReturnType<typeof component>>(still works), or import the member response types directly. theme build --out/<file>, thevalidate-integrationmanifest roots (components/templates/codemods), andlayout --fileare now confined withassertWithin. An escaping integration root reports a validation issue instead of importing and executing files outside the package;layout --fileis also size-capped (5 MB) and rejects non-files, so a stream like/dev/zerocan't exhaust memory.- Fuzzy-match (Levenshtein), the layout value parser, and the layout expander gained bounds — a very long search query, a deeply nested attribute value, and a huge repeat count (
Box*999999999) can no longer spin the CPU, blow the stack, or exhaust the heap. - Docs topic lookup uses a null-prototype map so
__proto__/constructoras a topic name can't bypass the unknown-topic guard. The shipped getting-started docs and the sandbox registry generator point at the current CLI source path again (both broke in the authoring reorg). assertWithinnow canonicalizes symlinks (realpath of the deepest existing ancestor) — a symlink inside the project root pointing outside no longer lets a write escape. Also rejects a NUL byte in the path. This closes the escape for every command that writes through the guard (swizzle/template/upgrade/theme/layout/agent-docs).search(): non-positive/non-integerlimit, empty query, unknown--type→ERR_INVALID_ARGUMENT(previouslylimit: 0returned the full unclamped set).swizzle(): the component name is sanitized so../separators can't escape the--outputbase.swizzle()import rewriting: dynamicimport('../Sibling/…')is now rewritten (was left pointing at a non-existent sibling in the output dir); a two-levels-up asset import (../../locales/x.json) maps to the exported subpath instead of the invalid<pkg>/..; and../theme/tokens.stylexkeeps its full subpath (the StyleX compiler needs the dedicated./theme/tokens.stylexexport — collapsing it to<pkg>/themebroke StyleX resolution). Component-local.stylexfiles that aren't subpath exports keep the working barrel collapse.template()copy: refuses to clobber withoutoverwrite: true(ERR_FILE_EXISTS); adds anoverwriteoption.upgrade(): the--pathscan dir is confined to cwd (--applyrewrites files in place).init(): template scaffold refuses to clobber an existingpage.tsx(ERR_FILE_EXISTS); an unknown--agentnow throwsERR_UNKNOWN_AGENT(was silently ignored).layout: rejects an unknown--form(ERR_INVALID_OPTION) and empty expression (ERR_INVALID_ARGUMENT).layout expand: text payloads containing<,>,{, or}(e.g.Text"5 < 3") are emitted as JSX string-expression children so the generated TSX is valid — previously they produced syntactically-broken output.layout expand: a top-level repeat or group that expands to multiple sibling elements (B"x"*3,(B"a" + B"b"), an outlinerepeatblock) is now wrapped in a fragment — previously the generated TSX had adjacent root elements with no parent and failed to compile (the wrapper decision counted AST roots instead of expanded elements).layout(expand/check): an empty expression now surfacesERR_MISSING_ARGUMENTand a missing--filesurfacesERR_FILE_NOT_FOUND(was a genericERR_UNKNOWN/ a rawENOENTerrno, with a stack leak in human mode).layoutparser: a pathologically deep compact expression (V > …nested past 512 levels) is rejected with a locatedERR_LAYOUT_PARSEinstead of blowing the call stack and surfacing a rawRangeError(→ERR_UNKNOWN).layout check --form …printers: a string containing a quote (e.g. a Buttonlabel="Don't panic") now round-trips — the printer picks a delimiter the string doesn't contain instead of always single-quoting, so the emitted compact/outline surface re-parses (was producing an unparseable token).resolveTheme: a non-stringastryx.themein package.json (number/array/object/boolean) degrades to null instead of crashingastryx componentwith a rawTypeError(parity with the empty-string / unknown-slug paths).jsonOut: serializes the envelope BEFORE marking the emission handled, so if a command returns unserializabledata(circular ref / BigInt — an author bug) the bin error boundary still emits a JSON error envelope instead of leaving a--jsonconsumer with empty stdout.- package scanner: a dependency's
astryx.docsthat is a non-string (number/array) is skipped instead of crashing the whole scan with a rawTypeError, and adocspath that escapes its own package dir is skipped rather than surfacing foreign docs; a non-string packagenameis coerced to a string. component --package <pkg> --showcase/--blocks: route to the right leaf instead of falling back tocomponent.detail.discover/docsleaves: empty query/section errors instead of matching everything via.includes('').docs()/discover(): a non-stringtopic/section/querynow throws a stable coded error (ERR_UNKNOWN_TOPIC/ERR_UNKNOWN_SECTION/ERR_INVALID_ARGUMENT) instead of a rawTypeErrorthe CLI downgraded toERR_UNKNOWN(parity with thecomponent/hooknon-string guards).blog()detail: a non-string slug throwsERR_INVALID_ARGUMENT(was a rawTypeErrorthe CLI downgraded toERR_UNKNOWN), and fails fast before any network fetch.hook()/component()dispatchers: a non-stringnameorcategorythrows a coded error (ERR_UNKNOWN_HOOK/ERR_UNKNOWN_COMPONENT/ERR_UNKNOWN_CATEGORY) instead of a rawTypeErrorwith no.codefrom the leaf's.toLowerCase()/.replace(...).theme add: a write failure where an ancestor of the target dir is a file now surfacesERR_WRITE_FAILED(themkdirmoved inside the write try/catch) instead of leaking a raw fs errno (EEXIST/ENOTDIR) + absolute path.validate-integration: a path-unsafe[package]spec (../absolute) is reported as aninvalid_package_specdiagnostic instead of crashing with a raw stack (human) / genericERR_UNKNOWN(--json).doctor: no longer crashes (raw stack in human mode /ERR_UNKNOWNin--json) when multipleastryx.config.*files coexist — it reports aconfigFAIL. Version-alignment skips (info) instead of a spurious drift WARN with aNaN.undefined.xfix when either version isn't comparable semver (e.g.workspace:*).manifest: subcommands are sorted by name (same stability guarantee the top-level command list makes), so reordering.command()calls can't silently change the agent-facing manifest.build: the CLI wrapper now propagates the API's errorcodeinto the--jsonenvelope (bogus--type/ non-positive / non-integer--limit→ERR_INVALID_ARGUMENTinstead of a genericERR_UNKNOWN), and delegates--limitvalidation to the API (parity withsearch).layout check: exits1in BOTH--jsonand human mode for an invalid (but parseable) layout — the exit code no longer depends on the output mode, so it works as a CI gate / agent check without parsing stdout.upgradeconfig codemods: afindConfigPaththrow (multipleastryx.config.*files) is surfaced as a structured per-codemod error instead of crashing the whole upgrade run — config codemods run before the strict loader, so this restores the per-codemod isolation every other failure path honors.- CLI dispatch: the belt-and-suspenders postAction "completed without emitting an envelope" error carries a
code(ERR_UNKNOWN) so every error envelope is branchable oncode. toErrorEnvelope/AstryxError: attachsuggestionsonly when it's a real array.injectXdsBlock/removeXdsBlockno longer drop, duplicate, or orphan user content on malformed managed blocks (END-before-START, duplicate/nested blocks, or a start marker with no end). They locate a single well-formed block (END searched after START) and refuse to touch an ambiguous/half-written file instead of corrupting it.- The codemod source scan no longer follows symlinks (a symlinked file under the scanned path could rewrite its target OUTSIDE the project) and skips generated-output dirs (dist/build/out/.next/coverage) — codemods rewrite source, not artifacts or dependencies.
resolvePackageDirrejects an integration spec that isn't a bare package name (no.., no absolute, must stay in node_modules) — a config spec can no longer point the loader at an arbitrary module.- A broken integration manifest (throws on import or fails schema validation) no longer crashes
Project.load(and thus every command). It's recorded and surfaced viaissues(), restoring the documented skip+warn policy; other integrations still load. - The
--radius-*,--shadow-*/--elevation-*, and--color-*token-migration codemods no longer rewrite a longer consumer-defined token that merely shares a prefix (e.g.--radius-container-custom→--radius-3-custom,--radius-innermost→--radius-0most,var(--shadow-10)→--shadow-base0,--color-positive-custom→--color-success-custom). The boundary lookahead was binding only to the last alternative in the pattern (and two codemods had no boundary at all); it now wraps the whole alternation, so only exact token names migrate. migrate-badge-children-to-labelno longer emits a duplicatelabelprop when the badge already has one (<XDSBadge label="x">Active</XDSBadge>produced an invalidlabel="x" label="Active"); it now skips a badge that already declareslabel.readDocMetano longer reads agroup:/hidden:field nested inside apropDescriptionsblock (a docsZh/docsDense translation export) as the component's group — that leaked a translated prop description as a group key in the default Englishcomponent --list(e.g. a Chinese string appeared as a group). The field regexes now match top-level fields only (<=2 spaces).astryx search/buildverbose output was unreachable: the boolean--detailflag collided with the root program's value-taking--detail <level>, sosearch button --detailerroredargument missing. The boolean is now--verbose(the global--detail <level>is unchanged).- The themes bundled for
astryx theme addhad drifted from source — theneutralbundle was missing a WCAG AA light-modetext-secondarycontrast fix and a StatusDot color block, soastryx theme add neutralscaffolded a theme below AA. All bundles are regenerated to match source, guarded by a new drift test. - The
unwrap-authoring-factoriesupgrade codemod produced broken output for a shorthandtypeproperty (emitted{'component'}) and for no-argument factory calls (left a call referencing the just-removed import). Both now emit the correct plain object.
Contributors
Thanks to everyone who contributed to this release: