dsh-generative-ui 0.0.2 → 0.0.3

package/lib/index.js

@@ -16,6 +16,7 @@ var AI_STREAM_PATH = "/dsh-generative-ui/ai";
 var FS_PATH = "/dsh-generative-ui/fs";
 var EXEC_PATH = "/dsh-generative-ui/exec";
 var WEB_SEARCH_PATH = "/dsh-generative-ui/web-search";
+var CARD_ERROR_PATH = "/dsh-generative-ui/card-error";
 
 // src/contract.ts
 var UI4A_DIR = ".dsh/ui4a";
@@ -56,8 +57,36 @@ function canvasIdOf(path) {
   return isCanvasId(id) ? id : null;
 }
 
+// src/card-failure.ts
+var CARD_FAILURE_CONTEXT = "ui4a:card-failure";
+var CARD_FAILURE_CONTEXT_ORDER = 250;
+var failureText = (failure) => `A ui4a card in this session is not rendering. It failed at the ${failure.phase} step:
+
+${failure.message}
+
+This is current state, not a new event — it is re-read every step and disappears once the card renders. If the error names the correct usage (the available exports, for instance), fix the card and send it again. If it does not, look it up before you change anything.`;
+var WAKE_TEXT = "A ui4a card you wrote is not rendering — the failure is in the runtime context. If there is no card failure there, it recovered on its own between this notice and now: say nothing about it and carry on with what you were doing.";
+var WAKE_SUMMARY = "ui4a card failed to render";
+
+class CardFailures {
+  bySession = new Map;
+  set(session, failure) {
+    const wasHealthy = !this.bySession.has(session);
+    this.bySession.set(session, failure);
+    return wasHealthy;
+  }
+  clear(session) {
+    this.bySession.delete(session);
+  }
+  text(session) {
+    const failure = session === undefined ? undefined : this.bySession.get(session);
+    return failure === undefined ? "" : failureText(failure);
+  }
+}
+
 // src/skill.ts
 var CLI_URL = "https://pkg.pr.new/MindLab-Research/macaron-genui-demo/@genui/cli@main";
+var RUN_CLI = `BUN_INSTALL_CACHE_DIR="$TMPDIR/bun-cache" bunx --yes genui@${CLI_URL}`;
 var SKILL_NAME = "generative-ui";
 var SKILL_DESCRIPTION = `How to decide between an inline ${FENCE_LANG} block, a canvas file, and plain prose — and how to lay one out so it reads. Load it **before you decide**, not after — including when your first instinct is that prose is enough. Most of the questions that should have been an interface do not ask for one.`;
 function mapNotes(typesMap, standaloneMap) {
@@ -91,7 +120,7 @@ function mapNotes(typesMap, standaloneMap) {
     `${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`,
@@ -126,11 +155,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:
 
@@ -145,6 +252,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:
@@ -196,19 +316,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.
 
@@ -229,12 +372,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.
@@ -316,9 +461,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:
 
@@ -333,10 +478,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:
 
-- **In a canvas, extra width should make the rows SHORTER, not the card wider.** Measured across
+  \`\`\`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>
+  \`\`\`
+
+  **\`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
@@ -352,7 +535,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
@@ -505,6 +742,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
@@ -751,7 +1000,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
@@ -759,6 +1008,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.
 
@@ -866,14 +1138,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}`}
+\`\`\`
+
+**\`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>
 \`\`\`
 
-\`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.
+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}
 
@@ -926,14 +1220,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.
@@ -966,7 +1265,9 @@ export default function Answer() {
 - **The info string is \`${FENCE_LANG}\`, never \`tsx\`.** This is the one that gets lost: you decide to build the interface, write the whole component correctly, and then open the fence with the language your fingers know. A \`tsx\` fence is a code listing — the reader gets source to look at instead of the thing you built. Check the opening line before you write the body.
 - The module must \`export default\` a component taking no props.
 - **Never name it after something you imported.** \`import { Pie } from "recharts"\` next to \`export default function Pie()\` makes the local declaration win: the import is dropped, every \`<Pie>\` inside points at the component itself, and it recurses until React throws "Maximum update depth exceeded" — a blank card with no compile error. Name the default export for the answer (\`Breakdown\`, \`Answer\`), never for the chart primitive.
-- \`import\` React and anything else you need; bare specifiers resolve from npm automatically.
+- \`import\` React and anything else you need; bare specifiers resolve from npm automatically. **Any package, not a short list** — \`@headlessui/react\` or \`@radix-ui/react-*\` for switches, tabs, modals and disclosures that already handle focus and the keyboard, \`shiki\` to syntax-highlight code or a diff (**never \`@monaco-editor/react\` for code the reader only READS** — measured, a card that did spent 22s of worker time analysing code nobody edited and took 132ms per tab switch against 4ms for its other buttons), \`recharts\` for charts, \`lucide-react\` for icons. There is no install step and no allowlist, so hand-rolling a component to avoid an import is a worse component you now own.
+
+  **Four widgets are never hand-written here, because hand-writing them silently drops the keyboard.** A row of tabs, a collapsible section, a dropdown or select, a modal. Written by hand they look finished and are not: measured, a real reader clicked through a hand-rolled tab strip and asked *"我以为用了的话就能有左右方向键来切换 tab 的功能呢"* — arrow-key roving, Home/End, focus returning where it came from, \`aria-selected\` following the panel. That is a day of work in a library and a \`useState\` away from wrong by hand. **\`@radix-ui/react-tabs\` is the one with arrow keys**; \`@headlessui/react\`'s \`Tab\` does not rove. Reach for the import the moment you type the state that switches between them, not after someone notices. **The hand-rolled ones do not feel like a decision** — measured across 125 cards, \`@headlessui/react\` was imported **zero times** while 40% of those cards hand-wrote a disclosure out of \`useState\` and a conditional, re-deriving the focus and keyboard behaviour \`Disclosure\` ships with. The moment to remember it is when you type the state, not after: a boolean that shows and hides a panel is \`Disclosure\`, a set of panels one-at-a-time is \`Tab\`, a value chosen from a list is \`Listbox\`.
 - **\`useState\` holds state; \`useMemo\` computes a value.** Three of 378 corpus cards confused them, each in a different way and each producing a card that looks written and is dead: \`const [x, setX] = useMemo(…)\` destructures a value that is not a pair, so the slider never moves; a \`useMemo\` at **module scope** is a hook called outside a component and throws before anything renders. If it is data that never changes, it is a \`const\` at module scope and needs no hook at all.
 - **Write the React import before you write the data.** Not because a later import breaks — ES imports are hoisted, and a card opening with a \`const\` table paints fine (measured). Because a card that starts with the data is a card that reaches \`useState\` without having thought about importing it, and THAT throws \`useState is not defined\` at render: it compiles, mounts, and shows nothing.
 
@@ -1003,13 +1304,13 @@ export default function Answer() {
     onChange={ (e) => setN(e.target.value === "" ? "" : Number(e.target.value)) }   // stays empty
 
 - **A guard against \`undefined\` is not a guard against empty.** \`if (!commits) return <Loading/>\` passes for \`[]\`, and the next line — \`commits[commits.length - 1].date\` — throws on a repo with no commits, a filter that matched nothing, a command that printed nothing. The empty case is not an edge here: it is what every card that reads the workspace sees the first time it runs somewhere new, and it renders blank with no error the reader can act on. Check \`length\` before you index, and say what is missing.
-- \`import { readFile, writeFile, readdir } from "$dsh/fs"\` reads and writes the workspace, under **the session's own access mode** — the same fence the model's own file tools run behind, so a read-only session refuses the write rather than pretending. **Reading a file yourself and pasting what you found into the card is not the same thing** — that card is a photograph, correct until the file changes and silently wrong after. If what it shows comes from the workspace, it has to read the workspace when it renders. \`localStorage\` is still right for a canvas's own private state.
+- \`import { readFile, readBytes, writeFile, readdir } from "$dsh/fs"\` reads and writes the workspace, under **the session's own access mode** — the same fence the model's own file tools run behind, so a read-only session refuses the write rather than pretending. **Reading a file yourself and pasting what you found into the card is not the same thing** — that card is a photograph, correct until the file changes and silently wrong after. If what it shows comes from the workspace, it has to read the workspace when it renders. \`localStorage\` is still right for a canvas's own private state. **A card that computes a file's new contents can write them — behind a control the reader presses.** Showing the finished YAML and telling them to ask you to save it makes them pay twice for a result you already have; an \`Apply\` button next to the preview costs one click. The button is the consent, so it says what it will do (\`Write cordis.patch.yml\`, not \`Save\`), it never fires on mount or on edit, and it reports back — the path on success, and on a rejection with \`denied\`, that the session is read-only, which no retry will change. **Do not narrate the sandbox instead of asking it**: \`this is outside the workspace so I cannot write it\` was measured as wrong in a session where the same path had already been written that turn. Call \`writeFile\` and let the fence answer. **A file that is not text goes through \`readBytes(path) -> Uint8Array\`, never \`readFile\`** — \`readFile\` decodes as UTF-8, so a png, a wav or a \`.mid\` comes back with every byte above 0x7f replaced by U+FFFD: corrupt, and silently so. To show a workspace image: \`const url = URL.createObjectURL(new Blob([await readBytes(path)]))\`, and \`URL.revokeObjectURL\` when it is replaced. **There is no HTTP route that serves workspace files** — \`<img src={\`/\${path}\`}>\` resolves against the app, 404s, and every thumbnail is a broken icon.
 - \`import { streamText } from "$dsh/ai"\` runs a model call from inside the card, on the app's own model and credentials. **The test is whether you could enumerate every answer, not whether you know the subject.** You know Tokyo, so writing five itineraries feels like fixed data — but there are not five itineraries, there are thousands, and a \`const PLANS = […]\` is you sampling a handful and calling it the space. Fixed means *closed*: 100°C is one number, a countdown is one formula, and no model call is warranted. Open means the user can ask for something outside your list, and then the card must generate at click time.
 __EXEC_BULLET__
 
 - \`import { search } from "$dsh/web"\` runs one web search and resolves with \`{content?, sources, truncated}\` — \`sources\` is \`{url, title?, snippet?, publishedAt?}\`, and only \`url\` is guaranteed. **Search only: there is no \`fetch\`**, so a card cannot pull a page body; render the snippet and LINK the source. **Show the sources.** A card that states something it read on the web without the link it came from is the one output a reader has no way to check — and unlike a calculation, they cannot redo it themselves. Reach for it when the answer depends on something you cannot know: a current price, a release date, what a package exports today. Not for what you already know.
 - \`import { sendMessage } from "$dsh/chat"\` drives the next turn from inside the card. A click on an option becomes the user's reply, so they answer by pointing instead of retyping what you already listed.
-- \`import { usePersistedState } from "$dsh/state"\` is \`useState\` that survives — same signature, lazy initialiser included, kept in \`localStorage\` under a namespaced key with the read and the write already wrapped. Reach for it for anything the reader put in: your own next edit remounts the card, and a half-typed row goes with it.
+- \`import { usePersistedState } from "$dsh/state"\` is \`useState\` that survives. **That is the module's only export, and the key comes first:** \`usePersistedState(key, initial)\`, lazy initialiser included, kept in \`localStorage\` under a namespaced key with the read and the write already wrapped. Both halves of that sentence are load-bearing and both were measured going wrong: a card that reached for a sibling it assumed was there (\`import { write, usePersistedState }\`) rendered **completely blank with no error at all**, because an unresolvable named import kills the whole module; and this line used to say "same signature", which is false in the one way that matters and produced \`usePersistedState(false, "saved")\`. Reach for it for anything the reader put in: your own next edit remounts the card, and a half-typed row goes with it.
 - **These __CAPABILITY_SET__ are the whole set — __CAPABILITY_LIST__ — and a further one you reason your way to does not exist.** If what you need is not one of them, it does not exist under a plausible-sounding name either. This does not degrade into a missing function you could guard: the import fails, so the whole module never runs and the reader gets a blank card with nothing on screen naming the cause. If what you want is not on this list, build it out of what is.
 - Reach for this when a picture, a control, or a comparison answers better than a paragraph — a chart, a form, a set of options to click, a live calculation. Not for text that is already fine as text.
 - **A question does not have to say "build" to want this.** Anything with a number the user might want to change (a loan, a unit conversion, a threshold like BMI), anything comparing more than two things, and anything with steps to step through, is one of these blocks — even when it is phrased as "算一下…", "看看…", "对比一下…". Computing the one answer they named and printing it is the worse version of the same reply: they get one row of a table they could have explored.
@@ -1040,7 +1341,7 @@ __EXEC_BULLET__
   button that answers with everything at once. \`这个请求太模糊了\` is the argument for the fields, not against them:
   vague is what makes the form worth building, and a model that asks in prose has done the hard half (working out
   which questions matter) and skipped the cheap half.
-- **When they hand you an expression, they are asking what it will do — show them.** A cron line, a regex, a glob, a \`.gitignore\` rule, a chmod number, a semver range: the user is holding something opaque and wants its behaviour, not its grammar. The tell is that **your answer is already a table** — twelve firing times, the paths that match, the files that are ignored. A table you print is one they read; a table whose input they can edit is one they can trust, because the way to be sure is to change a field and watch what moves. Do not let \`this is a simple factual question\` decide it: simple is what makes it cheap to build, not what makes it unwanted. **Nor let the opposite decide it.** Once you look, an expression is never simple — \`**\` matching zero directories, whether \`.d.ts\` counts, what bash does without globstar. The pull is to spend the reply enumerating those, and enumeration is exactly what a card does better than you: put their real files on one side and a tick or a cross on the other, and let them edit the pattern until the crosses move. **\`这些细节值得讲清楚\` is the argument for the card, not against it.** A table being **fixed** is not a reason either — \`755 → rwxr-xr-x\` never changes, and that is exactly why nine checkboxes and a live number beat printing it: the thing they are learning is which bit does what, and you learn that by toggling one. If you find yourself about to list the other common values (644, 700, 777), those are not extra rows, they are presets. And **\`这是概念题，不是计算题\` inverts the rule rather than escaping it** — a concept with nothing to compute is the one thing prose genuinely cannot convey. \`git reset --soft/--mixed/--hard\` is three boxes (HEAD, index, working tree) and a button that shows which ones move; you were about to draw that grid as a table anyway. Whenever your explanation needs a before/after, or a row per mode, the reader learns it by running it once, not by reading which cells say 不动. \`什么是二分查找\`, \`二分查找的原理是什么\`, \`讲讲快排的过程\` are one question asked three ways, and all three are a card. **Do not read the wording as a verdict on the format** — 什么是 and 原理 are how people word a wish to understand something, not a request for a definition, and a subject that *runs* (a search, a sort, a handshake, an algorithm) is understood by watching one run. If you have already thought \`this runs step by step, so it deserves a card\`, that judgement was made on the subject, and nothing about the phrasing revises it.
+- **When they hand you an expression, they are asking what it will do — show them.** A cron line, a regex, a glob, a \`.gitignore\` rule, a chmod number, a semver range, **a formula**: the user is holding something opaque and wants its behaviour, not its grammar. Those six are instances of one shape, not the shape itself — \`softmax(QK^T/√d)V\` is an expression somebody is holding exactly as a cron line is, and \`带具体数字算一遍，我自己跟着算\` is \`这个 cron 几点跑\` in another subject. Measured: three models spent eight, ten and twelve turns on that request typing matrices into code fences by hand, truncating them **three times** so the reader had to ask for the rest — a grid of numbers you are typing out is the same tell as a table you are printing. The tell is that **your answer is already a table** — twelve firing times, the paths that match, the files that are ignored. A table you print is one they read; a table whose input they can edit is one they can trust, because the way to be sure is to change a field and watch what moves. Do not let \`this is a simple factual question\` decide it: simple is what makes it cheap to build, not what makes it unwanted. **Nor let the opposite decide it.** Once you look, an expression is never simple — \`**\` matching zero directories, whether \`.d.ts\` counts, what bash does without globstar. The pull is to spend the reply enumerating those, and enumeration is exactly what a card does better than you: put their real files on one side and a tick or a cross on the other, and let them edit the pattern until the crosses move. **\`这些细节值得讲清楚\` is the argument for the card, not against it.** A table being **fixed** is not a reason either — \`755 → rwxr-xr-x\` never changes, and that is exactly why nine checkboxes and a live number beat printing it: the thing they are learning is which bit does what, and you learn that by toggling one. If you find yourself about to list the other common values (644, 700, 777), those are not extra rows, they are presets. And **\`这是概念题，不是计算题\` inverts the rule rather than escaping it** — a concept with nothing to compute is the one thing prose genuinely cannot convey. \`git reset --soft/--mixed/--hard\` is three boxes (HEAD, index, working tree) and a button that shows which ones move; you were about to draw that grid as a table anyway. Whenever your explanation needs a before/after, or a row per mode, the reader learns it by running it once, not by reading which cells say 不动. \`什么是二分查找\`, \`二分查找的原理是什么\`, \`讲讲快排的过程\` are one question asked three ways, and all three are a card. **Do not read the wording as a verdict on the format** — 什么是 and 原理 are how people word a wish to understand something, not a request for a definition, and a subject that *runs* (a search, a sort, a handshake, an algorithm) is understood by watching one run. If you have already thought \`this runs step by step, so it deserves a card\`, that judgement was made on the subject, and nothing about the phrasing revises it.
 - **"看看都有啥" is a request to browse, and browsing is a card.** 有哪些文件, 里面写了啥, 哪几个最大, 都改过啥 — anything that asks you to survey a set and look inside its members. **Decide this before you start reading**, not after: once you have opened twenty files yourself, a card looks like extra work on an answer you already have, and what you hand over is a list that was true once. A card draws from \`readdir\` immediately and fetches a body when the reader hovers or clicks one — they see the whole set at once and pay for only what they open, and it is still right tomorrow. __EXEC_HISTORY__
 - **Asking for a few of something is asking for more of them.** Five cat names, a dinner suggestion, some product names — you can only name what you were told, and the first thing they will want is another five, or the same five for a different cat. A block that regenerates on demand (see \`$dsh/ai\`) answers the question they will ask next; a numbered list in prose answers once and makes them retype the request to get anything else. **It does not have to ask for a number, and a casual question is still this.** \`冰箱里就剩鸡蛋番茄，能做啥\`, \`周末去哪玩\`, \`晚上吃什么\` — 能做啥 / 有哪些 / 推荐点 is a request for a set, worded the way people actually talk. Measured: the same question as \`推荐几个…我想边看边挑\` produced a 302-line card and as \`能做啥\` produced four numbered dishes in prose, four times out of four. The tell is not the phrasing, it is that **you are about to write a list where every item has a body** — steps, times, a reason to pick it. \`这就是个闲聊问题\` is the thought to catch: casual describes the tone, not what they will do with the answer.
 - **"Visualise this", "show me a chart", "make it interactive" is this block, not a tool.** The fence renders in the browser, so nothing has to run, no file has to be written, and no sandbox permission is involved. Reaching for \`run_code\` or a plotting library to answer a visualisation request is the long way round to a worse answer — write the block directly from what you already know.
@@ -1054,12 +1355,31 @@ A canvas is a file rather than a fence:
 
 Use the ordinary file tools — writing the path is what creates the canvas.
 
+**Which one to use is the skill's call, but the default is not.** A canvas is a file in the user's
+workspace that they now own and have to close, so it is something you do TO their workspace, not a
+richer way to answer. Unless they asked for something durable — a page, a report, a tool, a board,
+somewhere to come back to — the answer to a question goes inline, however long and well-organised
+that answer turns out to be. Measured on a session that had loaded the skill: asked what changed in
+a release, the model wrote a \`.ui4a.tsx\` file for a question asked once.
+
 ## Load the skill before you explore, not before you build
 
 Load the \`${SKILL_NAME}\` skill as your **first** step on anything that might want an interface. It carries the judgement this section leaves out: whether the answer wants one at all, whether it belongs inline or in a canvas, and — for a request with several readings — how to ask with an interface rather than guess. **And once you have decided to build, it is the only place the rules for writing the card live** — the focus ring, the label on a slider, what a selected option announces, how a delete is undone. Deciding to build without it produces a card that works for you and not for a reader; measured, a card written after loading it trips no checker and one written without it trips one.
 
 **"Might want an interface" is a lower bar than it sounds, and it is where the loading fails.** Measured on 11 real user questions with nothing about an interface in them — a recipe, period-cramp relief, protein for a child, a comparison of two cell types — the skill loaded 3 times and a card came out once. Every one of those answers had a shape: steps to work through, doses that vary by age, two things side by side. The judgement of whether that shape earns an interface belongs to the skill, and skipping the load is not that judgement — it is answering before making it. Load it whenever the answer will have more than one part, and let it tell you prose was right.
 
+**The decision is per turn, and the first turn is the worst one to make it on.** Measured across
+121 conversations of five turns or more: 93 loaded the skill on turn 0, 7 on turn 1, exactly 1 on
+turn 2, and **none ever loaded later** — and of the 20 that never loaded, all 20 produced nothing
+across 179 turns between them. Not one recovered. The trap is that turn 0 is usually the turn where
+prose is genuinely right: the request is one line, the workspace is empty, and the honest answer is
+"paste the query". Two models got that identical opening — \`这条查询慢得离谱\` against an empty
+directory — and both answered it correctly in prose; the one that had loaded the skill anyway spent
+turn 1 on a card comparing two index designs, and the one that had not wrote that same comparison as
+a markdown code block and never reconsidered across seven further turns. **So ask again every turn.**
+A conversation is specified gradually, and the turn that finally names the table, the row count and
+the query is the turn the shape arrives — normally not the first one.
+
 **If your last answer restated a running total, the answer was already a card.** This is the
 largest single shape in real use — 22% of a sampled corpus — and the one where a card almost never
 appears: **18 runs across three models, 0 fences, 0 canvases, and 17 of the 18 replies carried a
@@ -1103,7 +1423,7 @@ will not ask for a card they do not know they can have.
 
 **The numbered-list tell is not about architecture — it is about the list.** The paragraph above
 found it while explaining a system, but the shape is the signal wherever it turns up. Measured on
-a real answer to \`¿Con qué otro pastel combinaría el pistacho?\`: six numbered options, a
+a real answer to a question asking which flavour to pair with another: six numbered options, a
 paragraph of reasoning under each, 1,600 characters, no card — while other models built one for
 the same question. Six options with a note apiece is a set the reader wants to compare, and
 comparing is what a card does and prose does not: they read it top to bottom once and keep
@@ -1114,6 +1434,96 @@ seven times is the same list with the digits removed, and it was measured at 2,5
 prose in the same wave. A run of parallel items, each with its own explanation, is a card whether
 you number it, bold it, or bullet it.
 
+**A one-line gloss is still an explanation, and headings over groups make it worse, not better.**
+The rule above says "a paragraph under each" and that wording has a hole in it: \`- **read** — 读文本文件\`
+twenty times, under four \`###\` group headings, is not a paragraph apiece, so it reads as exempt.
+It is the same shape at higher density — and the grouping is you admitting the list is long enough
+to need navigating. Measured on a question asking what a runtime exposes: 17 to 23 such rows in prose on five of
+six models, four times out of four on some — the single worst-covered question of its wave. **The
+test is what the reader does with it.** A list they read once, top to bottom, and are done with is
+prose. A list they will come back to, scan for one entry, or want narrowed — a catalogue, an
+inventory, an API surface, a set of options — is a card, and the group headings you were about to
+type are its filters.
+
+**If you are about to draw it, you have already agreed it is not prose.** Three shapes say this out
+loud, and each is a card that got typed into a code fence instead:
+
+- **Box-drawing characters.** \`┌─┐\` \`│\` \`└─┘\` \`▼\` around labelled boxes with arrows between them.
+  Measured on a question about one layer of a plugin stack: a three-tier diagram hand-drawn with 416 box characters —
+  layers, the packages inside each, arrows for who calls whom. Every one of those boxes is a part
+  the reader wants to open; in a fence they cannot, and the whole thing reflows into garbage on a
+  narrow screen.
+- **Aligned monospace columns**, padded with spaces to line up. That is a grid you are laying out by
+  hand, badly, in a medium with no layout.
+
+The counter-argument is that a fence is quicker and the diagram is only illustrative. It is quicker
+for you. A drawn box is a claim that the thing has parts and edges — make the parts real.
+
+**A markdown table over about four rows is a card you stopped one step short of.** It gets its own
+line because it does not feel like drawing — it is just markdown, and markdown is what prose is
+made of. But a table is a card with the interactivity taken out: you already decided the answer has
+columns and that the reader will read DOWN one of them. Give it back the sorting and the filtering
+and you have built the thing you were describing. **"I am explaining, the table is only support" is
+the thought that gets past this** — measured on a question asking what a repository's tests cover:
+prose with a 40-row two-column table under section headings, on five of six models, while the same
+models put a card up for a question asking what tools exist every single time. The difference was not the shape of
+the answer; it was that one felt like a catalogue and the other felt like teaching. A table that
+long IS the answer, whatever the paragraphs around it are doing.
+
+**Every tell above is the same question, asked late.** They are worth reading because they name
+shapes you can catch yourself typing, but by then you have already chosen. Ask it first, once, of
+every answer, before the first line goes out:
+
+> Is the reader going to READ this, or USE it?
+
+Read means they take it in once, in order, and are done: an explanation, a recommendation, an
+answer with one part. Use means they will come back to it, look for one piece of it, compare two
+of its pieces, change an input, or act on it — and every one of those is something prose cannot do
+and a card can. **When the answer is "use", the card is the deliverable and the prose is the
+caption.** Two sentences of what you found, then the thing.
+
+Three thoughts predictably get this wrong, and all three are about you rather than the reader:
+\`they asked a question, so I should answer it\` — you are, and how it is delivered is your call;
+\`this is a quick one\` — quick describes writing it, not using it; \`they did not ask for a card\` —
+they cannot ask for what they do not know is available, and in the whole measured corpus the users
+who got one never asked, while the ones who did had already been given prose first and were asking
+for it a second time.
+
+
+**A diff, a log, a config file — anything the reader will look THROUGH rather than read — is the
+same call.** \`最近改了啥\`, \`这个文件给我看看\`, \`报错日志是什么\`: the answer is a body of text with
+structure inside it, and prose about it plus a fenced dump is the worst of both — the fence has no
+highlighting, no folding, and no way to jump to the part they wanted. Measured: on a question
+asking what a commit changed, **0 of 24 answers built anything**, across six models, while the same
+models built cards for lists all day. A diff viewer that colours the hunks, folds the files, and
+lets them open one is a card; \`shiki\` does the colouring in about ten lines. **The reflex to catch
+is that code feels like it "is already text"** — so does a table, and the reason it wants a card is
+the same: the reader is looking for one part of it.
+
+**A card the reader has to scroll to see the shape of has hidden its own structure.** Aim for the
+unopened card to sit inside roughly two thirds of the viewport — not as a CSS \`max-height\`, which
+just moves the problem into an inner scrollbar, but as the size you are budgeting for while you
+decide what starts open. Estimate it the way you would a page: a row is ~40px, a heading block
+~80px, a paragraph of body text ~60px. Twenty rows with their descriptions showing is already past
+it before you have written the header.
+
+**The moment to act on this is when you write \`.map\`, not when you finish.** Measured across two
+waves of real cards: at 320px wide, **90% render past 60vh and a fifth past two full screens**,
+median 950px — and saying "budget for two thirds of a viewport" changed that by one point, because
+by the time a card feels long it is written. So make it a rule about the code: **a \`.map\` over
+more than about eight items renders those items COLLAPSED**, one line each, with the body behind
+a \`Disclosure\`; and the filter above it starts on a real subset, never on "all". If you cannot
+decide which subset, that is the card telling you it needs a search box, not that it needs to show
+everything.
+
+What that budget buys is **hierarchy, which is contrast, not just order**. A title, a set of
+counts, and a row of filters stacked as three bands of the same grey with the same rounding and
+the same text size is three rows the eye cannot rank — the reader sees a wall and starts reading
+from the top, which is the thing a card exists to avoid. Rank them: the title carries weight and
+size, ONE control is the primary (filled, the accent colour) and its siblings are quiet (text or
+outline), counts are secondary text next to what they count rather than another band of chips.
+**When every element is emphasised nothing is** — pick the one thing the reader looks for first
+and let it be the only loud thing on the row.
 
 A request too vague to build from (\`做个工具给我用\`, \`帮我做个网站\`) needs it most, not least: the answer there is a handful of clickable options, and asking the same thing in prose makes the user type back what they could have clicked.
 
@@ -1128,10 +1538,34 @@ thirty seconds, before anything is loaded.
   \`Bot\`, \`BrainCircuit\`, \`Zap\` beside a heading say "an AI made this" and nothing else. An icon earns
   its place by naming the thing it sits next to — \`Copy\` on a copy button, \`Languages\` on a translate
   tab. A heading that reads fine without one takes none.
-- **Do not wrap the whole card in a tinted, bordered, rounded box by reflex.** Inside a canvas
-  that box is a frame inside the panel's own frame. Inline, ONE bounded box is right — but the
-  reflex is to give every block inside it another, and a bordered box inside a bordered box is
-  almost always wrong. A divider or a gap does that job.
+- **One bounded box, and lines inside it.** Inline, the card's own root is that box; inside a
+  canvas the panel already drew it, so the root takes none. Everything below the root separates
+  with a rule or a gap:
+
+      <div className="bg-layer border border-line rounded-lg p-4 divide-y divide-line">
+        <section className="py-3 first:pt-0 last:pb-0">…</section>
+        <section className="py-3 first:pt-0 last:pb-0">…</section>
+      </div>
+
+  **The check is countable, so run it: walk up from any element and count the ancestors that repeat
+  the box recipe — a border or a \`bg-layer*\`, plus \`rounded\`, plus a \`p-*\` — counting the one you
+  are inside. Three is already a frame around a frame; four means one of them is doing nothing.**
+  Prose alone has been here since the first round and \`hierarchy\` is the dimension the panel moves
+  least on (+0.18 ± 0.20 across r001→r002, which is nothing) — because
+  "one bounded box" reads as satisfied at every level, since each level is one box from inside
+  itself. Read off the syntax tree of 755 cards: **216 (29%) stack three of these boxes**, and 41
+  (5.4%) stack four or more. The deepest is five —
+
+      bg-layer border border-line rounded-lg p-4 → bg-page border border-line-2 rounded-md p-3
+        → border border-line rounded bg-layer p-3 → bg-layer-2 border border-line rounded p-2
+        → text-[10px] p-1 rounded bg-page border border-line
+
+  — each adding two to four pixels of padding and a one-pixel line, until the innermost box holds
+  less content than frame. Grounds stack the same way and go deeper: the worst runs \`bg-layer\` →
+  \`bg-page\` → \`bg-layer\` → \`bg-layer\` → \`bg-layer\` → \`bg-page\`, six deep, and the three in the
+  middle are the same colour — a container that changes the ground to the ground it already had.
+
+  A block that feels like it needs its own border wants a heading.
 
 
 ## Weight
@@ -1206,6 +1640,15 @@ written \`@[30rem]:\`:
 
     <div className="grid grid-cols-1 gap-3 @[30rem]:grid-cols-2">
 
+**Spend the width on the ROW, not inside it.** This is the half that gets missed: 71% of measured
+cards carry a real breakpoint, and a vision panel still called out wasted width in **27% of its
+verdicts** — because the prefixes went on padding, gaps and font sizes while the list itself stayed
+one column at every width. Its words for the result: *"餐名与右侧热量标签间距过宽、视线脱节"* — a
+name on the far left and its number on the far right, 700 pixels apart, on a row that should have
+become two columns. **Before the small stuff, ask what the LIST does with the extra width**: a run
+of items with a label and a value is \`@[30rem]:grid-cols-2\`; a row of three bands is
+\`@[32rem]:grid-cols-[1fr_auto_auto]\` so the three sit on one line instead of stacking.
+
 **Reflowing text is not a responsive layout, and it is what you ship when you write no prefix at
 all.** A card with no breakpoint still "works" at every width — the text simply wraps — so nothing
 looks broken while you write it, and the failure only shows in a screenshot. Measured on one card
@@ -1278,7 +1721,7 @@ One value that fits your longest label today is a value that stops fitting when
 **And a number column wants \`text-right\`, not \`text-center\`.** \`tabular-nums\` makes every digit
 the same width so figures stack — and centring throws that away, because \`5\` and \`25\` then sit at
 different right edges. The two belong together: \`text-right tabular-nums\`, in a fixed track.`;
-var EXEC_BULLET = `- \`import { bash } from "$dsh/exec"\` runs one command in the workspace and resolves with \`{stdout, stderr, exitCode}\`, under the session's own sandbox mode. **A non-zero exit resolves — check \`exitCode\`, do not catch it.** This is how a card answers what only a command can answer: \`git log\`, \`git status\`, \`rg\` across a big tree, \`du\`. **Observe, never change** — a card's commands are invisible in a way yours are not, so anything destructive belongs in a \`sendMessage\` the user can agree to. Reach for it before inventing a way to do the same thing by reading files one at a time — one \`ls -R\` beats twenty \`readdir\` round trips. Commands are killed after 15 seconds, so nothing that watches or serves.`;
+var EXEC_BULLET = `- \`import { bash } from "$dsh/exec"\` runs one command in the workspace and resolves with \`{stdout, stderr, exitCode}\`, under the session's own sandbox mode. **A non-zero exit resolves — check \`exitCode\`, do not catch it.** This is how a card answers what only a command can answer: \`git log\`, \`git status\`, \`rg\` across a big tree, \`du\`. **Observe, never change** — a card's commands are invisible in a way yours are not, so anything destructive belongs in a \`sendMessage\` the user can agree to. Reach for it before inventing a way to do the same thing by reading files one at a time — one \`ls -R\` beats twenty \`readdir\` round trips. Commands are killed after 15 seconds, so nothing that watches or serves. **It is also the answer whenever \`$dsh/fs\` has no verb for what you need**: searching a tree (\`rg\`, \`fd\` — there is no find API and a recursive \`readdir\` walk is not one), running the project's own \`lint\` / \`check\` / tests and showing the rows, or deriving a file from another (\`sips\`, \`magick\`) instead of moving megabytes through the browser.`;
 var EXEC_HISTORY = `**A history is a set too.** 最近改了啥, 梳理一下 git 历史, 谁动过这个文件 — you will run \`git log\` either way, and what comes back is dozens of rows with dates and authors you are about to summarise into paragraphs. Summarising throws away the rows. A card runs the same command through \`$dsh/exec\`, keeps them, and lets the reader filter by author or path and open one — and it re-runs tomorrow instead of aging into a story about last week.`;
 
 // src/index.ts
@@ -1286,7 +1729,7 @@ var name = "dsh-generative-ui";
 var inject = ["systemPrompt"];
 var SETTINGS_NAMESPACE = settingsNamespace("dsh-generative-ui");
 var Config = z.object({
-  allowExec: z.boolean().default(false).description("Let generated cards run shell commands through `$dsh/exec`. A card is model-written code running in your browser; leave this off unless you want that.")
+  allowExec: z.boolean().default(true).description("Let generated cards run shell commands through `$dsh/exec`, under this session's own sandbox mode. Cards use it to search (`rg`, `fd`), run `lint`/`check`, and read `git`. The sandbox still applies; what does not is the per-command approval prompt, so turn this off for a session where that matters.")
 });
 var wasmFile = (importMetaUrl) => createRequire(importMetaUrl).resolve("@esm.sh/tsx/pkg/tsx_bg.wasm");
 var resolvedMap = (relative, importMetaUrl) => {
@@ -1553,6 +1996,18 @@ function apply(ctx, config = Config({})) {
 }
 function applyWith(ctx, allowExec) {
   ctx.effect(() => ctx.systemPrompt.section({ name: PROMPT_SECTION_NAME, order: PROMPT_SECTION_ORDER, text: inlinePrompt(allowExec) }), "dsh-generative-ui: inline prompt");
+  const failures = new CardFailures;
+  ctx.effect(() => ctx.systemPrompt.context({ name: CARD_FAILURE_CONTEXT, order: CARD_FAILURE_CONTEXT_ORDER, text: (assembly) => failures.text(assembly.agent?.id) }), "dsh-generative-ui: card failure context");
+  let wake = null;
+  ctx.inject(["agents"], (withAgents) => {
+    wake = (session) => {
+      const agent = withAgents.agents.get(session);
+      agent?.followup(createUserMessage({ content: [{ type: "text", text: WAKE_TEXT }], source: { kind: "plugin", plugin: "dsh-generative-ui", form: "notice", summary: WAKE_SUMMARY } }));
+    };
+    return () => {
+      wake = null;
+    };
+  });
   ctx.inject(["webServer", "sessions"], (scoped) => {
     const file = wasmFile(import.meta.url);
     const liveWorkspaces = () => {
@@ -1561,6 +2016,7 @@ function applyWith(ctx, allowExec) {
     };
     scoped.effect(() => scoped.webServer.register({ kind: "prefix", path: ASSET_PREFIX, handler: (req, res) => serveAsset(req, res, file) }), "dsh-generative-ui: tsx wasm");
     scoped.effect(() => scoped.webServer.register({ kind: "exact", path: CANVAS_READ_PATH, handler: (req, res) => serveCanvas(liveWorkspaces, req, res) }), "dsh-generative-ui: canvas reads");
+    scoped.effect(() => scoped.webServer.register({ kind: "exact", path: CARD_ERROR_PATH, handler: (req, res) => serveCardError(failures, () => wake, req, res) }), "dsh-generative-ui: card failures");
     scoped.inject(["fs", "sandboxPolicy"], (withFs) => {
       withFs.effect(() => withFs.webServer.register({ kind: "exact", path: FS_PATH, handler: (req, res) => serveFs(withFs, liveWorkspaces, req, res) }), "dsh-generative-ui: workspace files");
     });
@@ -1576,9 +2032,41 @@ function applyWith(ctx, allowExec) {
     });
   });
   ctx.inject(["skills"], (scoped) => {
-    scoped.effect(() => scoped.skills.register({ name: SKILL_NAME, description: SKILL_DESCRIPTION, content: skillBody(typesImportMap(import.meta.url), standaloneImportMap(import.meta.url)), source: "runtime", invocation: { modelInvocable: true, userInvocable: false } }), "dsh-generative-ui: skill");
+    scoped.effect(() => scoped.skills.register({
+      name: SKILL_NAME,
+      description: SKILL_DESCRIPTION,
+      content: skillBody(typesImportMap(import.meta.url), standaloneImportMap(import.meta.url), allowExec),
+      source: "runtime",
+      invocation: { modelInvocable: true, userInvocable: false }
+    }), "dsh-generative-ui: skill");
   });
 }
+async function serveCardError(failures, wake, req, res) {
+  if (req.method !== "POST")
+    return void res.writeHead(405).end();
+  const url = new URL(req.url ?? "", "http://localhost");
+  const session = url.searchParams.get("session");
+  if (session === null || session === "")
+    return void res.writeHead(400).end();
+  let body = "";
+  for await (const chunk of req) {
+    body += chunk;
+    if (body.length > MAX_BODY)
+      return void res.writeHead(413).end();
+  }
+  let report;
+  try {
+    report = JSON.parse(body);
+  } catch {
+    return void res.writeHead(400).end();
+  }
+  if (report.message === undefined || report.message === "") {
+    failures.clear(session);
+  } else if (failures.set(session, { message: report.message, phase: report.phase ?? "compile" })) {
+    wake()?.(session);
+  }
+  res.writeHead(204).end();
+}
 export {
   ASSET_PREFIX,
   Config,
@@ -1591,6 +2079,7 @@ export {
   serveAi,
   serveAsset,
   serveCanvas,
+  serveCardError,
   serveExec,
   serveFs,
   serveWebSearch