[cixzhang]

Exact decision needed

What astryx swizzle promises about the copy it writes. Today a product team that swizzles a component to own its source gets a copy that often does not build: the copy imports Core helpers Core does not export. No current record says the copy must build, keep theme targets, or behave like the package component.

This PR adds spec:AST-110 (Swizzle output) only. Core approved the record on 2026-10-31. It stays draft until its co-owner, the CLI owner, agrees. A draft does not govern, so the spec:AST-080 FR5 and FR7 swizzle cases and the architecture:cli-surface pointer land in the same pull request that makes AST-110 current; the record's Known gaps say so.

Existing authority searched

• architecture:cli-surface INV28: what swizzle --list reports. Says nothing about the copy's contents.
• spec:AST-035 FR11–FR12: which component an unqualified or Core-scoped swizzle <Name> copies.
• spec:AST-081 FR3: swizzle refuses to run outside a project.
• spec:AST-080 FR7: product rules stay outside astryx-base, which puts a swizzled copy above the theme layer. Its swizzle exception lands when AST-110 becomes current.
• @astryxdesign/build: it sorts modules into its library pass (astryx-base) or product pass by path (node_modules/@astryxdesign/), so a copy in the product tree lands in the product layer.
• spec:AST-017 FR21: modules without a public contract stay internal; ./internal/* is limited to Core and Lab.
• architecture:public-component-api INV12 (anything reachable is public) and INV23 (each private data attribute has one owner module).
• architecture:layer-runtime: the layer stack, modal outlet, and layer contexts that FR3 keeps single.
• spec:AST-030 FR11 and FR14: one test lane per surface; allowlisted triggers.
• Searched docs/** and the CLI's command docs for swizzle, eject, and copy. The command doc only says imports that escape the component folder are rewritten.
• Overlapping open work: fix(cli): swizzle recursively copies nested component subdirectories #5101 (copy nested component subfolders) implements part of FR2; fix(cli): swizzle finds gh on PATH instead of running gh auth status #8626 (gh lookup) affects how fast the copy runs. Neither decides what the copy promises.

Decision

• FR1, builds on its own: with the same Core version and a StyleX compiler, the copy type-checks and bundles with no edits. It imports only paths its owner package exports, never ./internal/*. Swizzle reports the owner package's npm dependencies the copy imports (with their declared ranges); the copy builds once the product installs them.
• FR2, helpers come with it: non-public modules the component reaches are copied with it and imported by relative path. Nested folders come too. Tests, stories, specs and docs stay behind. If an earlier swizzle already wrote a helper, an identical file is reused. A different file is never overwritten (not even with --overwrite): the new one is written alongside under a version-suffixed name, and only the new copy's imports point at it.
• FR3, shared runtime state stays single: coordinating state (layer stack, modal outlet, interaction modality, bottom-sheet stack, and the one announcement channel per document of spec:AST-086 FR9) and the contexts that connect providers to consumers live under registered, versioned keys. A copy and the package on the same version share them, so stacking, Escape and focus return work as one, a copied useToast reaches the package's LayerProvider, and identity symbols (brands, context keys) agree between copy and package. It holds in both directions: package components inside a copied Dialog deliver announcements inside that modal (spec:AST-086 FR14), and package group context stops at the copy's layer boundary (spec:AST-038 FR7). A copy on another version keeps its own store and never reads a different shape.
• FR4: each private data attribute's owner module (INV23) that the component imports is copied whole, so callers, the copy included, still never write the attribute by hand.
• FR5: theme targets, documented classes, data attributes and custom properties are unchanged. Swizzle marks its output directory with an astryx-swizzle.json file (owner package and version). @astryxdesign/build compiles modules under a marked directory in its library pass into astryx-base, below astryx-theme, so a theme's component overrides still apply. This holds for products on @astryxdesign/build. The stock StyleX plugins have no library-pass setting, so on them a copy's rules land above astryx-theme; the record lists that as a known gap.
• FR6: keyboard, focus, roles, names, states, announcements and events match the package until the product edits the copy.
• FR7: before a change to component source or the swizzle copy merges, every component swizzle can copy (Core's --list per spec:AST-035 FR12, plus each integration package's components through --package) is ejected, type-checked, bundled with StyleX, and server-rendered, and a failure blocks the merge. Release checks add a real-browser render.

CI impact of FR7, shaped with the CI and release owners: one step in the existing required test job, selected by the shared change-scope classification, with results in the single PR report. It uses standard runners and adds about +3 job-minutes on pull requests that change component source or swizzle code (≈ +2–3% of pull-request runner time). It adds no wall-clock time to green and no new runs or checks. These numbers are estimates until the first real run measures them.

Rejected alternatives

• Export the helpers copies need: anything reachable from a package path becomes public API (INV12), so internals would turn into permanent API to make a copy build.
• Never copy stateful modules; import a contained package instance instead. That needs a public runtime entry with a compatibility promise only copies need, and it leaves a copy on another version without the state it needs. Core already keeps modality and the bottom-sheet stack in versioned per-document stores so duplicate bundles share state; FR3 makes that the rule.
• Run the proof in the CLI smoke workflow: that workflow is not a required check, so a failure could not block, and it is already close to its time budget.

Claim scope and non-goals

The record governs only what a swizzled copy contains and promises, and the proof that keeps it true. It leaves out:

• which component a name copies;
• where the command runs;
• how a product compiles StyleX;
• keeping an edited copy in step with later Core releases;
• making internal helpers public.

Evidence and implementation relationship

• Published 0.7.5 was built for real, covering all 112 names swizzle --list offers: 12 build and render, 89 fail to build, 9 build but render wrong, and 2 build with nothing to render.
• Causes:
  • The import rewrite collapses ../X/file to the public @astryxdesign/core/X entry, which lacks internal helpers (87 components).
  • Deep StyleX modules are missing from the exports map (12).
  • Copied styles land in the app's cascade layer above the theme's, so theme component overrides stop applying (9 today, 38 once imports resolve). FR5 now states the cascade rule.
  • Spec records and tests get copied (104), and nested folders are left out.
  • --list offers 6 folders that are not components.
• On main, a full ledger of 154 components (Core, Lab, Charts, RichText, Vega) finds:
  • 32 pass every check, 96 don't bundle, 17 lose theme component overrides, and 1 behaves differently (Escape doesn't close a copied Lab MobilePowerSearch).
  • Copying every helper Core doesn't export raises passes to 48. What remains:
    • copied shared-state modules (a second live region; focus misses the combobox in a copied CommandPalette);
    • the cascade layer;
    • Core's private type additions and a unique-symbol identity split;
    • 16 copies that need the owner package's npm dependencies (d3, vega-util).
  • FR1, FR3 and FR5 cover each of these.
• Running 112 separate CLI processes took 654 s locally, almost all of it start-up, so the proof copies in-process.
• Response and file changes:
  • swizzle.copy lists each helper as written, reused or versioned, and each npm dependency with its range.
  • 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.
• No implementation is in this PR. The CLI owner implements the copy changes (FR1, FR2, FR4, FR7). Core implements FR3's stores and contexts. The build package reads the FR5 marker, and the styling overview documents where a copy's rules land with and without it.

Writing rubric results

• R1 narration: none found. Intent, requirements, current-state impact and known gaps are in the present tense.
• R2 research in the record: one finding, fixed. Ledger counts and CI estimates moved out of the record into this description; Known gaps keeps the causes only.
• R3 evidence naming a change: none. Verification cells name checks and states.
• R4 rejected alternatives over one line or outside a decision: two, in DEC-1 and DEC-2, one line each.
• R5 pull request or issue references remaining: none in the record.
• R6 ruled open questions still listing options: none. The record has no open questions; DEC-1 and DEC-2 carry Core's approval.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Validation

• pnpm check:knowledge: Knowledge templates and records are aligned.
• Prettier: AST-110 clean.
• git diff --check: clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Error		Oct 31, 2026 9:57pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Oct 31, 2026, 10:01 PM UTC

[github-actions]

PR Analysis Report

Current run: The current change has no visual or preview-producing scope. Visual checks are not applicable; preview links are not shown.

---

_{Generated by PR Enrichment workflow | View current CI run}

[cixzhang]

/approve-spec 3268411

[astracat-bot]

The swizzle output contract is clear and an engineering owner has approved its direction, but it needs a few fixes before it lands. Please reconcile the records it conflicts with and close the gaps below; the review has the evidence for each.

• FR5 puts a copy's styles in the package component's cascade layer, while spec:AST-080 FR7 says product rules stay outside astryx-base; amend AST-080 in this pull request or reword FR5.
• FR4 cites architecture:public-component-api INV23, which is not on main; define the private-attribute owner module here or hold FR4 until that claim lands.
• Add architecture:layer-runtime to the impact for FR3, list the Toast case (a copied useToast never sees the package LayerProvider), and say in FR2 what happens when a helper another copy already wrote exists.
• Cite spec:AST-035 FR12 instead of restating the swizzle --list rule in FR7, move the 0.7.5 counts and CI estimates to the description, and record the approval in the front matter before merge.

[Automated review]

[astracat-bot]

This puts a copy's styles in astryx-base, while spec:AST-080 FR7 says "Product rules stay outside astryx-base" and its Non-goals leave how a product compiles an ejected component to the product. Please amend AST-080 in this pull request or reword FR5 so the two records agree.

[astracat-bot]

architecture:public-component-api has no INV23 on main (its invariants end at INV22), so FR4 depends on a claim that does not exist yet. Define the private-attribute owner module here, or hold FR4 until INV23 lands.

[astracat-bot]

The spec content is approved at this head; please record it here (authority, approved_by, approved_at, phase) and in DEC-2's Decider before merge, so architecture:cli-surface never points at a draft.

[astracat-bot]

FR3 changes how Layer/layerStack.ts and Layer/modalOutlet.ts keep state, which architecture:layer-runtime owns; please list it here and in Current-state impact, and consider adding those modules to the path block.

[astracat-bot]

With helpers kept beside the component, two copies that reach the same private helper (for example Layer/layerScopedContext, imported by Dialog, Drawer, Lightbox, MobileNav and many context modules) collide: the second swizzle hits ERR_FILE_EXISTS, or --overwrite replaces an edited helper. Please say what an existing helper does.

[astracat-bot]

spec:AST-035 FR12 already says swizzle --list lists Core's components, and this record's Non-goals hand the list to it; please cite FR12 in Known gaps instead of restating the rule here.

[astracat-bot]

These are estimates from measurement, which architecture:knowledge-contracts INV10 keeps out of records; the R2 rubric line also says CI measurements stay out. Please move them to the description.

[cixzhang]

/approve-spec cb7b410

[cixzhang]

/approve-spec 0851db0

[astracat-bot]

The swizzle output contract has an engineering owner's approval, but the records need a few changes before they merge.

• Name the setup or swizzle output that puts a copy's rules in astryx-base (AST-110 FR5 and the amended AST-080 FR7): the documented StyleX path and @astryxdesign/build both put product code above astryx-theme. List the styling overview, plus the build package if it changes, as affected.
• Move AST-110 to authority: current with the approval, or hold the cli-surface pointer and the AST-080 exception until it is current, since a draft record does not govern.
• List the --overwrite, existing-file and swizzle.copy response changes from FR1 and FR2 in Current-state impact.
• Add the time and context failure to the FR7 verification row, and say which proof covers the integration packages the FR1 row names. Cite AST-035 FR12 and public-component-api INV23 where the record restates them.

[Automated review]

[astracat-bot]

Nothing in this record or AST-080 says what puts a copy's rules in astryx-base. The styling overview has products compile swizzled components with a stock StyleX plugin, and @astryxdesign/build puts product code in a product layer above astryx-theme with the x prefix. Please name the setup or swizzle output that places them (and with which class prefix), and list the styling overview, plus the build package if it changes, under Current-state impact and affects_consumer_docs.

[astracat-bot]

This hands the copy contract to spec:AST-110, which stays authority: draft, and a draft is "useful for review, but not a rule" (architecture:knowledge-contracts). Please move AST-110 to current with the approval (DEC-14 keeps it through that edit), or land this pointer and the AST-080 FR7 exception once it is current.

[astracat-bot]

FR2 changes what --overwrite and an existing file do. The command doc says --overwrite replaces existing files, and that without it they fail with ERR_FILE_EXISTS. FR1 also adds a dependency report that the swizzle.copy response type lacks. Please list those command-doc and response changes here.

[astracat-bot]

FR7 also promises no added required context and no added wall-clock time, but this row has no failure for either. Please add one.

[astracat-bot]

FR7 no longer says the list holds only component folders; spec:AST-035 FR12 owns that, so cite FR12 here.

[cixzhang]

/approve-spec 8294fdb

[astracat-bot]

The swizzle output record is clear about what a copy must do, but approval waits on an engineering owner's decision on this revision's content: FR1–FR7 and DEC-1–DEC-2 are new requirements in a draft record, and FR5 relies on the deferred exception to AST-080 FR7 ("Product rules stay outside astryx-base"). An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Three record fixes are needed either way:

• FR5 asks products without the build package to add the copy to a "library pass" that the documented stock StyleX plugins do not have, so name that setting or limit FR5's cascade placement to the build package (and list AST-080 FR5 beside the deferred exception if the plain path stays).
• FR7 promises no added wall-clock time to the slowest required check, but its verification row only fails past the 15-minute job budget.
• Current-state impact credits FR7 with listing only component folders, which AST-035 FR12 owns, and the Non-goal hands StyleX compilation to AST-080, whose own Non-goals disclaim it.

[Automated review]

[astracat-bot]

The styling overview's StyleX path uses stock plugins pointed at the app's own source; they compile in one pass with one class prefix and emit no astryx-base layer, so these products have no "library pass" to add the copy to. Please name the exact setting per documented plugin, or limit this placement to @astryxdesign/build and list the plain StyleX path under Platform support.

[astracat-bot]

FR7 promises "no wall-clock time to a pull request's slowest required check", but this row only fails past the 15-minute job budget. Please fail when the proof lengthens the slowest required check, or reword FR7 to the budget.

[astracat-bot]

FR7 no longer says anything about which folders the list holds; spec:AST-035 FR12 owns swizzle --list, as this record's Non-goals say. Please cite FR12 here.

[astracat-bot]

AST-080's Non-goals disclaim "How a product compiles its own code, including any StyleX settings it uses…", so this pointer names an owner that declines the topic. Please drop it or point at the owner that states it.

[cixzhang]

/approve-spec 285f61c

[astracat-bot]

An engineering owner has approved this revision and the earlier gaps are fixed, but one change remains before merge. A copied Dialog copies hooks/useAnnounce.ts and its live regions, which breaks spec:AST-086 FR9's single announcement channel per document. FR3's Known gaps, Current-state impact and Verification row never name that channel, so the swizzle proof would pass a second live region. Please name it in those three places and re-approve the new head; when AST-110 moves to current, amend spec:AST-080 FR5 and FR7 in that same pull request, as Known gaps already say.

[Automated review]

[astracat-bot]

A copied Dialog also copies hooks/useAnnounce.ts, because ModalAnnounceProvider imports its private ModalAnnounceContext and modalAnnounce reaches announceMessage. The copy brings its own live-region singleton, so the document gets a second polite/assertive pair, against spec:AST-086 FR9. Please list the announcement channel here, in Current-state impact, and as a state in FR3's Verification row.

[cixzhang]

/approve-spec 70b633b

[astracat-bot]

The swizzle output record has an engineering owner's approval at this revision and the announcement-channel gap is fixed, but one change remains before merge. FR3's Verification row and Known gaps only test a copy under a package provider, while the usual composition is the reverse: package components inside a copied Dialog or overlay, where a copy today loses what the package gives them under spec:AST-086 FR14 (a package picker's messages go to the page channel the modal hides) and spec:AST-038 FR7 (package group context crosses the copy's layer boundary). Please add those states to the FR3 row, make its failure cover either direction, name that direction in Known gaps, and re-approve the new head.

[Automated review]

[astracat-bot]

This row only tests a copy under a package provider ("a copied consumer misses the package provider"), and the new state puts the package component beside the copied Dialog. The usual composition is a package component inside a copy: today a package Selector inside a copied Dialog reads the package ModalAnnounceContext, gets null, and announces on the page channel the modal hides, where a package Dialog delivers it inside (spec:AST-086 FR14); and the copy's LayerContentBoundary does not reset package group contexts, which a package overlay stops (spec:AST-038 FR7). Please add those states and make the failure cover either direction.

[astracat-bot]

This gap names only a copy missing the package's provider. Please also name the reverse: package components inside a copied Dialog or overlay miss the copy's announcement route and layer boundary.

[cixzhang]

/approve-spec c984b8e

[astracat-bot]

The swizzle output record has an engineering owner's approval at this revision, and FR3 now holds in both directions, so package components inside a copied Dialog or overlay keep in-modal announcements (spec:AST-086 FR14) and the layer boundary (spec:AST-038 FR7). Nothing else blocks merging. One optional cleanup: the Non-goal for where the command runs cites spec:AST-081 FR3, but swizzle's refusal outside a project is in FR4, so "FR3–FR4" would be exact.

[Automated review]

[astracat-bot]

Optional: spec:AST-081 FR3 says swizzle must not read the carried Core, but the refusal outside a project ("swizzle is refuse, even with a carried Core.") is in FR4, so FR3–FR4 would cite both.