dsh-generative-ui 0.0.2 → 0.0.4

package/src/skill.ts

@@ -14,6 +14,10 @@ import { CANVAS_DIR, CANVAS_SUFFIX, CAPABILITY_PREFIX, FENCE_LANG, capabilityMod
 
 /** The checker, from pkg.pr.new: @genui/cli is a private workspace package and not on npm. */
 const CLI_URL = "https://pkg.pr.new/MindLab-Research/macaron-genui-demo/@genui/cli@main";
+// How to run `@genui/cli` straight from that URL. One constant because the two places that print a
+// command must not drift apart, and because each runner needs something different from the others —
+// see the paragraph under "Check it before you hand it over", where all three are spelled out.
+const RUN_CLI = `BUN_INSTALL_CACHE_DIR="$TMPDIR/bun-cache" bunx --yes genui@${CLI_URL}`;
 
 export const SKILL_NAME = "generative-ui";
 
@@ -67,7 +71,7 @@ export function mapNotes(typesMap: string | undefined, standaloneMap: string | u
     `${check} \`build\` and \`dev\` want runnable JS, so they take a different one:`,
     "",
     "```",
-    `npm_config_cache="$TMPDIR/npm-cache" npx --yes ${CLI_URL} build <file> -i ${standaloneMap}`,
+    `${RUN_CLI} build <file> -i ${standaloneMap}`,
     "```",
     "",
     `That second map stubs \`${CAPABILITY_PREFIX}/*\` — the exported page has no dsh around it, so those calls log to`,
@@ -111,11 +115,89 @@ They are not two sizes of the same thing; they have different lifetimes.
 
 **Canvas** (\`${CANVAS_DIR}/<id>${CANVAS_SUFFIX}\`) is *a place the user comes back to*. It stays in the panel across turns, keeps state, and can hold several views. Use it when the thing has substance — a tool, a dashboard, an editor, anything with more than one screen or worth reopening tomorrow.
 
-The tell is the question "would the user want this again in ten turns?" Yes → canvas. No → inline. When it is genuinely borderline, inline is the cheaper mistake: it is one message, not a file the user now owns.
+**The tell is not "would this be useful to keep".** That question is about the content, it answers
+yes for anything reference-shaped, and it is how a changelog, a cron explanation and a definition of
+closures all became files. Ask instead: **did they ask for a durable thing?** A canvas is a file in
+their workspace that they now own and have to close — creating one is an action taken on their
+behalf, and it needs their say-so:
+
+- They named a lasting artifact — "make me a dashboard", "a page I can share", "save this as", "a
+  tool for…", "画板", "报告" — or asked to keep or come back to something. → **canvas**
+- They asked a question, even a large one whose answer is long and well-organised. → **inline**,
+  every time. "What changed in 2.1.251" is a question; 71 items of answer does not make it a file.
+- The thing genuinely has more than one screen, or holds state the next turn needs. → **canvas**,
+  and say in one line that you opened it.
+
+Measured: on \`cron-read\` — *"\`*/17 3-5 * * 2\` 这个 cron 到底几点跑？"*, a lookup with one right
+answer — models opened a canvas **5 times in one round and 6 in the next**, and one opened a canvas
+for *"什么是闭包？"*. Nobody asked for a file in any of them.
+
+When it is genuinely borderline, inline is the cheaper mistake: it is one message, not a file the
+user now owns.
 
 Two things follow from the lifetime difference:
 
-- An **inline** block that the user acts on — picks an option, submits a choice — should *end that step*: send the result with \`sendMessage\` **and** record what was chosen, so the card still shows it when scrolled back to weeks later. Both halves matter: skip the send and the click goes nowhere, skip the record and the card resets to untouched. A form that looks untouched after submitting reads as broken.
+- An **inline** block that the user acts on should *end that step* — see the next entry for WHICH control ends it, because on a card whose options need previewing it is not the one they pick with. Whichever it is, that control does two things: send the result with \`sendMessage\` **and** record what was chosen in \`usePersistedState\`, so the card still shows it when scrolled back to weeks later.
+
+  **The second half is the one that gets dropped, and it fails in two different ways.** Measured over the 105 turns where a reader actually submitted something: **36 (34%) left the card looking exactly as it had before the click**, and another **20 (19%) showed the choice and then lost it on reload** — 53% between them, and evenly spread across every model, so it is the rule and not a habit. The first is forgetting to record at all (\`sendMessage\` treated as the finish line); the second is recording into \`useState\`, which a reload throws away. Both read to the reader as a form that did not take their answer.
+
+  So the submit handler has three statements, not one:
+
+      const [answer, setAnswer] = usePersistedState<string | null>("<this card>-answer", null)
+      …
+      onClick={() => { setAnswer(pick); sendMessage(…) }}        // record, then send
+      …
+      {answer !== null && <p className="text-muted">已选择：{label(answer)}</p>}   // and SHOW it
+
+  The third line is the one nobody writes — but not for the reason it first looked like. Of the
+  cards that call \`usePersistedState\`, **91 of 93 do render the value somewhere**; what they render
+  it as is \`aria-pressed\` on the button that was clicked. Reading the turns where a submit left the
+  card unchanged: **31 of 42 mark the choice with a highlight and say nothing in words**, and 19 of
+  those 42 hold it in \`useState\`, so the highlight is gone after a reload. A highlight is a fine
+  way to show which control is active while the reader is still there; it is not an answer to
+  someone coming back to this card next week, who sees one button shaded and no statement of what
+  was decided. Say it in words AND keep it in \`usePersistedState\`. (Re-firing on reload is the opposite mistake and does not happen — 0 of 105 — so
+  guard the send with the recorded answer, not with anything cleverer.)
+- **Exactly one control ends the step, and the reader must be able to find it.** This is the
+  single largest hole in what gets built: across 161 runs where the reader actually clicked
+  something, **108 of them — 67% — never once got a result back out of the card**, 468 clicks that
+  went nowhere. It is not one model's habit (every one of the ten does it) and not one case's
+  (every case does it). The shape is always the same: a card you can fiddle with forever and never
+  finish.
+
+  **The check is one grep, so run it on what you just wrote: does the source contain a
+  \`sendMessage\` call at all?** Re-measured over 171 clicking runs, 117 of them dead: **90 — 77% —
+  have no \`sendMessage\` anywhere in the card**. The reader clicks \`RESTful (JSON)\`, \`下一步 →\`,
+  \`2. 尺度缩放 / √d\` — real controls, wired to internal state and to nothing else — and the
+  conversation stops there. Not "the ending was hard to find": there was none to find.
+
+  Two endings are correct, and which one depends on whether the options need explaining:
+
+  - **The options speak for themselves** (yes/no, this file or that one) — the click IS the answer.
+    Two plain buttons, no card around them, \`sendMessage\` on click. Nothing to preview.
+  - **The options mean something you have to see to choose between** — then the click SELECTS and
+    shows, and a separate **Submit** sends. Clicking a tab must not fire the turn; a reader
+    comparing three options should be able to look at all three first.
+
+  The preview form is a selector, a result area, and one submit — that is the whole structure, and
+  the result area is where the card earns its existence:
+
+      const [pick, setPick] = useState(OPTIONS[0].id)
+      const [sent, setSent] = usePersistedState<string | null>("migration-plan-choice", null)
+      …
+      <div className="flex flex-wrap gap-2">…one button per option, aria-pressed={pick === o.id}…</div>
+      <div className="mt-3">{OPTIONS.find((o) => o.id === pick)!.preview}</div>
+      <button disabled={sent !== null} onClick={() => { setSent(pick); sendMessage(…) }}>…</button>
+
+  \`preview\` is whatever actually shows the difference: a mermaid graph of the two migration paths,
+  the formula rendered by katex, an SVG of the layout, a working miniature of the thing, a 3D view,
+  a playable board. A paragraph of text describing the option is not a preview — the reader could
+  have read that in the reply.
+
+  **And it fires once.** \`sent\` above is persisted, so a reload shows the answer that was given
+  rather than an untouched form, and the button cannot send a second turn for a question already
+  answered.
+
 - A **canvas** stays interactive. It does not "complete"; it just sits there working.
 - A **canvas outlives the reply that made it**, so data the user puts into it — entries, notes, cards — must survive a reload on its own. Reach for \`usePersistedState\` from \`${capabilityModule("state")}\` — \`useState\`'s signature including a lazy initialiser, with the value kept in \`localStorage\` under a namespaced key, and the read and write already wrapped:
 
@@ -130,6 +212,19 @@ Two things follow from the lifetime difference:
   in a label and the user's half-typed row goes with it. Persist what they typed, not just what
   they saved.
 
+  **An inline card is clickable before you have finished writing it, and that is where this bites
+  hardest.** The reader sees the first controls while the rest of the card is still arriving, and
+  **every chunk that adds JSX remounts every component the card defines itself** — so a choice they
+  make mid-stream is wiped by the next chunk, silently, with the control snapping back to its
+  initial state. Measured three ways on the same card, one variable each: state in a
+  card-defined child is lost, the same state in the exported component survives, and
+  \`usePersistedState\` survives in either. **Two chunks is enough** — this is not a rare race.
+
+  So anything the reader can change belongs in \`usePersistedState\`, not only the answer you
+  intend to record. The one case it cannot reach is a third-party component holding its own state:
+  \`<Disclosure defaultOpen>\` reverts to \`defaultOpen\` on every remount, and the only way to keep
+  what the reader did is to control it yourself from persisted state.
+
   **If you write \`setRows(prev => prev.filter(r => r.id !== id))\` behind a button, keep the row.**
   Persisting is what makes that line permanent — before it, a mistaken delete came back on reload.
   Hold the removed row and offer it back:
@@ -181,19 +276,42 @@ Ask with an **inline** block instead: one short line saying what you need to kno
 
 \`\`\`tsx
 import { sendMessage } from "$dsh/chat"
+import { usePersistedState } from "${capabilityModule("state")}"
 
 export default function Pick() {
-  const [picked, setPicked] = useState<string | null>(null)
+  const [picked, setPicked] = usePersistedState<string | null>("ask:which-cloud-host", null)
   const choose = (id: string) => { setPicked(id); sendMessage(id) }
+  // the key names THIS question — two asks in one conversation must not share it
   // picked === null → the options; otherwise just the chosen one, still highlighted
 }
 \`\`\`
 
+**When the two answers need no explaining, they are two buttons in a row — not two cards.** The
+shape to match is in the question: \`Postgres or SQLite?\` / \`公制还是英制？\` / \`要我先跑测试吗？\` are
+answered by the label alone, and a bordered tile with a description under each says the choice is
+weightier than it is. Same \`choose\`, same key, one row:
+
+\`\`\`tsx
+<div className="flex flex-wrap gap-2">
+  {OPTIONS.map((o) => (
+    <button key={o.id} onClick={() => choose(o.id)} aria-pressed={picked === o.id}
+      className="rounded-md border border-line px-3 py-1.5 text-sm hover:bg-hover
+                 aria-pressed:bg-accent aria-pressed:text-white aria-pressed:border-transparent
+                 aria-pressed:hover:bg-accent">                    {/* or the selection vanishes under the pointer */}
+      {o.label}
+    </button>
+  ))}
+</div>
+\`\`\`
+
+Give each option a description and you have built the card version above; the descriptions are
+what earn the tiles. Two labels that stand on their own take the row.
+
 Rules for that move:
 
 - **Do it before you explore.** Listing the workspace tells you what is there, never what the user wants. Stalling in tool calls is not a step.
 - **Real options, not a form.** Each card is a thing you could go build right now. "Something else" belongs at the end as a plain text field, not as one of the cards.
-- **Ask once.** Take the answer and build. A second round reads as stalling — if a detail is still open, pick the sensible default and say so in one line.
+- **One ask per question, and their answer settles that question.** Take it and build: a detail they left open takes your sensible default, named in one line. A choice their answer just *opened* is a different question, and it takes this same move — they told you the language, so formal-or-casual is a question that did not exist a turn ago.
 
 Don't ask when the request already names the thing, when there is one obvious reading, or when building it is faster than asking about it. Plain conversational questions get plain answers.
 
@@ -214,12 +332,14 @@ This one runs *opposite* in the two places, and getting it backwards is the most
 
 - **Canvas fills its panel.** It already has a frame and a title bar around it. So take the whole space — \`height: 100%\`, your own padding, backgrounds bleeding to the edges — and do **not** wrap yourself in one more rounded, bordered, tinted box. A card inside the panel is a frame inside a frame.
 - **Inline is the card.** It sits between paragraphs, so one bounded box is what tells the reader where it starts and stops.
-- **But \`bg-base\` is the page's own colour, so a wrapper painted with it is not a box.** Measured
-  from the token table: \`bg-base\` is \`#fff\` on light and \`#151517\` on dark — the same value the
+- **But \`bg-page\` is the page's own colour, so a wrapper painted with it is not a box.** Measured
+  from the token table: \`bg-page\` (that is the CLASS; \`--dsw-alias-bg-base\` is the variable
+  behind it, and the two vocabularies are deliberately different) is \`#fff\` on light and
+  \`#151517\` on dark — the same value the
   transcript behind the card is painted with, on both grounds. A root \`<div>\` with
   \`background: var(--dsw-alias-bg-base); padding: 16px; border-radius: 12px\` therefore draws
   nothing a reader can see: what is left is an invisible 16px inset and a rounded corner nobody
-  can find, while the \`bg-layer-1\` blocks inside it read as the real frame — a frame inside an
+  can find, while the \`bg-layer\` blocks inside it read as the real frame — a frame inside an
   invisible frame. If you want the inline card to be bounded, bound it with \`bg-layer\` **plus**
   \`border-line\` (see the both-spellings rule below). If you don't, drop the wrapper's background
   and radius entirely rather than painting it the colour of the page.
@@ -301,9 +421,9 @@ Either way, don't restage the header. The panel already names the canvas, so a h
 
   **A control you have FILLED is the opposite case, and the two get confused.** The rule above is
   about separating a surface from the surface under it, where both tokens are deliberately faint —
-  \`border-l1\` is 4% black. Once an element carries a real fill (a selected segment on
+  \`border-line\` is 4% black. Once an element carries a real fill (a selected segment on
   \`state-business-primary\`, a primary button), that fill separates it completely and a leftover
-  \`border-l2\` is a grey ring around a blue block, related to nothing. Drop it — but to
+  \`border-line-2\` is a grey ring around a blue block, related to nothing. Drop it — but to
   \`transparent\`, not to \`none\`, or the selected item loses a pixel of height and the row twitches
   as the reader clicks along it:
 
@@ -318,10 +438,48 @@ Either way, don't restage the header. The panel already names the canvas, so a h
   (\`#fff\` here) as their colour and no background at all, or a white outline if the shape itself
   has to stay readable.
 - **Keep nesting shallow.** A bordered box inside a bordered box is almost always wrong; a divider line does the job.
-- **You are a component on someone else's page.** Your root is a normal node inside the chat column or the panel — nothing isolates you. No \`position: fixed\`, no \`100vw\`/\`100vh\`, no portals into \`document.body\`, no global listeners you don't remove. Overlays go in a \`relative\` wrapper you own with \`absolute inset-0\`. Effect libraries default to the wrong thing here and have to be pointed at your own element — \`canvas-confetti\` attaches a fullscreen canvas to \`document.body\` unless you pass one, so \`confetti.create(ref.current, { resize: true, useWorker: true })\` with that \`<canvas>\` absolutely positioned inside your container. Same for anything that says "mounts to body" or "fullscreen".
-- **The width is not the viewport's.** The same component lands in a narrow chat column *and* in a wide panel, so a media query tells you nothing useful — measure your own container, or design something that reads at any width. Content grids especially: one comfortable column beats two cramped ones.
+- **You are a component on someone else's page.** Your root is a normal node inside the chat column or the panel — nothing isolates you until you do it yourself. No \`position: fixed\`, no viewport UNITS (\`vh\`/\`vw\`, at any number — the window is not your box, so \`78vh\` is wrong for the same reason \`100vh\` is), no portals into \`document.body\`, no global listeners you don't remove. Overlays go in a \`relative\` wrapper you own with \`absolute inset-0\`. Effect libraries default to the wrong thing here and have to be pointed at your own element — \`canvas-confetti\` attaches a fullscreen canvas to \`document.body\` unless you pass one, so \`confetti.create(ref.current, { resize: true, useWorker: true })\` with that \`<canvas>\` absolutely positioned inside your container. Same for anything that says "mounts to body" or "fullscreen".
+- **A title or a control sitting above a long list is a \`sticky\` header. Not "could be" — is.**
+  The test is mechanical, so apply it mechanically: *is there anything above the list that the
+  reader will still want once they are deep inside it?* A heading that says what they are looking
+  at, a search box, a row of filter chips, a count that changes as they filter. If yes, that strip
+  pins. Otherwise the reader scrolls into the list, decides to narrow it, and has to scroll back up
+  past everything they were reading to reach the box that narrows it.
+  **Measured across 766 generated cards: 356 have a heading or a control above a list, and 353 of
+  them let it scroll away.** Not a tendency, an absence: the shape is in every case (60 on one, 54
+  on the next, 31, 26, 23…) and every model (95 for the worst, then 56, 44, 35, 33…), and no model
+  pins it more than the rest. One of the 353, read in full: 266 lines — \`<h2>最近工作轨迹</h2>\`, a
+  search input reading \`搜项目、作者或提交内容\`, a row of per-repo filter chips, then
+  \`filtered.slice(0, limit).map(…)\` and a "load more" button. **Zero occurrences of \`sticky\`**,
+  in that card and in the second one the same turn produced. Everything needed to steer the list
+  scrolled away the moment the list was worth steering.
+
+- **Your root sets no height and no \`overflow\`; the page is what scrolls.** You are inside a
+  column the reader is already scrolling, so a root that sizes itself and grows its own scrollbar
+  puts a second scroll inside the first. Pin with \`sticky\`, which pins against the READER's
+  scroll, and give an inner pane its own bound only when a list genuinely needs one:
+
+  \`\`\`tsx
+  <div className="isolate relative">                                   {/* your own stacking context */}
+    <div className="sticky top-0 z-10 bg-layer border-b border-line">…</div>
+    <div className="max-h-[30rem] overflow-y-auto">…</div>            {/* the list, not the card */}
+  </div>
+  \`\`\`
 
-- **In a canvas, extra width should make the rows SHORTER, not the card wider.** Measured across
+  **\`overflow\` on ANY ancestor of a \`sticky\` element switches it off, silently** — no error, no
+  warning, it simply scrolls away. Watched happen across one card's revisions: a root grew
+  \`overflow: hidden\` to contain a stacking problem, the pinned header stopped pinning, and the
+  two edits were two turns apart. Nothing between a \`sticky\` element and the page may set it.
+
+  **\`isolate\` is what keeps your \`z-index\` small.** Inside a stacking context you own, \`z-10\`
+  is above everything of yours and below everything of the app's. Without one, a number picked to
+  beat your own siblings also beats the composer the reader types into.
+
+- **The width is not the viewport's.** The same component lands in a narrow chat column *and* in a wide panel, so a media query tells you nothing useful — measure your own container with \`@container\` and \`@[32rem]:\` variants, which is the ONE responsive tool that works here. "One comfortable column beats two cramped ones" settles what to do at 320px; it is not a licence to ship the same single column at 720. **Judged by a vision panel on 59 cards at three widths, "still one column at 720px, half the card is empty" was the single most common criticism — 91% of verdicts — and "no breakpoint of any kind in the source" was 76%.** A list of items with a name and a description is \`@[30rem]:grid-cols-2\`; a strip of stats is \`@[24rem]:grid-flow-col\`. The reader who widens the panel is asking for less scrolling, and getting a wider version of the same tall column is not an answer.
+
+- **Extra width should make the rows SHORTER, not the card wider — inline as much as in a canvas.**
+  This entry read "In a canvas" for a while and that scope was wrong: a vision panel grading
+  **inline** cards raised it in 27% of verdicts, on cards that *did* carry breakpoints. Measured across
   one wave, height at 320 divided by height at 720: the five inline cards shrink 1.26–1.52x, and
   the six canvases shrink **1.02–1.18x** — one is 1100px tall at 320 and still 1076px at 720. It
   is not for want of the technique; 8 of those 9 canvases carry a container query or an intrinsic
@@ -337,7 +495,61 @@ Either way, don't restage the header. The panel already names the canvas, so a h
       </div>
 
   The reader drags a canvas panel between 320 and 720 — that drag should buy them less scrolling.
+- **Nothing you draw may carry a width the column did not give it.** Measured by mounting 60 real
+  cards at 380px: **12 overflowed the column**, across 4 of the 26 runs sampled, and the part that
+  hangs off the edge is invisible in a screenshot — the picture is clipped at the card, so an
+  absent column reads as a design choice and nobody can name the defect. Every one of the 12 was
+  the same mistake in a different costume:
+
+  | what stuck out | how far | write instead |
+  | --- | --- | --- |
+  | \`<svg width="600" …>\` | 308–348px | \`viewBox="0 0 600 400"\` and \`className="w-full h-auto"\` — the viewBox carries the coordinates, the class carries the size |
+  | a \`<pre>\`/\`<code>\` of real source | 409–705px | the code keeps its long lines; the WRAPPER gets \`overflow-x-auto\`, so the card stays put and the code scrolls inside it |
+
+  **A hand-rolled \`<pre>\` is two defects at once, and it is the single commonest thing in this
+  corpus.** Of 766 cards, **194 show code and 182 of them hand-roll a \`<pre>\` — 94%**; only 4 reach
+  for \`shiki\`. And they are where the overflow lives: of 107 measured overflows, **35 — a third of
+  everything — are a \`<code>\` element**, at a median of 195px past the edge against 84px for every
+  other tag combined. (Not one is a \`<pre>\`: the wrapper is fine, the \`<code>\` inside it is what
+  hangs off. The single widest overflow in the corpus is a \`<section>\` at 978px, so these are the
+  typical worst rather than the record holder.) So the fix is one import,
+  not two patches: \`shiki\` highlights it (see the library table) AND you still put the
+  \`overflow-x-auto\` on the wrapper. Unhighlighted source in a card the reader cannot scroll
+  sideways is code they can neither read nor reach the end of.
+  | \`<table className="min-w-[28rem]">\` | 84px | put the \`overflow-x-auto\` on the wrapper and drop the min-width, or let the columns wrap |
+
+  \`min-w-0\` is the answer to a flex child that will not shrink; this is its opposite — an
+  explicit intrinsic width you typed yourself, and no ancestor can undo it. **The widest offender
+  was 705px hanging off a 380px column**, which is not a card that looks slightly wrong, it is a
+  card most of which does not exist for the reader.
+
 - **Layout breaks late, controls break early.** A row of buttons can reflow at a small width; a grid of content cards cannot, because each column has to stay wide enough to read.
+- **Whatever \`hover:\` changes, the selected state has to claim in its hover form too.** A
+  \`hover:bg-hover\` and an \`aria-pressed:bg-accent\` on the same button generate at the SAME
+  specificity — \`:is()\` takes its argument's, so \`.class:hover\` and \`.class[aria-pressed]\` are
+  both \`(0,2,0)\` — and source order in the generated sheet puts \`hover\` last. So the selected
+  button turns back to neutral grey **while the pointer is on it**, which is exactly when the
+  reader is looking at it. **Measured across 766 generated cards: 308 real collisions in 193 cards
+  across 60 runs** — a quarter of everything written, 256 on \`bg\` and 52 on \`text\`.
+
+  Add the pressed-and-hovered pair. It is \`(0,3,0)\`, so it wins on specificity and does not care
+  where it lands in the sheet:
+
+      hover:bg-hover aria-pressed:bg-accent aria-pressed:hover:bg-accent
+
+  **Whichever attribute you marked the selection with, qualify that one** — the trick is the extra
+  variant, not the word \`aria-pressed\`. Of those 308 collisions, only 163 are on \`aria-pressed\`;
+  the rest are \`data-[state=active]\` (74), \`checked\` (43) and \`aria-selected\` (28), and each has
+  the same fix, verified against this generator:
+
+      data-[state=active]:hover:bg-accent    checked:hover:bg-accent    aria-selected:hover:bg-accent
+
+  **Do not reach for \`not-\`.** \`not-aria-pressed:hover:bg-hover\` and
+  \`hover:not-aria-pressed:bg-hover\` are the intuitive fix and this generator matches **neither** —
+  they produce no rule at all, so the button keeps the bug and the class list now says it was
+  handled. A ternary works too (\`picked ? "bg-accent" : "hover:bg-hover"\`) because only one branch
+  is ever present; reach for that when the two states differ in more than a couple of properties.
+
 - **Icons must name the thing beside them.** \`Sparkles\`, \`WandSparkles\`, \`Wand2\`, \`Stars\`, \`Bot\`, \`BrainCircuit\`, \`Zap\` as decoration say "an AI made this" and nothing else — \`Copy\` on a copy button, \`Languages\` on a translate tab, and nothing on a heading that reads fine without one. Prefer no icon to a decorative one.
 - **If you take the focus ring off, put something back.** \`outline-none\` on a borderless input
   is the most common single thing in these cards that breaks keyboard use: **77 of 378 remove the
@@ -490,6 +702,18 @@ Either way, don't restage the header. The panel already names the canvas, so a h
 
   \`aria-pressed\` for a standalone toggle, the shape above for a pick-one. It is one attribute beside the ternary you already wrote — and the group wrapper, which is what tells a screen reader these three belong together.
 
+- **Getting the attribute right and the pixels wrong is the commoner half.** A vision panel reading
+  59 cards raised this in **22% of its verdicts**, in one recurring form: \`aria-checked\` correctly
+  set, and the selected chip differing from its siblings **only by background colour**. That is one
+  channel, and it is the channel that fails first — greyscale, a dim screen, or the 8% of men with
+  a colour vision deficiency. The fix is a second channel on the same ternary, and it costs a
+  class: \`font-medium\` on the selected one, or a \`✓\` before its label, or a ring the unselected
+  ones do not carry. **Colour may be the loudest signal; it may not be the only one.**
+  (No screen for this one, deliberately: a prototype matching the template-literal ternary found
+  **7 selections across three waves and zero colour-only ones**, against 22% in the verdicts — the
+  shapes a card writes this in are too many for a regex, and a detector that narrow reports a
+  clean sweep on a defect that is everywhere.)
+
   **Write the state and the style it produces as one token, and this whole class of bug stops
   existing.** \`aria-checked:bg-accent\` is a single string: there is no second place for it to
   disagree with. Measured on a card written before that was possible — the CSS said
@@ -736,7 +960,7 @@ retrieve a page body — render the snippet and link the source.
 
 ## Reading and writing workspace files
 
-\`$dsh/fs\` gives a card \`readFile(path) -> string\`, \`readdir(path) -> {name, type, size}[]\`
+\`$dsh/fs\` gives a card \`readFile(path) -> string\`, \`readBytes(path) -> Uint8Array\`, \`readdir(path) -> {name, type, size}[]\`
 (\`type\` is \`"file"\` or \`"directory"\`, so a tree needs no probing; \`size\` is bytes, absent on
 directories) and \`writeFile(path, content)\` over the workspace. Paths are workspace-relative and
 \`path\` is required — there is no "current directory" argument-less form, under the
@@ -744,6 +968,29 @@ session's own access mode — the same fence the file tools run behind. So a rea
 refuses the write, and the card should say so rather than looking broken: catch it and tell
 the user the session is read-only.
 
+**Anything that is not text goes through \`readBytes\`.** \`readFile\` decodes as UTF-8, so a png, a wav
+or a \`.mid\` read that way comes back with every byte above 0x7f replaced by U+FFFD — corrupt, and
+silently so. And there is **no HTTP route that serves workspace files**: \`<img src={\`/\${path}\`}>\`
+resolves against the app, 404s, and the reader gets a page of broken icons. Measured on a real
+canvas that found 357 images and showed none of them. The whole shape is three lines:
+
+\`\`\`tsx
+const [url, setUrl] = useState<string>()
+useEffect(() => {
+  let live = true, made: string | undefined
+  void readBytes(path).then((bytes) => {
+    if (!live) return
+    made = URL.createObjectURL(new Blob([bytes]))
+    setUrl(made)
+  })
+  return () => { live = false; if (made !== undefined) URL.revokeObjectURL(made) }
+}, [path])
+\`\`\`
+
+Revoking is not optional in a browser that keeps a long transcript: one object URL per image per
+mount, never released, is a leak the reader pays for in memory. A grid of them wants an
+\`IntersectionObserver\` too — read the bytes when the cell comes near, not all of them on mount.
+
 Reach for it when the data **belongs to the workspace** — a file the user can also open, edit
 and commit.
 
@@ -851,14 +1098,36 @@ A canvas is a file, so you can run a checker over it. \`@genui/cli\` validates e
 kind of TSX:
 
 \`\`\`
-npm_config_cache="$TMPDIR/npm-cache" npx --yes ${CLI_URL} check <file>${typesMap === undefined ? "" : ` -i ${typesMap}`}
+${RUN_CLI} check <file>${typesMap === undefined ? "" : ` -i ${typesMap}`}
 \`\`\`
 
-\`npx\`, not \`bunx\` — bun cannot parse a scoped package name inside that URL. The
-\`npm_config_cache\` prefix is not optional: your commands run sandboxed and npm's default cache
-under \`~/.npm\` is not writable there, so a bare \`npx\` dies with \`EPERM mkdtemp\` and a message
-about root-owned files that has nothing to do with the real cause. \`check\` includes
-TypeScript diagnostics; \`lint\` is the faster syntax-only pass.
+**\`bunx\` needs the package NAME in front of the URL** — \`genui@https://…\`. Bun reads the whole
+argument as \`<name>@<spec>\`, so a bare URL gives it an empty name and it stops at
+\`unrecognised dependency format\` before fetching anything. Any name works; it is a label, not a
+lookup.
+
+If bun is not there, in order:
+
+\`\`\`
+pnpx --config.blockExoticSubdeps=false ${CLI_URL} check <file>
+npm_config_cache="$TMPDIR/npm-cache" npx --yes ${CLI_URL} check <file>
+\`\`\`
+
+Both take the bare URL. The pnpm flag is **not** optional — the CLI pulls \`@genui/unocss\` by URL
+as well, and pnpm refuses URL-resolved SUBdependencies by default, so without it you get
+\`ERR_PNPM_EXOTIC_SUBDEP\` naming a package you never asked for. Do **not** add
+\`--config.cacheDir\` beside it: pnpm then loses the package's own bin and dies with
+\`spawn cli ENOENT\`, which reads like the package is broken and is not. It needs no cache redirect
+anyway — its store is the one of the three your sandbox lets you write.
+
+**The other two do**, and the reason is worth knowing because it disguises itself. Sandboxed,
+\`touch ~/.npm/_cacache/x\` and \`touch ~/.bun/install/cache/x\` both come back
+\`Operation not permitted\`; the directories exist, they are simply not yours to write from in
+there. npm reports this as \`EPERM mkdtemp\` **and a message about root-owned files**, which sends
+you looking for a permissions problem in your home directory that is not there. \`$TMPDIR\` is
+writable, so pointing each cache at it is the whole fix.
+
+\`check\` includes TypeScript diagnostics; \`lint\` is the faster syntax-only pass.
 
 ${maps}
 
@@ -911,14 +1180,19 @@ Bare specifiers resolve from npm at render time — there is no install step, so
 
 **Nor because a library might have quirks.** Hand-rolling an SVG chart to avoid \`recharts\`, or a plain textarea to avoid a markdown renderer, is not the safe choice — it is a worse component and several hundred lines you now own. Reach for the real library: \`recharts\` for charts, \`@dnd-kit/core\` for drag, \`motion/react\` for animation, \`lucide-react\` for icons. Write it by hand only when nothing does the job.
 
-Four that are easy not to think of, each with the one thing to get right:
+Five that are easy not to think of, each with the one thing to get right:
 
 | want | reach for | the detail |
 | --- | --- | --- |
 | a running total, score, or counter the user watches change | \`@number-flow/react\` | \`import NumberFlow from "@number-flow/react"\` — a **default** import; there is no named \`NumberFlow\` export, and \`import { NumberFlow }\` is \`undefined\` and a blank card. Then \`<NumberFlow value={n} />\` in place of \`{n}\` |
 | a panel that slides in, especially on a narrow card | \`vaul\` | \`<Drawer.Portal container={hostEl}>\` — without \`container\` it portals to \`document.body\`, outside your card |
 | a transient confirmation | \`sonner\` | import **both** \`toast\` and \`Toaster\`, and render \`<Toaster />\` in your tree — \`toast()\` alone is silent, with no error anywhere. Worth reaching for rather than hand-rolling: a hand-written toast is almost always \`position: fixed\`, which floats it over the whole app instead of your card |
-| form controls | \`@headlessui/react\` | \`Field\` + \`Label\` around \`Switch\`/\`Listbox\`/\`Combobox\` — labelling comes with them |
+| form controls — a switch, a select, a combobox, a modal, tabs, a disclosure | \`@headlessui/react\` | \`Field\` + \`Label\` around \`Switch\`/\`Listbox\`/\`Combobox\` — labelling comes with them. Its \`Disclosure\` and \`Tab\` are also the cheapest correct way to build the folding a dense card needs. **The container components render a \`Fragment\`, so a \`className\` on one throws and takes the whole card with it** — \`<Disclosure className=…>\` dies with *Passing props on "Fragment"!* and the reader gets that sentence instead of the card. Measured: 1 of the 4 cards in a wave that reached for this library. Write \`<Disclosure as="div" className=…>\`; same for \`Tab.Group\`, \`Listbox\`, \`Menu\`, \`RadioGroup\`. The leaves (\`Disclosure.Button\`, \`.Panel\`) are real elements and take \`className\` as they are, which is why the failure looks like the library rejecting a style it accepts everywhere else. |
+| the same, when you want arrow-key roving between tabs or menu items | \`@radix-ui/react-tabs\`, \`@radix-ui/react-accordion\`, \`@radix-ui/react-dialog\` | one package per primitive, so import only what you use. **This is the one that gives arrow-key navigation**: Radix's \`Tabs\` moves focus with ←/→ and Home/End, Headless UI's does not — a real user asked for exactly that and was right to notice it missing. Compose from \`Tabs.Root\`/\`List\`/\`Trigger\`/\`Content\`; they render unstyled, so every class is yours |
+| a formula the reader is trying to READ, not just the number it comes out as | \`katex\` | \`katex.renderToString(tex, { throwOnError: false })\` into \`dangerouslySetInnerHTML\`; it has both a default and a named \`renderToString\`, so either import works. \`throwOnError: false\` is the load-bearing half — a half-typed \`\\\\frac{a}\` renders as \`<span class="katex-error">\` instead of throwing during render and taking the card with it, and half-typed is what streaming produces. The glyph metrics come from its stylesheet: append \`<link rel="stylesheet" href="https://esm.sh/katex@0/dist/katex.min.css">\` in an effect and REMOVE it in the cleanup, the same way you would a listener |
+| a flow, a sequence, a state machine — anything whose content is *which box points at which* | \`mermaid\` | \`mermaid.initialize({ startOnLoad: false })\` once, then \`await mermaid.render(id, "graph LR; A-->B")\` which resolves \`{ svg }\` for \`dangerouslySetInnerHTML\` — it is async and returns a string, it does not mount itself. Give each render a unique id or the second one collides with the first. Reach for this before hand-placing boxes: you write the edges and it does the layout, which is the part that goes wrong by hand |
+| a diagram whose POSITIONS carry meaning — a system laid out the way the reader pictures it, a floor plan, an annotated screenshot | your own \`<svg>\`, or boxes and CSS | This is the one case where hand-drawing IS the answer, and the rule above does not contradict it: \`recharts\` renders DATA, and there is no library that knows what your boxes are or which arrow goes where. Asked to draw something, draw it — a card that answers "画出来" with a bulleted list of the parts has changed the question. Nodes as positioned boxes with \`<svg>\` lines between them, or a grid of boxes with borders for the edges, both read fine |
+| showing code, a diff, or a config file | \`shiki\` | \`await codeToHtml(src, { lang, theme })\` in an effect, then \`dangerouslySetInnerHTML\` — it is async, so render a \`<pre>\` of the raw text first and swap. A hand-rolled \`<pre>\` with no highlighting is the tell that this was skipped, and for a diff the red/green is the whole point. **\`@monaco-editor/react\` only when the reader will TYPE into it.** Measured on a real card that used it for two read-only tabs: Monaco's language service spent **22 seconds** in its worker running TypeScript analysis on code nobody was editing, \`_registerLanguages\` cost another 571ms at startup, and a tab switch took **132ms** where the same card's other buttons took 4ms. Everything the reader wanted from it — line numbers, colours, two files — \`shiki\` renders as static HTML |
 
 
 Names you half-remember are the main failure mode: a wrong export is not a typo, it is an \`undefined\` component and a blank render, with nothing in the console naming it. So look a name up *before* you write the code, not after it breaks — for lucide, fetching \`https://lucide.dev/icons/<kebab-name>\` answers it outright, since a 404 means the name does not exist. Icons you have actually watched render are fine to reuse from memory.

package/types/fs.d.ts

@@ -12,6 +12,20 @@ declare module "$dsh/fs" {
    * `readFile` decodes as UTF-8 and would corrupt them silently. Capped at 8MB.
    */
   export function readBytes(path: string): Promise<Uint8Array<ArrayBuffer>>;
-  /** Rejects with `FS_SANDBOX_DENIED` when the session is read-only. */
+  /**
+   * A refusal, told apart from a breakage.
+   *
+   * `denied` is the field to branch on: the session said no, and no retry changes that —
+   * show the reader what would have been written and let them apply it another way.
+   * Anything else (a missing directory, a full disk) is an outage and reads as one.
+   */
+  export type FsError = Error & { denied?: boolean; code?: string };
+  /**
+   * Writes the file, under the session's own access mode.
+   *
+   * Rejects with a `FsError` whose `denied` is true when the session may not write —
+   * `code` is `FS_SANDBOX_DENIED` there. **A write the reader did not ask for is not
+   * yours to make**: put it behind a control they press.
+   */
   export function writeFile(path: string, content: string): Promise<void>;
 }