What's New
Release notes and changelog for all packages.0.2.0
Breaking Changes
- cli/json: remove the central
CLIAnyResponse,CLIResponseType, andCLIResponseDataMaptypes.jsonOutis now a structural serializer andparseResponse/assertResponsereturn the structuralCLIResponse({type, data, meta?}) instead of the discriminated union, soresult.dataisunknownuntil you narrow it yourself. Runtime output is unchanged (every--jsonenvelope is byte-identical). This only affects consumers importing those types or relying onparseResponse/assertResponseto auto-narrow.data. - component/hook
--jsonlist responses collapsed.--detail compact/fullpreviously emitted distinctcomponent.brief/component.full(andhook.*) envelopes; they now all emitcomponent.list(resp.hook.list) with adata.detail: 'names' | 'compact' | 'full'field. Migrate: switch ondata.detail, not the.brief/.fulldiscriminator. Removed types: ComponentBriefResponse, ComponentFullResponse, HookBriefResponse, HookFullResponse.
New Features
- CLI:
blogis now a normal, agent-facing command — it appears in--helpand the capability manifest and supports--json(emittingblog.list/blog.detailenvelopes), instead of being hidden. Human output is unchanged; the reader still consumes the public RSS feed. Also scriptable through the./apibarrel asblog(slug?). - CLI:
initis now fully scriptable through the./apibarrel — the non-interactive installer (agent-docs cheat sheet, starter template,--remove-agents) lives inapi/initand returns a typed receipt (init.run|init.remove), with the CLI reduced to a thin parse → API call → render wrapper. Human output is emitted through an injectable logger, so a scriptedinit()stays silent while the CLI output is byte-identical for existing usage. - CLI:
theme buildis now fully scriptable through the./apibarrel — the ~1,000-line theme compiler (defineTheme extraction, CSS generation via@astryxdesign/core/theme, variant/type-declaration + icon-module generation, override validation) lives inapi/theme/buildand returns a typedtheme.buildreceipt, with the CLI reduced to a thin parse → API call → render wrapper. Human progress is emitted through an injectable logger, so a scriptedthemeBuild()stays silent while the generated CSS/JS/.d.ts, the--jsonenvelope, and human output stay byte-identical for existing usage. Watch mode remains a thin CLI loop. - CLI:
upgradeis now fully scriptable through the./apibarrel — the version-to-version pipeline (codemods + agent-docs refresh) lives inapi/upgradeand returns a typed receipt (upgrade.list|upgrade.status|upgrade.run), with the CLI reduced to a thin parse → API call → render wrapper. Human progress is emitted through an injectable logger, so a scriptedupgrade()stays silent while the CLI output and--jsonenvelopes are unchanged for existing usage. - Timestamp: new
tooltipEntriesprop renders the hover tooltip across several time zones and/or formats at once — one line per entry, each with an optionaltimezoneID(IANA id; omit it or pass'local'for the viewer's zone),format(every non-relativeTimestampFormatplus'full'), andlabel. The default is unchanged: with no entries the tooltip stays the single full absolute line in the viewer's zone. Configuring entries also attaches the tooltip to absolute formats, which previously had none — note that this gives those timestamps a tab stop and focus ring, as relative timestamps already have, so a column of them gains one tab stop per row.hasTooltip={false}still suppresses the tooltip, and an empty array counts as no configuration. Also correctsisTimezoneShown's documentation, which claimed it applied to thesystem_date_timeandsystem_timeformats; it never has, and those formats stay machine-readable. (#4188)
Fixes
astryx theme build: component-override keys for multi-word components (TextInput, DateInput, NumberInput, DropdownMenu, SideNav, TopNav, etc.) now match the hyphenated class the component actually renders. The known-component registry used de-hyphenated keys, so overrides authored against them emitted dead selectors (.astryx-textinputinstead of.astryx-text-input) that silently never applied (#4109).
Other Changes
- CLI: blog reorganized into api/blog leaf shape — list/detail leaves projecting a shared RSS adapter (
_adapter.mjsowns all network fetch + feed parsing), withblog.mjskept as a dispatcher+barrel so the sameblogexport, the CLI wrapper, api/index.mjs, and the --json/human output stay byte-identical. - CLI:
buildreorganized into theapi/buildleaf shape —build.mjsis now a dispatcher + barrel that routes no-query →build.help(api/build/help/help.mjs) and a query →build.kit(api/build/kit/kit.mjs), with each leaf projecting its single{type, data}envelope. Pure reorganization: thebuildexport, the./apibarrel, and the CLI consumer are unchanged, and the--jsonand human output stay byte-identical for existing usage. - CLI:
componentreorganized into theapi/componentleaf shape over a shared_adapterresolver —component.mjsis now a dispatcher + barrel that routes to per-type leaves (list,detail,detail/props,detail/source,detail/showcase,detail/blocks), each a thin projection of a subject the adapter resolves once (core/external/scoped/integration ownership, ambiguity handling, and fuzzy search, deduped). Pure reorg: every--jsonenvelope and human output stays byte-identical across all modes. - CLI: discover reorganized into api/discover leaf shape (list, detail, detail/doc, search) behind a shared _adapter that owns external-package discovery and doc loading; discover.mjs is now a dispatcher+barrel keeping the same exports. Pure reorg —
--jsonand human output are byte-identical and api/index.mjs + the CLI consumer are untouched. Adds colocated leaf tests. - CLI: docs reorganized into api/docs leaf shape —
docs()inapi/docs/docs.mjsis now a dispatcher + barrel that routes by argument shape into three leaves (api/docs/list,api/docs/detail,api/docs/detail/section), each projecting into a single{ type, data }envelope. The discovery, overlay loading, and topic resolution shared by ≥2 leaves live inapi/docs/_adapter.mjs. Pure reorganization: thedocsexport,api/index.mjs, the CLI consumer, and all--jsonand human output are unchanged (byte-identical). - CLI: hook reorganized into api/hook leaf shape —
hook.mjsis now a dispatcher+barrel routing to colocated leaves (list/list.mjs→ hook.list,detail/detail.mjs→ hook.detail,detail/params/params.mjs→ hook.detail.params) over a shared_adapter.mjsresolver. Pure reorg:--jsonand human output are byte-identical across all modes, and thehookexport surface (api/index.mjs + CLI) is unchanged. - CLI: init reorganized into api/init leaf shape —
init.mjsis now a dispatcher + barrel that routes toapi/init/run/run.mjs(the default /--features/--allinstall path) andapi/init/remove/remove.mjs(the--remove-agentspath), with the shared plain-logger contract inapi/init/_adapter.mjs. Pure reorg:getNextSteps,noopInitLogger, and theInitOptions/InitLoggertypes stay re-exported from the barrel, so api/index.mjs, the CLI command, and the programmatic API are unchanged. Human and--jsonoutput are byte-identical. - CLI: layout reorganized into the api/layout leaf shape — a shared
_adapter.mjs(analyze/loadBlocks/formatIssueoverlib/xle) with thinexpand/,check/, andgrammar/leaves, plus alayout.mjsbarrel.api/index.mjsand the CLI are unchanged (they import via the barrel). Pure reorg:layout expand/check/grammar--jsonenvelopes and human output are byte-identical. - CLI: swizzle reorganized into api/swizzle leaf shape — the flat command splits into
api/swizzle/list(swizzle.list) andapi/swizzle/copy(swizzle.copyreceipt, incl.rewriteImports), with shared @astryxdesign/core discovery + component listing deduped inapi/swizzle/_adapter.mjs, andswizzle.mjsreduced to a dispatcher + barrel that keeps its existing exports (swizzle,rewriteImports). Pure reorganization with no behavior change: human output and every--jsonenvelope stay byte-identical, and the CLI command, the./apibarrel, and the centraltypes/swizzledeclarations are untouched. - CLI: template reorganized into api/template leaf shape (shared helpers preserved on the barrel). Pure reorg —
--jsonand human output stay byte-identical: shared discovery/IO moved toapi/template/_adapter.mjs, the command modes split intolist/show/skeleton/copyleaves, andtemplate.mjsbecomes a dispatcher + barrel that re-exports every previously-exported symbol (template, discoverTemplates, discoverAll, discoverAllWithErrors, discoverIntegrationTemplatesForOne, findShowcase, findRelatedBlocks, stripTemplateAssetRefs, listTemplates, extractComponents, and the DiscoveredTemplate/TemplateDiscoveryError types) so component/layout/search/init/discover/validate-integration and lib/project keep resolvingapi/template/template.mjsunchanged. - CLI:
theme add/listare reorganized into the fractalapi/theme/leaf shape — a shared_adapter.mjs(bundled-theme manifest reader + slug resolver) with thinadd/(copy →theme.addreceipt) andlist/(theme.list) leaves over it, plus atheme.mjsbarrel, mirroring thetheme buildextraction (#4462).themeList()is now exported from@astryxdesign/cli/apialongsidethemeAdd. Pure reorg:theme list/add--jsonenvelopes and human output are byte-identical, with new direct-API tests for both leaves. - CLI: upgrade reorganized into api/upgrade leaf shape — the flat pipeline is split into a dispatcher+barrel (
upgrade.mjs), a shared_adapter.mjs(version detection + agent-docs refresh + codemod selection/execution machinery), andlist/status/runleaves (upgrade.list|upgrade.status|upgrade.run). Pure reorg: the./apibarrel + CLI consumer are unchanged, and both the human output and--jsonenvelopes are byte-identical.
Contributors
Thanks to everyone who contributed to this release:
0.1.9
New Features
- CLI: full API coverage for the
build,swizzle,layout, andvalidatecommands — each is now scriptable through the./apibarrel with the CLI as a thin parse → API call → render wrapper.buildgains--jsonoutput. Behavior is unchanged for existing command usage. (#4302)
Fixes
- Align two
--jsoncontract shapes with what the CLI actually emits - Register all emitted response types in the
--jsonenvelope union Three response types were defined, exported, and emitted by commands but never added toCLIAnyResponse— the union thatjsonOut()type-checks payloads against:component.full,component.detail.blocks, andupgrade.status. Because their discriminators were missing from the map,jsonOut('upgrade.status', …)(and the two component variants) were rejected by the type-checker, and their payload shapes weren't actually being validated.build.helphad no response type at all. Added aBuildHelpResponsetype and wired all four into the union so every--jsonenvelope the CLI can emit is now type-checked against a declared shape. - Type
detectPackageManagerhonestly soastryx doctor's "no lockfile" branch is reachabledetectPackageManagerreturns'npx'as the sentinel for "nothing detected", but its return type only listed'yarn' | 'pnpm' | 'bun' | 'npm'. Type-checkers therefore treateddoctor'spm !== 'npx'guard as a dead comparison — the "No lockfile detected — defaulting to npm/npx" message looked unreachable and was at risk of being "cleaned up". The return type is nowPackageManager | 'npx'and detection narrows via a shared type predicate, so the guard is honest and the branch is preserved. - Make the CLI's
.mjssources fully strict-typecheckable (checkJs + JSDoc) Annotated the entire CLI package sotsconfig.strict.json(fullstrictcheckJsoversrc,bin,scripts,docs, and the emittedtemplates) reports zero errors — down from 1717. Fixes are JSDoc-only: no runtime logic changed,.mjsstays.mjs. Strict checking also surfaced and corrected several type-contract drifts: theupgrade.runresponse type (declared adepsUpdatedfield the command never emits, and omitted the realintegrations/filesChanged/transformsApplied/errors), registered the emittedtheme.list/theme.add/layout.*response types in the--jsonenvelope union, and addedcategory?toReferenceSectionin core's docs types (reference docs already emit it). - Drop the dead
cwdparameter fromgetLatestVersioncheckForUpdatecalledgetLatestVersion(cwd)and the JSDoc advertised acwdparameter, but the function takes no arguments — it only reads the$ASTRYX_LATEST_VERSIONenv var, so the passedcwdwas silently ignored. Removed the phantom parameter and its doc so the signature matches the behavior. No functional change to the update-nudge output.
Other Changes
swizzle.copypayloads always includepackageandusesStyleX(both covered by tests), butSwizzleCopyResponse.datadidn't declare them — the call site cast the payload toRecord<string, unknown>to sidestep the mismatch. Added both fields to the type and dropped the loose cast so the payload is type-checked.- The error
suggestionsshape was declared as{name, reason}(reason required) in the JSON envelope / API error contract, but some call sites emit bare{name}(e.g. candidate component names on swizzle). Introduced a single canonicalSuggestiontype (reason?optional) and referenced it everywhere so the contract matches the emitted data.
Contributors
Thanks to everyone who contributed to this release:
0.1.8
Breaking Changes
- Avatar and AvatarGroup adopt Icon's abbreviated size scale —
sizenow takesxsm/sm/md/lg/xlinstead oftiny/xsmall/small/medium/large. Pixel values are unchanged (20/24/36/48/128px) and the default is nowmd(still 36px, formerlysmall). Avatar's tiers stay larger than Icon's because avatars align with media rather than glyphs. Runastryx upgradeto migrate call sites. (#2672)
New Features
astryx init --features agentsnow defaults to creating rootAGENTS.md— the tool-agnostic standard that Codex/Copilot, Cursor, and most agents read — instead of the Claude-specific.claude/CLAUDE.md. Claude output is now opt-in via--agent claude(→.claude/CLAUDE.md), and--agent allstill writes both. Projects with existing agent-doc files are unaffected: init still discovers and updates every file already present, so this only changes the from-scratch default. (#4216)- "Foolproof init": both
@astryxdesign/coreand@astryxdesign/clinow print a postinstall nudge pointing you tonpx @astryxdesign/cli init,astryxcommands nudge you to finish setup until init has run, andastryx initruns non-interactively (no TTY required) so it works in CI and agent environments. (#4147, #4153, #4154, #4155)
Fixes
- Stop suggesting bare
npx astryxbefore the CLI is installed — it resolves to an unrelated package on the npm registry. The CLI now emits an install-aware invocation everywhere it prints a command: - Extend the v0.1.0 upgrade codemods to cover test files that mock
@xds/coremodules, which were previously left half-migrated and broke after upgrade: astryx upgradenow keeps the managed agent-docs block (<!-- ASTRYX:START --> … <!-- ASTRYX:END -->) in sync with the installed version on every path — including the up-to-date and no-codemods short-circuits that previously returned before any refresh, leaving AI agents reading a stale component index and superseded rules. The block documents the installed library, so it's now refreshed up front (independent of codemods) and reported in the--jsonreceipt asagentDocs. One detection pass covers three cases: a stale block is rewritten (--apply) or reported as a pending change (dry-run, which no longer writes); a project with core installed but no managed block is nudged to runastryx init --features agents; an already-current block stays silent. (#4168, #4169)
Documentation
- Add a
cli-integrationsCLI docs topic (astryx docs cli-integrations) so the integration-authoring guide (originally written by @ejhammond) is discoverable through the CLI and docsite instead of an unreferenced markdown file. Rewrite the CLI README's Configuration section to match the current strict config schema (integrations,issuesUrl,hooks.postCodemod,experimental.xle) and reframe the Integrations section around the two-file API.
Other Changes
- Installed / global / dev runs suggest
<pm> astryx <cmd>(e.g.pnpm exec astryx …), unchanged. - One-off runs (launched via
npx/pnpm dlx/yarn dlx/bunx) suggest the scoped package<dlx> @astryxdesign/cli <cmd>, which always resolves to us. - migrate-xds-module-specifiers: rewrite the mocked-module path in
vi.mock/vi.doMock/jest.mock/jest.doMock(and baremock) calls, plusimport(...)specifiers used in TS type positions (typeof import('@xds/core/Text')), so the mock still intercepts the renamed@astryxdesign/*import. - drop-xds-prefix-imports: un-prefix partial-mock override keys inside an
@xds/coremock factory (e.g.useXDSTruncation→useTruncation) so the override matches the renamed export instead of silently overriding nothing. Scoped to recognized@xds/coremock factories only; unrelated object keys are untouched.
Contributors
Thanks to everyone who contributed to this release:
0.1.7
New Features
- Export the authoring factories from
@astryxdesign/core:createConfigat@astryxdesign/core/configandcreateIntegration/createPageTemplate/createBlockTemplate/createComponentDoc/createFunctionDoc/createDocat@astryxdesign/core/authoring. Authoring a config or integration no longer requires depending on the CLI. Existing@astryxdesign/cli/*imports keep working via re-export. - Add the finalized doc-authoring API to
@astryxdesign/cli/doc:createComponentDoc,createFunctionDoc(any function, including hooks), andcreateDoc(generic reference/topic docs). Each factory stamps atypediscriminant and is validated at the load boundary against a matching per-kind schema. The legacy looseexport const docs = {...}format keeps loading unchanged, and.ts-authored hook/function sources now derive their import path to a tree-shakeable subpath instead of the bare package root. - New codemod for the Table
tablePropsdeprecation: lifts object-literaltablePropskeys into direct props on<Table>, keeps colliding or dynamic values in place with a TODO note. Codemod:npx astryx upgrade --codemod migrate-table-tableprops-to-direct-props(#3679) - New docs topic
internationalizationcovering how to localize astryx components, provide translation catalogs, override default strings, coexist with existing i18n libraries (react-intl, i18next, next-intl), swap languages at runtime, and validate coverage with the shipped pseudo locale. Runnpx astryx docs internationalizationor read it at https://astryx.atmeta.com/docs/internationalization. - template: accept
.template.{ts,mjs,js}as the canonical suffix for template-spec files, alongside the legacy.doc.*suffix. Template specs exportcreateBlockTemplate/createPageTemplate— a scaffoldable template, not documentation — so they now get a descriptive name. Core, external-package, and integration discovery (findShowcase,--blocks,astryx template <id>scaffolding) all treatFoo.template.tsidentically to a legacyFoo.doc.mjs; same-stem.tsxsource resolves for either suffix, and.template.tsauthoring is loaded via jiti. Additive only — no existing files are renamed.
Fixes
- Translated component docs no longer drop props
A
docsZh/docsDenseblock that carried its ownpropsarray replaced the English component doc wholesale rather than overlaying it, so any prop the translation had not caught up with simply ceased to exist.astryx component Button --zhsilently omittedisInterruptibleandisIconOnly; ten components were affected, includingMobileNav,PopoverandStackthrough the multi-componentcomponents[]shape. - Anchor --dense / --zh doc overlays to their base sections (#2182) The compressed and translated reference docs were merged into the base doc by array position, so an overlay whose sections were ordered differently — or which omitted one — grafted every title onto the wrong body.
- template: inline full demo-image URLs in the Avatar blocks and theme-showcase page so scaffolding strips them to a clean placeholder. Templates that stored only the CDN base in a
constand appended the filename via interpolation (`${CDN}/File.png`) previously scaffolded a malformedsrc— the placeholder data URI with the filename glued onto the end — plus a deadconst CDN = 'data:…'. (#4027)
Documentation
- Document the minimal
package.json#exportsrecipe an integration needs so its block templates are importable by a bundler-resolution consumer and type-check undermoduleResolution: bundler:"./templates/*.tsx": "./templates/*.tsx"plus an extensionfulimport('@acme/widgets/templates/…/…Showcase.tsx'). Addspackages/cli/docs/integration-authoring.mdand a fixture test proving the recipe against the repo's owntscandesbuild.
Contributors
Thanks to everyone who contributed to this release:
0.1.6
No changes in this release.