Skip to content

test(ui): re-pin the transcript rhythm contract in one file - #3437

Closed
Astro-Han wants to merge 1 commit into
mainfrom
test/markdown-rhythm-contract-guard
Closed

test(ui): re-pin the transcript rhythm contract in one file#3437
Astro-Han wants to merge 1 commit into
mainfrom
test/markdown-rhythm-contract-guard

Conversation

@Astro-Han

Copy link
Copy Markdown
Contributor

Summary

packages/ui/src/styles.css told readers that the "compact == transcript" assumption was held by packages/ui/src/__tests__/markdown-rhythm-dom-contract.test.tsx. That file was deleted in #2462 and its stylesheet-side sibling (apps/desktop/src/main/__tests__/markdown-rhythm-contract.test.ts) in #2425, so the comment has been citing a guard that does not exist — the worst state to leave an assumption in, because the next person reads the citation and stops looking.

This restores the two assertions the comment is actually about, plus the ladder order #2348 exists to protect, in one file. Split across two they each stayed green against the half they could not see, which is how the stylesheet half got deleted without anything noticing.

Pinned:

  • the ladder is declared on the --space-* scale in strictly increasing order — retuning a rung is a design call and stays green; list gaps meeting block gaps fails
  • every rung declared is actually spent by a rule, so the ladder cannot become decoration while literals do the spacing
  • the runtime hooks the selectors need are really emitted by MarkdownBody (data-maka-contract, data-density, astryx-markdown-heading, data-level, astryx-list-item). These names have a single upstream owner in Astryx and appear in Maka only inside selectors, so a rename kills every rule at once with nothing failing
  • compact markdown still has exactly one caller — the bet the comment names: the table carries heading TYPOGRAPHY on a density key, which Astryx's own RFC (RFC: Density System — Theme-level + Nestable Density Provider facebook/astryx#839) says density must not do

Deliberately not pinned, because they are how the table is written rather than what it promises: the adjacent-sibling gap form, the hr rung, the ListItem padding reset, and the two heading size tiers. The comment now says so, so the next reader does not have to open the test to find out.

Why this is not what #2425 / #2462 retired

Those PRs removed markup/copy pins, duplicate presentation assertions, and CSS-structure suites that asserted how a rule was written. Nothing here asserts an appearance or a rule's shape: three of the four assertions are relations that must survive any retune, and the fourth renders the real component and checks the join between Astryx's output and Maka's selectors.

The stylesheet-reading half does not revive the deleted css-test-helpers module or the renderer-wide CSS aggregate it read — it reads packages/ui/src/styles.css directly, in the package that owns it.

Refs #2348, #2425, #2462

Verification

Seven mutations, each verified to fail the assertion that describes it and pass again on restore:

mutation caught by
invert the ladder (--md-gap-list: var(--space-4)) ladder order
take a rung off the grid (--md-gap-block: 8px) ladder order
hardcode a rung's usage (margin-block-start: 16px) rung is spent
hardcode it while naming the rung in a comment rung is spent (comments are stripped first)
rename data-maka-contract="markdown" DOM hooks
cut density off before it reaches Astryx DOM hooks
add a second density="compact" caller transcript-only surface

Also run: npm --workspace @maka/ui run build + the new file under node --test (4/4 pass), npm --workspace @maka/ui run typecheck, npm run lint, npm run format:check. Not run: the full repository suite, left to CI.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code — read the deleted suites out of git history, chose which assertions to restore and which to drop, wrote the test and the comment correction, and ran the mutation sweep above. The scope call (restore the invariants, leave the rule-shape assertions out) was reviewed by the human contributor.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

styles.css told readers the "compact == transcript" assumption was held by
`__tests__/markdown-rhythm-dom-contract.test.tsx`. That file was deleted in
#2462 and its stylesheet-side sibling in #2425, so the comment has been
claiming a guard that does not exist — the worst state to leave an
assumption in, since the next person reads the citation and stops looking.

Restore the two assertions the comment is actually about, plus the ladder
order #2348 exists to protect, in ONE file. Split across two they each
stayed green against the half they could not see, which is how the
stylesheet half got deleted without anything noticing:

- the ladder is declared on the --space-* scale in strictly increasing
  order (retuning a rung is a design call and stays green; list gaps
  meeting block gaps fails)
- every rung declared is actually spent by a rule, so the ladder cannot
  become decoration while literals do the spacing
- the runtime hooks the selectors need are really emitted by MarkdownBody
  — data-maka-contract, data-density, astryx-markdown-heading, data-level,
  astryx-list-item. These names have a single upstream owner in Astryx and
  appear in Maka only inside selectors, so a rename kills every rule at
  once with nothing failing
- compact markdown still has exactly one caller, which is the bet the
  comment names: the table carries heading TYPOGRAPHY on a density key,
  and Astryx's own RFC says density must not do that

Why these are not what #2425/#2462 retired. Those PRs removed markup/copy
pins, duplicate presentation assertions and CSS-structure suites that
asserted how a rule was written. Nothing here asserts an appearance or a
rule's shape: three of the four are relations that must survive any
retune, and the fourth renders the real component and checks the join
between Astryx's output and Maka's selectors. Deliberately left unpinned,
because they ARE how the table is written: the adjacent-sibling gap form,
the `hr` rung, the ListItem padding reset, and the two heading size tiers.

The stylesheet-reading half no longer revives the deleted desktop
css-test-helpers module or the renderer-wide CSS aggregate it read; it
reads packages/ui/src/styles.css directly, in the package that owns it.

Seven mutations, each verified to fail the assertion that describes it:
inverting the ladder; taking a rung off the --space-* grid; hardcoding a
rung's usage; hardcoding it while naming the rung in a comment (this is
why comments are stripped first); renaming the contract wrapper; cutting
density off before it reaches Astryx; and adding a second compact caller.

Also state in the comment what the contract does and does not hold, so
the next reader does not have to open the test to find out.

Generated-by: Claude Code
@Astro-Han

Copy link
Copy Markdown
Contributor Author

Folded into #3436 — the retune and the guard that makes it reviewable ship as one intent, per review feedback. Branch deleted; the commit is preserved verbatim there.

@Astro-Han Astro-Han closed this Aug 21, 2026
@Astro-Han
Astro-Han deleted the test/markdown-rhythm-contract-guard branch August 21, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant