What's New

Release notes and changelog for all packages.

0.2.0

Breaking Changes
  • cli/json: remove the central CLIAnyResponse, CLIResponseType, and CLIResponseDataMap types. jsonOut is now a structural serializer and parseResponse / assertResponse return the structural CLIResponse ({type, data, meta?}) instead of the discriminated union, so result.data is unknown until you narrow it yourself. Runtime output is unchanged (every --json envelope is byte-identical). This only affects consumers importing those types or relying on parseResponse / assertResponse to auto-narrow .data.
  • component/hook --json list responses collapsed. --detail compact/full previously emitted distinct component.brief/component.full (and hook.*) envelopes; they now all emit component.list (resp. hook.list) with a data.detail: 'names' | 'compact' | 'full' field. Migrate: switch on data.detail, not the .brief/.full discriminator. Removed types: ComponentBriefResponse, ComponentFullResponse, HookBriefResponse, HookFullResponse.
New Features
  • CLI: blog is now a normal, agent-facing command — it appears in --help and the capability manifest and supports --json (emitting blog.list / blog.detail envelopes), instead of being hidden. Human output is unchanged; the reader still consumes the public RSS feed. Also scriptable through the ./api barrel as blog(slug?).
  • CLI: init is now fully scriptable through the ./api barrel — the non-interactive installer (agent-docs cheat sheet, starter template, --remove-agents) lives in api/init and 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 scripted init() stays silent while the CLI output is byte-identical for existing usage.
  • CLI: theme build is now fully scriptable through the ./api barrel — the ~1,000-line theme compiler (defineTheme extraction, CSS generation via @astryxdesign/core/theme, variant/type-declaration + icon-module generation, override validation) lives in api/theme/build and returns a typed theme.build receipt, with the CLI reduced to a thin parse → API call → render wrapper. Human progress is emitted through an injectable logger, so a scripted themeBuild() stays silent while the generated CSS/JS/.d.ts, the --json envelope, and human output stay byte-identical for existing usage. Watch mode remains a thin CLI loop.
  • CLI: upgrade is now fully scriptable through the ./api barrel — the version-to-version pipeline (codemods + agent-docs refresh) lives in api/upgrade and 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 scripted upgrade() stays silent while the CLI output and --json envelopes are unchanged for existing usage.
  • Timestamp: new tooltipEntries prop renders the hover tooltip across several time zones and/or formats at once — one line per entry, each with an optional timezoneID (IANA id; omit it or pass 'local' for the viewer's zone), format (every non-relative TimestampFormat plus 'full'), and label. 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 corrects isTimezoneShown's documentation, which claimed it applied to the system_date_time and system_time formats; 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-textinput instead 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.mjs owns all network fetch + feed parsing), with blog.mjs kept as a dispatcher+barrel so the same blog export, the CLI wrapper, api/index.mjs, and the --json/human output stay byte-identical.
  • CLI: build reorganized into the api/build leaf shape — build.mjs is 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: the build export, the ./api barrel, and the CLI consumer are unchanged, and the --json and human output stay byte-identical for existing usage.
  • CLI: component reorganized into the api/component leaf shape over a shared _adapter resolver — component.mjs is 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 --json envelope 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 — --json and 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() in api/docs/docs.mjs is 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 in api/docs/_adapter.mjs. Pure reorganization: the docs export, api/index.mjs, the CLI consumer, and all --json and human output are unchanged (byte-identical).
  • CLI: hook reorganized into api/hook leaf shape — hook.mjs is 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.mjs resolver. Pure reorg: --json and human output are byte-identical across all modes, and the hook export surface (api/index.mjs + CLI) is unchanged.
  • CLI: init reorganized into api/init leaf shape — init.mjs is now a dispatcher + barrel that routes to api/init/run/run.mjs (the default / --features / --all install path) and api/init/remove/remove.mjs (the --remove-agents path), with the shared plain-logger contract in api/init/_adapter.mjs. Pure reorg: getNextSteps, noopInitLogger, and the InitOptions / InitLogger types stay re-exported from the barrel, so api/index.mjs, the CLI command, and the programmatic API are unchanged. Human and --json output are byte-identical.
  • CLI: layout reorganized into the api/layout leaf shape — a shared _adapter.mjs (analyze/loadBlocks/formatIssue over lib/xle) with thin expand/, check/, and grammar/ leaves, plus a layout.mjs barrel. api/index.mjs and the CLI are unchanged (they import via the barrel). Pure reorg: layout expand/check/grammar --json envelopes and human output are byte-identical.
  • CLI: swizzle reorganized into api/swizzle leaf shape — the flat command splits into api/swizzle/list (swizzle.list) and api/swizzle/copy (swizzle.copy receipt, incl. rewriteImports), with shared @astryxdesign/core discovery + component listing deduped in api/swizzle/_adapter.mjs, and swizzle.mjs reduced to a dispatcher + barrel that keeps its existing exports (swizzle, rewriteImports). Pure reorganization with no behavior change: human output and every --json envelope stay byte-identical, and the CLI command, the ./api barrel, and the central types/swizzle declarations are untouched.
  • CLI: template reorganized into api/template leaf shape (shared helpers preserved on the barrel). Pure reorg — --json and human output stay byte-identical: shared discovery/IO moved to api/template/_adapter.mjs, the command modes split into list/show/skeleton/copy leaves, and template.mjs becomes 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 resolving api/template/template.mjs unchanged.
  • CLI: theme add/list are reorganized into the fractal api/theme/ leaf shape — a shared _adapter.mjs (bundled-theme manifest reader + slug resolver) with thin add/ (copy → theme.add receipt) and list/ (theme.list) leaves over it, plus a theme.mjs barrel, mirroring the theme build extraction (#4462). themeList() is now exported from @astryxdesign/cli/api alongside themeAdd. Pure reorg: theme list/add --json envelopes 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), and list/status/run leaves (upgrade.list | upgrade.status | upgrade.run). Pure reorg: the ./api barrel + CLI consumer are unchanged, and both the human output and --json envelopes 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, and validate commands — each is now scriptable through the ./api barrel with the CLI as a thin parse → API call → render wrapper. build gains --json output. Behavior is unchanged for existing command usage. (#4302)
Fixes
  • Align two --json contract shapes with what the CLI actually emits
  • Register all emitted response types in the --json envelope union Three response types were defined, exported, and emitted by commands but never added to CLIAnyResponse — the union that jsonOut() type-checks payloads against: component.full, component.detail.blocks, and upgrade.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.help had no response type at all. Added a BuildHelpResponse type and wired all four into the union so every --json envelope the CLI can emit is now type-checked against a declared shape.
  • Type detectPackageManager honestly so astryx doctor's "no lockfile" branch is reachable
    detectPackageManager returns 'npx' as the sentinel for "nothing detected", but its return type only listed 'yarn' | 'pnpm' | 'bun' | 'npm'. Type-checkers therefore treated doctor's pm !== '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 now PackageManager | 'npx' and detection narrows via a shared type predicate, so the guard is honest and the branch is preserved.
  • Make the CLI's .mjs sources fully strict-typecheckable (checkJs + JSDoc) Annotated the entire CLI package so tsconfig.strict.json (full strict checkJs over src, bin, scripts, docs, and the emitted templates) reports zero errors — down from 1717. Fixes are JSDoc-only: no runtime logic changed, .mjs stays .mjs. Strict checking also surfaced and corrected several type-contract drifts: the upgrade.run response type (declared a depsUpdated field the command never emits, and omitted the real integrations/filesChanged/transformsApplied/errors), registered the emitted theme.list/theme.add/layout.* response types in the --json envelope union, and added category? to ReferenceSection in core's docs types (reference docs already emit it).
  • Drop the dead cwd parameter from getLatestVersion checkForUpdate called getLatestVersion(cwd) and the JSDoc advertised a cwd parameter, but the function takes no arguments — it only reads the $ASTRYX_LATEST_VERSION env var, so the passed cwd was 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.copy payloads always include package and usesStyleX (both covered by tests), but SwizzleCopyResponse.data didn't declare them — the call site cast the payload to Record<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 suggestions shape 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 canonical Suggestion type (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 — size now takes xsm/sm/md/lg/xl instead of tiny/xsmall/small/medium/large. Pixel values are unchanged (20/24/36/48/128px) and the default is now md (still 36px, formerly small). Avatar's tiers stay larger than Icon's because avatars align with media rather than glyphs. Run astryx upgrade to migrate call sites. (#2672)
New Features
  • astryx init --features agents now defaults to creating root AGENTS.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 all still 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/core and @astryxdesign/cli now print a postinstall nudge pointing you to npx @astryxdesign/cli init, astryx commands nudge you to finish setup until init has run, and astryx init runs non-interactively (no TTY required) so it works in CI and agent environments. (#4147, #4153, #4154, #4155)
Fixes
  • Stop suggesting bare npx astryx before 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/core modules, which were previously left half-migrated and broke after upgrade:
  • astryx upgrade now 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 --json receipt as agentDocs. 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 run astryx init --features agents; an already-current block stays silent. (#4168, #4169)
Documentation
  • Add a cli-integrations CLI 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 bare mock) calls, plus import(...) 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/core mock factory (e.g. useXDSTruncation → useTruncation) so the override matches the renamed export instead of silently overriding nothing. Scoped to recognized @xds/core mock 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: createConfig at @astryxdesign/core/config and createIntegration/createPageTemplate/createBlockTemplate/createComponentDoc/createFunctionDoc/createDoc at @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), and createDoc (generic reference/topic docs). Each factory stamps a type discriminant and is validated at the load boundary against a matching per-kind schema. The legacy loose export 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 tableProps deprecation: lifts object-literal tableProps keys 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 internationalization covering 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. Run npx astryx docs internationalization or 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 export createBlockTemplate/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 treat Foo.template.ts identically to a legacy Foo.doc.mjs; same-stem .tsx source resolves for either suffix, and .template.ts authoring is loaded via jiti. Additive only — no existing files are renamed.
Fixes
  • Translated component docs no longer drop props A docsZh / docsDense block that carried its own props array 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 --zh silently omitted isInterruptible and isIconOnly; ten components were affected, including MobileNav, Popover and Stack through the multi-component components[] 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 const and appended the filename via interpolation ( `${CDN}/File.png` ) previously scaffolded a malformed src — the placeholder data URI with the filename glued onto the end — plus a dead const CDN = 'data:…'. (#4027)
Documentation
  • Document the minimal package.json#exports recipe an integration needs so its block templates are importable by a bundler-resolution consumer and type-check under moduleResolution: bundler: "./templates/*.tsx": "./templates/*.tsx" plus an extensionful import('@acme/widgets/templates/…/…Showcase.tsx'). Adds packages/cli/docs/integration-authoring.md and a fixture test proving the recipe against the repo's own tsc and esbuild.
Contributors
Thanks to everyone who contributed to this release:

0.1.6

No changes in this release.