Skip to content

feat(cli): experimental theme editor show <theme> --on <part> gives what one part of a theme shows - #12768

Open
josephfarina wants to merge 19 commits into
mainfrom
theme-resolved-values
Open

josephfarina wants to merge 19 commits into
mainfrom
theme-resolved-values

Conversation

@josephfarina

@josephfarina josephfarina commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What users see

astryx experimental theme editor show <theme> --on <part> answers "what does this part look like in my theme?" without reading package source. It is a lookup and writes nothing. It takes any theme the project builds: a theme made with the editor, a local theme, or an installed theme package (neutral, or an integration's theme). A slug that two packages provide is the one the app records; with none recorded, it is refused, and the suggestions add one to the app.

$ astryx experimental theme editor show neutral --on card
card in neutral (bundled theme), at rest: 5 values

padding           0.75rem - --spacing-3 - theme
background-color  light #ffffff, dark #1b1b1b - --color-background-card - theme
border-width      1px - --border-width - core
border-color      light #00000014, dark #ffffff1a - --color-border - theme
border-radius     0.75rem - --radius-container - theme

in variants: 37 values that differ, the first 4 here (--json lists every value)

variant:muted  background-color - light #f1f1f1, dark #1b1b1b - --color-background-muted - theme
...

--json (themeEdit.showPart) carries every value (79 for this card). Each value has:

  • property, when and state, written the way set takes them; a condition no flag of set reaches keeps Core's words in when and carries notSettable with why;
  • value: the final value, given per mode when the modes differ;
  • expression: the declaration that gives the value, per mode when a rule sets one mode;
  • tokens: the tokens it reads, given per mode when the modes read different ones;
  • source: whose value it is (core, base or theme), which is not a setting's source as in show's settings.

The theme docs topic gets a short section that points to the command as a step before changing a part ("see what it draws now"), the way the topic's other editor pointers are steps in making or changing a theme.

Scope

Components: CLI experimental theme editor show (new --on <part> option), themeEditShow(), ThemeEditShowOptions.on, ThemeEditShowPartResponse, ThemeEditPartValue, response type themeEdit.showPart, theme docs topic (one section)

  • One capability is added.
  • Unrelated fixes, cleanup, and policy changes were removed or split.
  • Consumer docs, focused tests, and migration evidence ship with the feature (no migration: a new option).
  • Public text and artifacts contain no internal Meta context.

Records

No record changes. The option is decided by the engineering owner's decision posted on this pull request: #12768 (comment)

How

  • The theme loads the way theme build loads it (loadThemeInput). Core resolves its tokens in each mode. The theme it extends is resolved the same way, and the answer compares the two to name the source. For an editor theme, the editor's own compile and base are used (see Not shown yet).
  • What a part reads comes from the editor's part data, which is derived from the installed Core. The values a part shows come from one function, partShows, moved out of how's measured check and now shared by both, with mergeRules and scopedTokens.
  • The theme layer comes after Core's styles. So when a rule on the part sets a property, any Core declaration that rule covers is dropped. This includes logical longhands, so padding covers padding-inline-start. A shorthand whose longhands the same rule overwrites later is dropped too, and so is a longhand that Core writes beside its own shorthand with the same value. The four logical corner radii count as the corners border-radius sets.
  • Each row's condition goes through the converter how <part> uses. A theme rule a property setting wrote is matched to that setting by the rule key the build writes for it (stateSlot), and takes the setting's own --when and --state. One condition is one row, whatever order Core writes its words in, and a condition a theme rule sets shows the rule's value, not Core's too.
  • A rule's @light or @dark block is read into that mode's value (and that mode's declaration and tokens) of the property under the rule's condition, not listed as a condition. A token such a block sets on the part goes into that mode's tokens inside the part, so the values that read it there show it. A block with no other row under its condition is a row of its own, and its other mode is taken from the same variant at rest, else the part at rest.
  • The text answer is a section with inline records (when, property, value, tokens, source), for the part at rest and for the first four variant values that differ. Rows for a custom property the part's rule sets stay in the JSON only.
  • A slug that two packages provide is read from the package the app records. With none recorded, the refusal suggests each package's theme add … --package. --on beside --png or --section, --on naming two parts, a group, an unknown part and an unknown theme are refused. A stray option beside --on is refused with no other show offered, since a show without --on writes pages.

This pull request went through many review rounds. Where an answer could not be shown right in every case, it was cut and is listed below rather than shown wrong.

Not shown yet

  • Which setting gives a value (an exact token, a dial, a rule on the part). Earlier rounds gave a via for this; it drew wrong labels three times, so it is left out. source says whose value it is.
  • The other mode of a property or token a one-mode block sets on the part with nothing else under that condition (left out of value, expression and tokens).
  • The show to run instead of a stray option beside --on (the refusal names none).
  • For an editor theme, what a person adds by hand below the settings in <theme>.theme.ts (a token, a part rule, a mode block). show --on reads the theme the editor's settings make. The help, the release note and the docs say so.

Blind agent test

An agent with no context and one shell tool answered three questions in a fresh Vite app using neutral: a card's padding, radius and colors; a primary button's colors and radius; and a medium button's height and padding. Each arm had 2 runs per question, and every answer was checked against the real values.

Arm Correct Source-read commands per run Turns Runs that used show --on
main 6/6 20.8 15.2 -
this PR 6/6 18.7 14.0 0/6
this PR + a line in component <Name> --detail full's theming section that names the command (test-only) 6/6 12.3 10.7 3/6

Agents look for theme values through component <Name> --detail full, not through the theme docs topic, so the command alone is not found. The runs that did use it took 0, 6 and 7 source reads and 6 to 9 turns. On the same questions, main took 6 to 31 reads and 14 to 19 turns. The line in the component answer is a follow-up on top of this PR.

Test plan

  • theme-show-part-values.test.mjs, 18 cases, including:
    • an editor theme's card with a corners dial and a padding setting: values, tokens, per-mode fill, no var() left, and nothing under themes/ or src/ changes;
    • the same theme read as a local theme; part-scoped and whole-theme dials; a variant's own setting and a rest setting in variant rows;
    • each row's when/state fed back to set, a CSS-selector row marked notSettable, and one row per condition;
    • --state disabled, --when variant:secondary --state expanded, --state hover --mode light and --mode light card settings beside a dial; neutral's segmented-control-item selected rule; a destructive button's dark half;
    • a token set on the card for one mode, and one for variant:muted only; two light-only outline-color settings on a link, where the text leaves the dark mode out as the JSON does;
    • a stray option and two --sections beside --on; no via in the JSON or the text;
    • the shared-slug refusal and the recorded package; one corner radius; the refusals; at most 16 text lines.
  • Each case added for a review fix failed with the code before that fix and passes now.
  • A probe over every part of neutral and of an editor theme like it (287 parts): no duplicate conditions, no mode rows, and every settable condition is taken by set (3 refused only as ERR_THEME_NO_EFFECT).
  • The experimental-isolation goldens are regenerated on current main with fresh cache, state and config folders: the new docs section and the icon set search count (one more than main).
  • The five CLI typechecks, the API type sync, structure, changeset and README checks pass; eslint and prettier are clean on the touched files.

Follow-ups (not blocking)

  • The text record's when field joins when, state and "(not settable)" in one field.
  • Mode blocks scoped to a state do not feed a token's value inside the part.
  • The fuller versions of what is not shown yet, each as its own small change: via, the cross-mode value, the suggestion that keeps --on, and hand edits in an editor theme's file.

preflight: pass 2b249b6
replay: worse 0 at 2b249b6

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 21, 2026 4:44pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 21, 2026, 4:53 PM UTC

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. Every line of the documented show neutral --on card example reproduces and the new tests pass, but these need fixing first:

  • show --on credits values that a part-scoped dial sets to Core, because _resolved.mjs:291-314 labels them from the theme's global tokens while partShows resolves them through the part's own tokens (after set <theme> spacing roomy --on card, card padding reads core token), so label each value from the same scoped token map and add a part-scoped dial to the test.
  • The text answer is one hand-indented string inside a single text block (experimental/theme.mjs:716-775), which the CLI's output rules forbid for items, so render it with section and records(..., {layout: 'inline'}) under the JSON key names and drop custom-property rows at rest as the variant rows already do.
  • The longhand dedupe misses the four logical corner radii (physical() in _resolved.mjs:51-61), so show neutral --on button prints the radius five times against the description, and a button case belongs in the test.
  • A theme slug that two packages provide cannot be looked up, because the refusal suggests show <slug> --package <pkg>, which show rejects as an unknown option, and ERR_AMBIGUOUS_THEME is missing from the command and function docs.
  • _resolved.mjs copies the rule merge from partShows (mergeComponents) and Core's default-token resolution from baseResolved (coreTokensOf) instead of calling them, so a fix to either original misses this lookup.

Smaller points: the JSON source means something different here than in show's settings, and the --on help says the text lists the variants that change something, while it lists four and counts the rest.

Claims and files checked

Review mode: full; reason: no-earlier-review

Claims:

  • The lookup of one part writes nothing: verified (the test snapshots the theme and app folders; no theme lock; it returns before any build).
  • Each property at rest and per variant, with its value per mode, declaration, tokens and who decides it: false for values a part-scoped dial sets (credited to Core).
  • It takes any theme the project builds (editor, local, installed package): verified for editor, local and bundled themes; false for a slug two packages provide.
  • The text lists the part at rest in a few lines and the JSON carries every value: verified.
  • The documented card output for neutral: verified line for line (the example leaves out three variant rows).
  • The JSON fields (property, when, state, value, expression, tokens, source, via): verified.
  • The theme docs topic gains a short section: verified in all three languages.
  • The theme loads the way theme build loads it, Core resolves tokens per mode, and the parent is compared to name the source: verified.
  • For an editor theme, its saved settings tell a dial from an exact token setting: verified for whole-theme settings; false for part-scoped dials.
  • What a part reads comes from the editor's part data: verified.
  • partShows moved out of how's measured check and is shared: verified (identical body; how's tests pass).
  • A rule on the part drops the Core declarations it covers, logical longhands included: verified.
  • A shorthand that later longhands overwrite is dropped: verified.
  • A longhand beside its own shorthand with the same value is dropped: false (the logical corner radii are kept).
  • The test plan's three test groups: verified (pass on the head).
  • The full suites on base and head, with the same failures on both: not rerun here.
  • The five CLI typechecks and the API type sync pass: four typechecks pass here; the fifth and the type sync were not rerun.
  • The structure, changeset, README, eslint and prettier checks: the README check passes here; the rest were not rerun.

Files:

  • .changeset/theme-show-part-values.md: two claims false (part-scoped dial attribution; any installed theme package).
  • packages/cli/api/theme-edit/_adapter.mjs: clear.
  • packages/cli/api/theme-edit/_edit.mjs: clear.
  • packages/cli/api/theme-edit/_how-commands.mjs: clear (the moved partShows is identical).
  • packages/cli/api/theme-edit/_resolved.mjs: part-scoped dial attribution, logical corner radii, the --package suggestion, two copied helpers.
  • packages/cli/api/theme-edit/show/show.mjs: clear.
  • packages/cli/api/theme-edit/theme-edit.type.mjs: non-blocking (source meaning).
  • packages/cli/api/theme-edit/theme-options-words-answered-color.test.mjs: clear.
  • packages/cli/api/theme-edit/theme-show-part-values.test.mjs: no part-scoped dial or button case.
  • packages/cli/api/theme-edit/themeEditShow.doc.mjs: ERR_AMBIGUOUS_THEME and the new ERR_INVALID_ARGUMENT cases are missing.
  • packages/cli/assets/docs/theme.doc.dense.mjs: clear.
  • packages/cli/assets/docs/theme.doc.mjs: clear.
  • packages/cli/assets/docs/theme.doc.zh.mjs: clear.
  • packages/cli/clients/cli/commands/experimental-theme-editor-show.doc.mjs: ERR_AMBIGUOUS_THEME is missing; the option text overstates the variant lines.
  • packages/cli/clients/cli/commands/experimental/theme.mjs: the text answer is drawn from characters.
  • packages/cli/clients/cli/commands/not-ready.test.mjs: clear.
  • packages/cli/foundation/response/response-types.doc.mjs: clear.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The rebase onto main left this patch unchanged, and the five problems from the last review still reproduce on this head; the inline notes on those lines still apply.

  • show --on credits values that a part-scoped dial sets to Core, because _resolved.mjs:291-314 labels them from the theme's global tokens while partShows resolves them through the part's own tokens (after set <theme> spacing roomy --on card, card padding reads core token), so label each value from the same scoped token map and add a part-scoped dial to the test.
  • The text answer is one hand-indented string inside a single text block (experimental/theme.mjs:716-775), which the CLI's output rules forbid for items, so render it with section and records(..., {layout: 'inline'}) under the JSON key names and drop custom-property rows at rest as the variant rows already do.
  • The longhand dedupe misses the four logical corner radii (physical() in _resolved.mjs:51-61), so show neutral --on button prints the radius five times against the description, and a button case belongs in the test.
  • A theme slug that two packages provide cannot be looked up, because the refusal suggests show <slug> --package <pkg>, which show rejects as an unknown option, and ERR_AMBIGUOUS_THEME is missing from the command and function docs.
  • _resolved.mjs copies the rule merge from partShows (mergeComponents) and Core's default-token resolution from baseResolved (coreTokensOf) instead of calling them, so a fix to either original misses this lookup.

Smaller points: the JSON source means something different here than in show's settings, the --on help says the text lists the variants that change something while it lists four and counts the rest, and (missed last time) a repeated --on is refused but not listed in the command's exit codes.

Claims and files checked

Review mode: full; reason: rebase

Claims:

  • The lookup of one part writes nothing: verified (the test snapshots the theme and app folders; no theme lock; it returns before any build).
  • Each property at rest and per variant, with its value per mode, declaration, tokens and who decides it: false for values a part-scoped dial sets (credited to Core).
  • It takes any theme the project builds (editor, local, installed package): verified for editor, local and bundled themes; false for a slug two packages provide.
  • The text lists the part at rest in a few lines and the JSON carries every value: verified.
  • The documented card output for neutral: verified line for line on this head.
  • The JSON fields (property, when, state, value, expression, tokens, source, via): verified.
  • The theme docs topic gains a short section: verified in all three languages.
  • The theme loads the way theme build loads it, Core resolves tokens per mode, and the parent is compared to name the source: verified.
  • For an editor theme, its saved settings tell a dial from an exact token setting: verified for whole-theme settings; false for part-scoped dials.
  • What a part reads comes from the editor's part data: verified.
  • partShows moved out of how's measured check and is shared: verified (identical body; how's tests pass).
  • A rule on the part drops the Core declarations it covers, logical longhands included: verified.
  • A shorthand that later longhands overwrite is dropped: verified.
  • A longhand beside its own shorthand with the same value is dropped: false (the logical corner radii are kept).
  • The blind agent test results: the author's measurement, not rerun.
  • The test plan's test groups: verified (pass on this head).
  • The full suites on base and head, with the same failures on both: not rerun.
  • The five CLI typechecks and the API type sync pass: verified on this head.
  • The structure, changeset, README, eslint and prettier checks: README, eslint and prettier verified on this head; the structure and changeset checks were not rerun.

Files:

  • .changeset/theme-show-part-values.md: two claims false (part-scoped dial attribution; any installed theme package).
  • packages/cli/api/theme-edit/_adapter.mjs: clear.
  • packages/cli/api/theme-edit/_edit.mjs: clear.
  • packages/cli/api/theme-edit/_how-commands.mjs: clear (the moved partShows is identical).
  • packages/cli/api/theme-edit/_resolved.mjs: part-scoped dial attribution, logical corner radii, the --package suggestion, two copied helpers.
  • packages/cli/api/theme-edit/show/show.mjs: clear.
  • packages/cli/api/theme-edit/theme-edit.type.mjs: non-blocking (source meaning).
  • packages/cli/api/theme-edit/theme-options-words-answered-color.test.mjs: clear.
  • packages/cli/api/theme-edit/theme-show-part-values.test.mjs: no part-scoped dial or button case.
  • packages/cli/api/theme-edit/themeEditShow.doc.mjs: ERR_AMBIGUOUS_THEME and the new ERR_INVALID_ARGUMENT cases are missing.
  • packages/cli/assets/docs/theme.doc.dense.mjs: clear.
  • packages/cli/assets/docs/theme.doc.mjs: clear.
  • packages/cli/assets/docs/theme.doc.zh.mjs: clear.
  • packages/cli/clients/cli/commands/experimental-theme-editor-show.doc.mjs: ERR_AMBIGUOUS_THEME and the repeated --on refusal are missing; the option text overstates the variant lines.
  • packages/cli/clients/cli/commands/experimental/theme.mjs: the text answer is drawn from characters.
  • packages/cli/clients/cli/commands/not-ready.test.mjs: clear.
  • packages/cli/foundation/response/response-types.doc.mjs: clear.

Automated review (maintainer link)

@josephfarina
josephfarina marked this pull request as ready for review November 19, 2026 13:22
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 262a676

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The five problems from the last review are fixed on this head (part-scoped dials, the text records, the logical corner radii, the theme add --package suggestion and the shared helpers), and the new tests pass; two things remain.

  • Miss: values that a whole-theme dial writes on a part are reported as via: part, because propertyVia (_resolved.mjs:163-172) only counts settings made with --on, so after set <theme> surfaces outlined the card's border and shadow read theme - part (and buttons outline does the same on the primary button); fall back to a whole-theme dial before part, add a surfaces outlined case to the test, and note that the last review's suggestion named only dials set with --on.
  • The new shared-slug handling in findProjectTheme (_resolved.mjs:442-468) and the ERR_AMBIGUOUS_THEME refusal that the docs now list have no test, which AST-042 FR2 requires for each documented error code, so add a case with two installed packages that provide one slug, covering both the refusal and the read of the package the app records.

Smaller point: the command doc's summary and description for theme editor show still say only that it lists settings and writes two pages, so the generated help never mentions the --on lookup.

Claims and files checked

Review mode: incremental; reason: none
changed rules (0): none

Claims:

  • The lookup of one part writes nothing and takes no theme lock: verified (the test snapshots the theme and app folders).
  • Each property at rest and per variant, with its value per mode, declaration, tokens and who decides it: verified, except that a whole-theme dial's part rules are reported as a rule on the part (false for that case).
  • It takes any theme the project builds (editor, local, installed or bundled): verified for editor, local and bundled themes.
  • A slug two packages provide is read from the package the app records, and otherwise refused with a theme add … --package suggestion that runs: verified by reading the code; not reproduced end to end, and untested.
  • The text lists the part at rest and the first four variant values that differ, with a count, and the JSON carries every value: verified.
  • The documented card output for neutral: verified line for line on this head.
  • The JSON fields, and how source differs from a setting's source: verified.
  • The theme docs topic gains a short section in all three languages, with the goldens updated: verified (the isolation test passes).
  • The theme loads the way theme build loads it, Core resolves tokens per mode, and the parent is compared to name the source: verified.
  • A dial on the part is credited to the dial, whether it writes tokens or a property, and a property setting on the part stays part: verified.
  • The text is a section with inline records, and custom-property rows stay in the JSON: verified.
  • The four logical corner radii count as the corners border-radius sets: verified (a button gives its radius once).
  • The rule merge and the tokens inside a part are one function each, shared with how, and Core's defaults come from the base resolver: verified.
  • ERR_AMBIGUOUS_THEME and the --on refusals, a repeated --on included, are in the command and function docs: verified.
  • The blind agent test results: the author's measurement, not rerun.
  • The test plan's test groups: verified (all pass on this head).
  • The full suites on base and head with the same failures on both: not rerun.
  • The CLI typechecks and the API type sync pass: verified on this head.
  • The README, eslint and prettier checks: verified on this head; the structure and changeset checks were not rerun.

Files:

  • .changeset/theme-show-part-values.md: one claim false (whole-theme dial attribution).
  • packages/cli/api/theme-edit/_adapter.mjs: clear.
  • packages/cli/api/theme-edit/_edit.mjs: clear.
  • packages/cli/api/theme-edit/_how-commands.mjs: clear.
  • packages/cli/api/theme-edit/_resolved.mjs: whole-theme dials reported as part; untested shared-slug branch.
  • packages/cli/api/theme-edit/show/show.mjs: clear.
  • packages/cli/api/theme-edit/theme-edit.type.mjs: clear.
  • packages/cli/api/theme-edit/theme-options-words-answered-color.test.mjs: clear.
  • packages/cli/api/theme-edit/theme-show-part-values.test.mjs: no whole-theme dial or shared-slug case.
  • packages/cli/api/theme-edit/themeEditShow.doc.mjs: clear.
  • packages/cli/assets/docs/theme.doc.dense.mjs: clear.
  • packages/cli/assets/docs/theme.doc.mjs: clear.
  • packages/cli/assets/docs/theme.doc.zh.mjs: clear.
  • packages/cli/clients/cli/commands/experimental-theme-editor-show.doc.mjs: non-blocking (summary and description).
  • packages/cli/clients/cli/commands/experimental/theme.mjs: clear.
  • packages/cli/clients/cli/commands/not-ready.test.mjs: clear.
  • packages/cli/foundation/response/response-types.doc.mjs: clear.
  • The six goldens under packages/cli/test/__golden__/no-icon-set/: clear.

Automated review (maintainer link)

@josephfarina

Copy link
Copy Markdown
Contributor Author

Owner decision (engineering owner, covering this pull request at its current head): the experimental theme editor gains show <theme> --on <part>, a read-only lookup that reports what one part looks like in any theme and writes nothing, with the themeEdit.showPart answer and its types. A theme slug that two packages provide is read from the app's recorded package. The theme docs gain a section for it. It stays under experimental, within the editor's spec:AST-050 scope.

josephfarina added a commit that referenced this pull request Nov 19, 2026
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 4101537

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: two findings from the previous review are still open at this head, which rebases the branch onto main and rewords one exit-code line.

  • propertyVia in packages/cli/api/theme-edit/_resolved.mjs (lines 163-172) returns via: "part" for values a whole-theme dial writes on the part: after set <theme> surfaces outlined, show <theme> --on card reports the card's border-style, border-width, border-color and box-shadow as theme - part, so fall back to the whole-theme dial before "part" and add a surfaces outlined case to the test.
  • ERR_AMBIGUOUS_THEME and the recorded-package read in findProjectTheme (_resolved.mjs lines 442-468) are documented for options.on but no test drives them, which the CLI admission spec requires for each documented error code, so add a two-package fixture test for the refusal and for the recorded-package read.

Also, the show command's summary and description still describe only the settings listing and the two HTML pages, so name the --on lookup there (non-blocking).

Claims and files checked

Review mode: full; reason: rebase

  • Claim: the lookup reports one part's values and writes nothing: verified (the new test compares the theme and app folders before and after; no theme lock is taken).
  • Claim: each property at rest and in each variant, with its value per mode, declaration and tokens: verified (the new tests; a run of the card in neutral gives 5 values at rest, 37 differing variant values and 79 in the JSON).
  • Claim: the answer says who decides each value, through a token, a dial or a rule on the part: false for whole-theme dials (first finding).
  • Claim: editor, local, bundled and installed-package themes are read, and a shared slug reads the package the app records: verified for editor, local and bundled themes by tests; the recorded-package read is correct by reading but untested (second finding).
  • Claim: the text gives the part at rest and the first four differing variant values, and the JSON carries every value: verified (test and run).
  • Claim: the description's example output for a card in neutral: verified line for line.
  • Claim: each value carries property, when, state, value, expression, tokens, source and via: verified (type doc and JSON).
  • Claim: the theme docs topic gains a short section pointing at the command: verified in all three locales.
  • Claim: no knowledge record changes: verified.
  • Claim: themes load the way the theme build loads them, with the editor's own compile and base for editor themes: verified by reading.
  • Claim: one part resolver, now shared with the how command's measured check: verified (the how suites pass).
  • Claim: a rule on the part drops the Core declarations it covers, logical longhands included, and overwritten shorthands and duplicate longhands are dropped: verified by reading and the padding test.
  • Claim: a dial set on the part is credited to the dial and a property set on the part stays part: verified by tests.
  • Claim: the text uses inline records under the JSON key names and leaves custom-property rows to the JSON: verified by reading.
  • Claim: the four logical corner radii count once: verified by the button test.
  • Claim: the shared-slug refusal suggests a runnable theme add with a package, and the error codes and refusals are documented: verified by reading.
  • Claim: the rule merge and the part's tokens are one shared function each, and Core's defaults come from the base resolver: verified by reading.
  • Claim: the help and type doc wording, and the updated goldens: verified (the experimental isolation test passes).
  • Claim: the blind agent test results: not checkable from the code.
  • Claim: the test plan's suites and typechecks pass: verified for the new suite and six related suites (150 tests); the strict CLI typecheck reports no error in a changed file, and its two errors come from a theme package this run did not build; the wider runs were not repeated.
  • File: .changeset/theme-show-part-values.md: its claim about dials is false for whole-theme dials (first finding).
  • File: packages/cli/api/theme-edit/_resolved.mjs: first and second findings.
  • File: packages/cli/api/theme-edit/theme-show-part-values.test.mjs: lacks the whole-theme dial and shared-slug cases (both findings).
  • File: packages/cli/clients/cli/commands/experimental-theme-editor-show.doc.mjs: non-blocking summary and description note.
  • File: packages/cli/api/theme-edit/_adapter.mjs, _edit.mjs, _how-commands.mjs, show/show.mjs, theme-edit.type.mjs, themeEditShow.doc.mjs, theme-options-words-answered-color.test.mjs: clear.
  • File: packages/cli/assets/docs/theme.doc.mjs, theme.doc.dense.mjs, theme.doc.zh.mjs: clear.
  • File: packages/cli/clients/cli/commands/experimental/theme.mjs, not-ready.test.mjs, packages/cli/foundation/response/response-types.doc.mjs: clear.
  • File: the six goldens under packages/cli/test/__golden__/no-icon-set/: clear.

Automated review (maintainer link)

josephfarina added a commit that referenced this pull request Nov 19, 2026
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 139f902

@josephfarina

Copy link
Copy Markdown
Contributor Author

Owner decision (engineering owner, covering this pull request at its current head): the experimental theme editor gains show <theme> --on <part>, a read-only lookup that reports what one part looks like in any theme and writes nothing, with the themeEdit.showPart answer and its types. A theme slug that two packages provide is read from the app's recorded package. The theme docs gain a section for it. It stays under experimental, within the editor's spec:AST-050 scope.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet.

Both findings from the previous review are fixed. Values that a whole-theme dial writes on a part now read via: dial, and the new test fails without the fix. The shared-slug refusal and the recorded-package read now have tests. No new problems were found in this push.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim: the lookup reports one part's values and writes nothing: verified (the test compares the theme and app folders before and after; no theme lock is taken with --on).
  • Claim: each property at rest and in each variant, with its value per mode, its declaration and its tokens: verified (tests).
  • Claim: the answer says who decides each value, through a token, a dial or a rule on the part: verified, whole-theme dials included (the new test fails on the previous revision and passes here; buttons outline on a primary button also reads dial).
  • Claim: editor, local, bundled and installed-package themes are read, and a slug two packages provide reads the package the app records, else is refused with a theme add … --package for each package: verified (tests).
  • Claim: the text gives the part at rest and the first four differing variant values, and the JSON carries every value: verified (test and run).
  • Claim: the description's example output for a card in neutral: verified line for line (5 values at rest, 37 differing variant values, 79 in the JSON).
  • Claim: each value carries property, when, state, value, expression, tokens, source and via, and source is not a setting's source: verified (type doc and JSON).
  • Claim: the theme docs topic gains a short section that points to the command: verified in all three locales.
  • Claim: no knowledge record changes, and an engineering owner's decision on the pull request governs the option: verified.
  • Claim: themes load the way the theme build loads them, with the editor's own compile and base for editor themes: verified by reading.
  • Claim: one part resolver, one rule merge and one scoped-token function, shared with the how command's measured check, and Core's defaults from the base resolver: verified by reading and the how suites.
  • Claim: a rule on the part drops the Core declarations it covers, logical longhands included, and overwritten shorthands and duplicate longhands are dropped: verified by reading and the padding test.
  • Claim: dials on the part, and whole-theme dials that write part rules, read dial, while a property setting on the part reads part: verified (tests and a run beside a whole-theme dial).
  • Claim: the text uses inline records under the JSON key names and leaves custom-property rows to the JSON: verified by reading.
  • Claim: the four logical corner radii count once: verified (button test).
  • Claim: the error codes and refusals are in the command and function docs, and the help wording and the show summary and description name the lookup: verified by reading.
  • Claim: the docs-topic and search goldens are updated for the new section: verified (the experimental isolation suite passes).
  • Claim: the blind agent test results: not checkable from the code.
  • Claim: the test plan's suites, typechecks and lint pass: verified for the new suite and five related suites (125 tests). The strict CLI typecheck reports no error in a changed file. eslint is clean on the changed files, and prettier flags only response-types doc lines that the base already had. The full 431-file run was not repeated.
  • File: .changeset/theme-show-part-values.md: clear.
  • File: packages/cli/api/theme-edit/_resolved.mjs: clear (whole-theme dials now read dial).
  • File: packages/cli/api/theme-edit/theme-show-part-values.test.mjs: clear (adds the whole-theme dial and shared-slug cases).
  • File: packages/cli/api/theme-edit/themeEditShow.doc.mjs, packages/cli/clients/cli/commands/experimental-theme-editor-show.doc.mjs: clear (the summary and description name the lookup).
  • File: packages/cli/api/theme-edit/_adapter.mjs, _edit.mjs, _how-commands.mjs, show/show.mjs, theme-edit.type.mjs, theme-options-words-answered-color.test.mjs: clear.
  • File: packages/cli/assets/docs/theme.doc.mjs, theme.doc.dense.mjs, theme.doc.zh.mjs: clear.
  • File: packages/cli/clients/cli/commands/experimental/theme.mjs, not-ready.test.mjs, packages/cli/foundation/response/response-types.doc.mjs: clear.
  • File: the six goldens under packages/cli/test/__golden__/no-icon-set/: clear.

Automated review (maintainer link)

josephfarina and others added 15 commits November 21, 2026 01:35
…one corner radius, and picks the app's theme for a shared slug

[skip ci]
… and reads a rule's mode block as that mode's value
… its own, per-mode declarations and tokens, and reads bare-state theme keys
…own variant, and the response doc names notSettable
… and reads an editor theme from its theme file
…he token, and loads the theme file through the editor's loader
@josephfarina josephfarina changed the title feat(cli): experimental theme editor show <theme> --on <part> gives what one part of any theme shows feat(cli): experimental theme editor show <theme> --on <part> gives what one part of a theme shows Nov 21, 2026
@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 21, 2026

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the show --on lookup holds up and its tests pass, but three of its answers mislead the reader and need fixing first.

  • Miss: a mistyped option beside --on (show --theme neutral --on card, or show neutral --on card --zz) is answered with a suggestion that drops --on (theme.mjs:1622, :1635), so following it is refused for a bundled or package theme and runs the full page-writing show for an editor theme.
  • Miss: propertyVia (_resolved.mjs:307-315) labels any rule that no setting on the part wrote as via: dial whenever the theme has a dial, so the header fill that background-color --on app-shell writes reads dial beside an unrelated corners pill and part without it.
  • A token set on the part for one mode (--color-background-card '#abcdef' --on card --mode light) reads null with an empty expression in the other mode (_resolved.mjs:715-749), although the part draws the theme's own value there, which also makes the description's claim about the other mode false for a token.

The description lists the first two as follow-ups, but callers meet them as soon as the option ships, so they belong in this change. Each fix is local to one place, and a test beside the existing cases would pin it.

Claims and files checked

Review mode: same-head; reason: none

  • Claim, the release note: one part's values as a lookup that writes nothing, for any theme the project builds, the part at rest and the first variant values in text and every value in --json, an editor theme read from its saved settings: verified (the before-and-after snapshot test, no theme lock with --on, a test per theme kind, the text and --json test).
  • Claim, the lookup tells what one part shows and writes nothing: verified.
  • Claim, it reads editor, local, installed package and bundled themes: verified by a test for each kind.
  • Claim, a slug two packages provide reads the app's recorded package, else is refused with a theme add … --package per package: verified by two tests.
  • Claim, the documented show neutral --on card output: verified line for line on the head.
  • Claim, --json rows carry property, when, state, notSettable, value, expression, tokens, source and via: verified by the type and the tests.
  • Claim, the theme docs topic gains a step before changing a part, in three languages: verified.
  • Claim, one capability with docs and tests, no unrelated work and no internal context: verified.
  • Claim, no record changes: verified.
  • Claim, the theme loads as theme build loads it, the resolver is shared with how, and covered or overwritten declarations are dropped: verified in the code and tests.
  • Claim, the review-round behaviors (part-scoped and whole-theme dials, text records, one corner radius, the ambiguous slug, variant and state settings, set-ready conditions, mode blocks, variant-scoped token blocks, the destructive dark half): verified by their test cases, 15 of 15 passing.
  • Claim, a rule a whole-theme dial writes on a part reads dial: verified; the description's own follow-up says rules no setting wrote read dial too, which is the second finding.
  • Claim, the other mode of a one-mode block row shows what the part shows without the block: false for a token block (third finding).
  • Claim, the release note, help and docs say an editor theme is read from its saved settings: verified.
  • Claim, the branch is on current main with regenerated goldens: the goldens match the head; main has moved on since, and the head still merges into it cleanly.
  • Claim, typechecks pass: verified for the four CLI typechecks.
  • Claim, the follow-ups are known limits: the first two are the first two findings; the other two are disclosed and not promised by the docs.
  • Claim, the blind agent test, the earlier-round suite runs and the preflight and replay lines: the author's measurements, not re-run and not relied on.
  • Files, _resolved.mjs: second and third findings; experimental/theme.mjs: first finding.
  • Files, the changeset, _adapter.mjs, _edit.mjs, _how-commands.mjs, show/show.mjs, theme-edit.type.mjs, themeEditShow.doc.mjs, the command doc, response-types.doc.mjs, the three theme docs, the three test files and the six goldens: clear.

Automated review (maintainer link)

…show, reads a whole-theme dial's part rule as the part's, and leaves out a mode it does not show yet
…e part's, and offers no show beside --on for two --section
@josephfarina
josephfarina marked this pull request as draft November 21, 2026 14:04

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the three answers flagged in the last review are fixed, each with a test that fails without the fix, but one text answer still disagrees with the JSON.

  • When a part has two one-mode settings of one property in the same mode and Core draws no rest row for it (outline-color light-only on link at rest and again with --state hover), the hover row prints dark no value in the text (experimental/theme.mjs:749) while --json leaves that mode out, because _resolved.mjs:665 takes the missing mode as undefined and pair keeps it as a key (:677); leave an undefined mode out (in pair, or with v[m] !== undefined in valueText) and add the link case beside the one-mode token test.

The fix is local, and the rest of the lookup holds up: 17 of 17 lookup tests pass, and a sweep over every part of neutral and of an editor theme found no duplicate condition, no var() left in a value and no refusal.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim, the release note: a lookup that writes nothing, giving every property the part reads at rest and per variant with its value per mode, its declaration, its tokens and whose value it is: verified (the before-and-after snapshot test, no theme lock with --on, the type and the tests).
  • Claim, it takes an editor, local or installed theme, and a slug two packages provide is the one the app records: verified by a test for each.
  • Claim, the text gives the part at rest and the first variant values that differ, and --json every value: verified; the documented show neutral --on card output matches line for line, with 79 values in the JSON.
  • Claim, an editor theme is read from its saved settings and hand additions are not shown yet: verified in the loader, the help, the release note and the docs.
  • Claim, each JSON value carries property, when, state, notSettable, value, expression, tokens and source, and no via: verified by the type, a test and the output.
  • Claim, the theme docs topic gains a step before changing a part, in three languages: verified.
  • Claim, one capability with docs and tests, no unrelated changes and no internal context: verified; the response-types doc also reflows two other entries onto one line each, with the same text.
  • Claim, no record changes: verified.
  • Claim, the theme loads as theme build loads it, the resolver is shared with how, and covered or overwritten declarations and the logical corners are dropped: verified in the code and tests.
  • Claim, each row's condition goes back to set as written, one row per condition, and mode blocks read as mode values: verified by tests and the sweep (no duplicate condition, no mode row).
  • Claim, a one-mode block with nothing else under its condition leaves its other mode out: verified for the first block; false in the text for a second block of the same property and mode (the finding).
  • Claim, the refusals for --png or --section beside --on, two parts, a group, an unknown part or theme, and a stray option with no other show offered: verified by tests and runs.
  • Claim, 17 cases, and each case added for a review fix failed before that fix: verified 17 of 17; the four cases added since the last review fail on the code before them.
  • Claim, the goldens are regenerated: verified, they match the head.
  • Claim, the typechecks pass: verified for three CLI typechecks; the strict one stops here only on unbuilt theme output imported by two unchanged templates.
  • Claim, the blind agent test, the earlier part sweep's count and the preflight line: the author's measurements, not re-run.
  • Claim, the not-shown-yet list and the follow-ups: disclosed, and they match the code.
  • Files, _resolved.mjs and experimental/theme.mjs: the finding.
  • Files, the changeset, _adapter.mjs, _edit.mjs, _how-commands.mjs, show/show.mjs, theme-edit.type.mjs, themeEditShow.doc.mjs, the command doc, response-types.doc.mjs, the three theme docs, the three test files and the six goldens: clear.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet.

The one finding of the last review is fixed: the text answer now leaves out a mode the --json answer leaves out, so two light-only outline-color settings on link read light #00ff00 in both, and a new test pins it. The heavy CI jobs run once this review passes, and they must pass before merge.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim, the release note: a lookup that writes nothing, giving each property the part reads at rest and per variant with its value per mode, its declaration, its tokens and who decides it, with the setting behind it not shown yet: verified (the before-and-after snapshot test, no theme lock with --on, the type and the tests).
  • Claim, it takes an editor, local or installed theme, and a slug two packages provide is the one the app records, else it is refused with a theme add … --package suggestion for each: verified by a test for each.
  • Claim, the text gives the part at rest and the first variant values that differ, and --json every value: verified; the documented show neutral --on card output matches line for line (5 values at rest, 37 variant values that differ, the first four shown), with 79 values in the JSON.
  • Claim, an editor theme is read from its saved settings and hand additions are not shown yet: verified in the loader, the help, the release note and the docs.
  • Claim, each JSON value carries property, when and state as set takes them, notSettable where no flag reaches, value, expression, tokens and source, per mode only where the modes differ: verified by the type, the tests and the output.
  • Claim, the theme docs topic gains a step before changing a part, in three languages: verified.
  • Claim, one capability with docs and tests, no unrelated changes and no internal context: verified; the response-types doc also reflows two other entries onto one line each, with the same text.
  • Claim, no record changes, and an engineering owner's decision on the pull request covers the option: verified.
  • Claim, the theme loads as theme build loads it, the resolver is shared with how, and covered or overwritten declarations and the logical corners are dropped: verified in the code and the tests; every how suite passes with this head merged into the current base.
  • Claim, each row's condition goes back to set as written, one row per condition, mode blocks read as mode values, and a one-mode block with nothing else under its condition leaves its other mode out: verified by the tests and a sweep over every part of neutral and of an editor theme (no duplicate condition, no mode row, no unknown mode kept).
  • Claim, the text leaves out a mode where the JSON leaves it out, for two light-only settings on a link: verified; the new test fails without the fix.
  • Claim, the refusals for --png or --section beside --on, two parts, a group, an unknown part or theme, and a stray option with no other show offered: verified by the tests and runs.
  • Claim, 18 cases, and each case added for a review fix failed before that fix: verified 18 of 18; the case added since the last review fails on the code before it.
  • Claim, the goldens are regenerated: verified; they pass at this head and with this head merged into the current base.
  • Claim, the typechecks, structure, changeset and README checks pass, and lint and formatting are clean: verified for three CLI typechecks, structure, changeset, README, eslint and prettier; the strict typecheck stops only on unbuilt theme output imported by two unchanged templates; the API type sync was not re-run.
  • Claim, the blind agent test, the author's part probe and the preflight line: the author's measurements; the probe's no-duplicate and no-mode-row results hold over 292 parts here, and the rest was not re-run.
  • Claim, the not-shown-yet list and the follow-ups: disclosed, and they match the code.
  • Files, _resolved.mjs, experimental/theme.mjs and theme-show-part-values.test.mjs: the fix and its test, clear.
  • Files, the changeset, _adapter.mjs, _edit.mjs, _how-commands.mjs, show/show.mjs, theme-edit.type.mjs, themeEditShow.doc.mjs, the command doc, response-types.doc.mjs, the three theme docs, the other two test files and the six goldens: clear.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — 2b249b64 Deployed Nov 21, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants