An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-110): a swizzled component builds on its own and behaves like the package (#9190)
Cindy Zhang7cf597944cda
diff --git a/docs/specs/AST-110-swizzle-output/spec.md b/docs/specs/AST-110-swizzle-output/spec.mdnew file mode 100644index 0000000000..86b5cf077c--- /dev/null+++ b/docs/specs/AST-110-swizzle-output/spec.md@@ -0,0 +1,256 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-110+authority: draft+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-31+phase: accepted+owners: [cixzhang, josephfarina]+affects_architecture: [architecture:cli-surface, architecture:layer-runtime]+affects_families: []+affects_contributing: []+affects_consumer_docs: [cli, styling-overview]+---++# Swizzle output system spec++<!-- path-applicability:v1 -->++```json+{+ "paths": [+ "packages/cli/api/swizzle/**",+ "packages/cli/clients/cli/commands/swizzle*"+ ]+}+```++<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->++## Intent++A product team runs `astryx swizzle <Name>` to own a component's source. The+copy builds in their app with no edits, answers to the same theme targets and+class names, and behaves like the package component it came from until they+change it. Core and the CLI keep that true for every component swizzle offers,+and the repository proves it before a change that could break it merges.++## Non-goals++- Which component a name copies and what `swizzle --list` reports:+ `spec:AST-035` FR11–FR12 and `architecture:cli-surface` INV28.+- Where the command runs: `spec:AST-081` FR3.+- How a product configures StyleX for its own code: the build package's+ options and the product's StyleX configuration own that.+- Keeping a copy the product has edited in step with later Core releases.+- Making Core's internal helpers public API (`spec:AST-017` FR21,+ `architecture:public-component-api` INV12).+- Equivalent internal implementations remain valid when they satisfy this+ contract.+- Internal modules, files, function names, algorithms, data structures, storage+ layouts, manifests, journals, locks, transaction protocols, and CI job/workflow+ topology belong in architecture or implementation unless callers or+ interoperating systems intentionally depend on that exact mechanism as a public+ protocol. In that case, state who depends on it and why an equivalent+ implementation would not satisfy the contract.++## Requirements++- **FR1 — An ejected component builds on its own.** In a project with the same+ Core version and a StyleX compiler, the output of+ `astryx swizzle <Name>` type-checks and bundles with no edits. It imports from+ its owner package only paths that package's `exports` lists, and never a+ `./internal/*` path. The npm packages the copied files import are the owner+ package's own dependencies; swizzle reports each one with the version range the+ owner package declares, and the copy builds once the product installs them.+- **FR2 — The helpers it needs come with it.** Every module the component+ reaches that is not reachable through a public export is copied into the+ output, keeping its folder layout relative to the component, and copied files+ import each other by relative path. A symbol the owner package exports publicly+ is imported from that public path. Nested folders the component imports are+ copied with it. The output holds only source the component runs: tests,+ stories, spec records, and component docs are not copied. When a helper the+ copy needs already exists in the output from an earlier swizzle, an identical+ file is reused; a different file is never overwritten, even with+ `--overwrite`, which replaces only the component's own files: the new helper+ is written alongside under a version-suffixed name, and only the new copy's+ imports point at it.+- **FR3 — Shared runtime state stays single.** A module whose state coordinates+ components with each other (the layer stack, the modal outlet, interaction+ modality, the bottom-sheet stack, the announcement channel of `spec:AST-086`+ FR9) keeps that state in one store per document, under a registered key that+ carries the store's protocol version. A copy and the package component on the+ same protocol version use the same store, so stacking, Escape, focus return,+ modality, and announcements behave as they do with the package+ alone. A copy on another protocol version keeps a store of its own and never+ reads a store of a different shape. A context that connects a provider to its+ consumers is coordinating state too: its context object lives under the same+ kind of versioned key, so a copied `useToast` reaches the package's+ `LayerProvider`. A symbol that identifies objects across modules, such as a+ brand or a context key, is registered under the same kind of key, so a copy+ and the package agree on it. The rule holds in both directions: a copy inside+ a package overlay, and package components inside a copied Dialog or other+ overlay. A package component inside an open copied modal delivers its+ announcements inside that modal (`spec:AST-086` FR14), and package group and+ layout context stops at the copy's layer boundary as it does at a package one+ (`spec:AST-038` FR7). A module whose state only caches work may be duplicated+ by a copy.+- **FR4 — Private attributes stay contained.** Each private data attribute's+ owner module (`architecture:public-component-api` INV23) that the component+ imports is copied whole and unedited, so callers, the copy included, still+ never write the attribute by hand.+- **FR5 — Theme targets and class names are unchanged.** The copy answers to the+ same theme targets and emits the same documented class names, data attributes,+ and custom properties as the package component of that version, so a theme,+ `xstyle`, and product CSS reach it the same way. Swizzle marks its output+ directory as Astryx source with an `astryx-swizzle.json` file that names the+ owner package and its version. `@astryxdesign/build` compiles every module+ under a marked directory in its library pass, with the library class prefix,+ into `astryx-base` below `astryx-theme`, so a theme's component overrides+ apply to the copy as they do to the package component. This placement holds+ for products that build with `@astryxdesign/build`. The marker is a protocol+ between the swizzle copy and the build package; a path rule alone cannot+ tell a copy from the product's own code.+- **FR6 — Behavior matches the package.** Until the product edits it, the copy's+ keyboard handling, focus, roles, names, states, announcements, and events match+ the package component of the same version.+- **FR7 — Every offered component is proven before merge.** Before a change to+ a component package's source or to the swizzle copy merges, every component+ swizzle can copy is ejected into a clean+ project, type-checked, bundled with a StyleX compiler, and rendered once on the+ server; a failure blocks the merge through a required check. Release checks run+ the same proof for every component and also render each copy in a real+ browser. The proof adds no required context and no wall-clock time to a pull+ request's slowest required check.+ Every component swizzle can copy means Core's components as `swizzle --list`+ offers them (`spec:AST-035` FR12) and every component of each integration+ package in the repository, copied with `--package`.++### Platform support++- Supported feature/engine floor: the product uses the same Core version the+ copy came from and a StyleX compiler; FR5's cascade placement needs+ `@astryxdesign/build`. Browser support is Core's.+- Unsupported behavior: a project without a StyleX compiler fails at import, as+ the command's output states. On the stock StyleX plugins a copy builds and+ behaves as FR1 and FR6 state, but its rules land in the product's layer, above+ `astryx-theme`. A copy kept across a Core upgrade is outside FR1 and FR6.+- Browser evidence: a real-browser render of every copy at release time (FR7);+ server rendering is the pull-request smoke evidence.++## Current-state impact++- The CLI's swizzle copy follows the component's module graph (FR1–FR2, FR4),+ and writes no test, story, spec, or doc file. The CLI owner implements and+ owns these changes.+- The FR7 proof joins the repository's existing required test lane+ (`spec:AST-030` FR11), selected by the shared change-scope classification and+ reported in the single pull-request report, with the full proof at release+ time.+- `architecture:layer-runtime`: the layer stack, the modal outlet, and the+ layer contexts (`LayerProvider` and its consumers, such as `useToast`) keep+ their state and context objects under versioned keys (FR3, DEC-2).+- `useAnnounce` keeps the announcement channel of `spec:AST-086` FR9 under a+ versioned key, so a copied Dialog joins the package's announcer instead of+ mounting a second pair of live regions (FR3, DEC-2).+- The `swizzle.copy` result lists each helper with whether it was written,+ reused, or written under a version-suffixed name (FR2), and each npm+ dependency the copy imports with the owner package's declared range (FR1).+ An existing component file still fails with `ERR_FILE_EXISTS` unless+ `--overwrite` is passed; an existing helper never fails the command and is+ never replaced, with or without `--overwrite` (FR2).+- `@astryxdesign/build`'s Vite, PostCSS, Babel, and Next integrations compile+ modules under an `astryx-swizzle.json` directory in the library pass (FR5).+- The styling overview states that a copy's rules land in `astryx-base` with+ `@astryxdesign/build`, and above `astryx-theme` with the stock StyleX plugins+ (FR5).+- The `swizzle` command doc states FR1 and FR6 for product teams.++### Known gaps++- The copy sends `../X/file` imports to the public `X` entry, which lacks the+ internal helpers, and deep StyleX modules are missing from Core's exports+ (FR1, FR2).+- Copied styles land in the app's cascade layer above the theme's, so theme+ component overrides stop applying (FR5).+- Copies include spec records and test files and leave out nested folders+ (FR2), and `swizzle --list` offers folders that are not components+ (`spec:AST-035` FR12).+- The layer stack, the modal outlet, the layer contexts, and `useAnnounce`+ keep module state, so a copied Dialog, BottomSheet, or `useToast` starts its+ own stack, misses the package's provider, or mounts a second pair of live+ regions, breaking `spec:AST-086` FR9's one channel per document (FR3).+- In the reverse direction, package components inside a copied Dialog or+ overlay do not see its layer boundary or modal: a package picker announces+ outside the copied modal (`spec:AST-086` FR14), and package group context+ crosses into it (`spec:AST-038` FR7) (FR3).+- Core's private type additions, such as `focusVisible`, do not travel with a+ copy, and a unique symbol splits identity between a copied and a package+ AppShell (FR1, FR3).+- Copies of components that import npm packages, such as d3 and vega-util, do+ not build until the product installs them, and swizzle does not name them+ (FR1).+- Some names `swizzle --list` offers differ from their folder's export names+ (Chat, NavMenu, Indicator, Resizable) (`spec:AST-035` FR12).+- No private data-attribute owner module exists yet (FR4).+- Products on the stock StyleX plugins have no library-pass setting, so a+ copy's rules land above `astryx-theme` there and theme component overrides do+ not reach it (FR5).+- `spec:AST-080` FR5 presents the stock StyleX path as the default for ejected+ components, and its FR7 keeps every product rule, a copy's included, outside+ `astryx-base`. The pull request that makes this record current amends both+ with their swizzle case (FR5) and adds the `architecture:cli-surface` pointer+ to this record.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Eject every offered component into a clean project; type-check and bundle | Every component in `swizzle --list`; Core, Lab, Charts, RichText, Vega; a component that imports an npm dependency | A type or resolve error, or an import of a path the owner's `exports` lacks or of `./internal/*`, fails, or a dependency the copy imports goes unreported |+| FR2 | Import graph of each output | Helpers in `utils`, `hooks`, `Layer`; nested folders; colocated tests and docs; a helper an earlier swizzle wrote, identical and different | A copied file imports a module that is neither in the output nor a public export, or a test, story, spec, or doc is copied, or an existing helper is overwritten |+| FR3 | Render a copied and a package layer component together; inspect stores; open, stack, and Escape | Dialog over package Popover; BottomSheet over package Dialog; modality; a copied `useToast` under the package `LayerProvider`; a symbol-branded object passed between copy and package; a copied Dialog announcing beside a package component; a package picker inside a copied Dialog announcing a result count; a package grouped control inside a copied overlay | In either direction (copy under package, package under copy): two stores of one protocol version exist in a document, Escape and focus return differ from the package alone, a copied consumer misses the package provider, a brand check fails, a second live region appears instead of one announcer (`spec:AST-086` FR9), an announcement escapes the open modal (`spec:AST-086` FR14), or group context crosses the layer boundary (`spec:AST-038` FR7) |+| FR4 | Scan each output for private data-attribute names and selectors; compare copied owner modules with the package's | Components that reach an owner module | A hand-written private attribute name or selector, or an edited owner module, in the output |+| FR5 | Render package and copy side by side under a theme with component overrides; compare | Default; each variant; a theme component override; a copy built by `@astryxdesign/build` | A theme override, documented class name, data attribute, or theme target reaches one and not the other |+| FR6 | The component's own interaction and accessibility checks run against the copy | Keyboard, pointer, screen-reader tree | A check that passes on the package fails on the copy |+| FR7 | The required test lane's swizzle proof and the release-time proof; both cover Core's list and every integration package's components through `--package` | A change to component source; a change to the swizzle copy; an unrelated change; Core, Lab, Charts, RichText, Vega | An offered component missing from the proof, a failure that does not block, a new required context, the proof adding wall-clock time to the slowest required check, or the proof pushing its job past the pull-request time budget |++Known verification gap: none of these checks exist on `main`.++## Decision log++### DEC-1 — Swizzle copies what a component needs and imports what is public++**Reference:** `spec:AST-110/DEC-1`+**Decider:** `cixzhang`, `2026-10-31`++A copy that builds is the whole value of swizzle, and the helpers a component+reaches are internal by `spec:AST-017` FR21. The copy therefore carries those+helpers with it and imports only public paths, so no internal helper becomes+public API to make a copy build.++Rejected: exporting the helpers copies need, because anything reachable from a+package path is public (`architecture:public-component-api` INV12).++### DEC-2 — Shared runtime state lives in versioned document stores++**Reference:** `spec:AST-110/DEC-2`+**Decider:** `cixzhang`, `2026-10-31`++A copy is a second bundle of the same modules. Core already keeps interaction+modality and the bottom-sheet stack in a per-document store under a registered,+versioned key so that duplicate bundles share one state; FR3 applies that rule+to every coordinating module, so copying a module never splits a stack and no+new public entry is needed.++Rejected: never copying stateful modules and importing a contained package+instance instead, because it needs a public runtime entry with a compatibility+promise only copies need, and leaves a copy on another version without the+state it needs.++## Open questions++- None.