dsh-claude-data 0.0.0-stage → 2.14.0

package/skills/claude-data/artifact-type/reference/visual-short-script.md

@@ -0,0 +1,146 @@
+# A Visual short's skeleton: the script
+
+Goes with the HTML and CSS in `artifact-type/reference/visual-short-skeleton.md`,
+as `files/vs.js`.
+Yours to write: the calcs, `fmt`, a `dash.draw` per chart and `scenes`. The rest
+is the engine: copy it as it stands, unless
+the person asks for something it doesn't do.
+
+```js
+// Figures as the captions say them: rounded for the ear, still numbers from the data, so the mark check compares them.
+dash.calc('said', {inputs: ['orders'], title: 'Figures as the captions say them', description: 'Rounded to two significant figures.',
+  fn: (orders) => orders.map((r) => ({channel: r.channel, cost: r.cost == null || !Number.isFinite(+r.cost) ? null : +(+r.cost).toPrecision(2)}))});
+
+const root = document.querySelector('#dash-root'), vs = root.querySelector('.vs'), stage = vs.querySelector('.vs-stage');
+const [chs, caps, mks] = ['.vs-ch', '.vs-cap', '.vs-mk'].map((q) => [...vs.querySelectorAll(q)]); // one of each, and one scene, per chapter
+const still = matchMedia('(prefers-reduced-motion: reduce)');
+const words = (el) => el.textContent.replace(/\s+/g, ' ').trim();
+const write = (el, s) => { if (el && el.textContent !== s) el.textContent = s; }; // text only when it changes
+const says = (i) => [...(caps[i]?.querySelectorAll('.vs-s:not([hidden])') ?? [])]; // a chapter's sentences, less any the data ruled out
+const called = (i) => ['.vs-label', 'h1, h2, h3'].map((q) => chs[i]?.querySelector(q)).map((el) => (el ? words(el) : '')).find(Boolean) ?? String(i + 1);
+// How a figure is written, by source and field; any other as it comes.
+const fmt = {'orders.cost': d3.format('$,.2f'), 'said.cost': d3.format('$,~f')};
+let said = [], durs = [], cur = 0, t = Infinity, playing = false, begun = false, raf = 0, last = 0, heard = null, was = null, pace = 1;
+const phase = () => root.getAttribute('data-dash-read-phase'); // there while a reading is open, and for a moment as a reader edits by hand
+
+// While a reading is open every time is scaled by `pace`: how long the voice took over the last caption it read through, against 15 characters a second.
+const paced = (at) => (phase() ? at * pace : at);
+// The second at which the mark named by `word` arrives in chapter i: where the word starts in the caption; 0 if it isn't there.
+const cue = (i, word) => paced(Math.max(0, said[i].indexOf(word)) / 15);
+// How far a move that starts at second `from` has got at time t, 0 to 1.
+const moved = (t, from, len = 0.6) => d3.easeCubicOut(Math.max(0, Math.min(1, (t - from) / len)));
+// A figure that counts up: `real` is marked and keeps its value; `copy` (data-draw="copy", unmarked, aria-hidden) lies over it and counts.
+const places = (v) => { const [m, e = 0] = String(v).split('e'); return Math.min(100, Math.max(0, (m.split('.')[1] ?? '').length - e)) || 0; };
+const shown = (s) => (String(s).match(/\.(\d+)/)?.[1] ?? '').length; // the decimals in a figure as written
+const count = (real, copy, p, value, f) => {
+  real.style.opacity = p < 1 ? 0 : 1; copy.style.opacity = p > 0 && p < 1 ? 1 : 0;
+  if (p >= 1) return;
+  let s = f(value * p); // on the way it is never written with more decimals than the finished figure
+  if (shown(s) > shown(f(value))) s = f(+(value * p).toFixed(places(value)));
+  write(copy, s);
+};
+
+// One per chart: make its elements from its rows, whole, and leave a — when there are none or the status isn't "ok"; fill each mark it makes with fig(mark), but no header cell, which is a label. Runs on new data and on a new width.
+dash.draw('d1', (el) => { /* el.replaceChildren(...) */ });
+// One function per chapter. It finds what the drawings made at each call, skips what is missing, sets styles from t and makes nothing; t = Infinity is the chapter whole. Take every time from cue(), so that a voice's pace reaches it.
+const scenes = [(t) => { /* for (const bar of chs[0].querySelectorAll('.bar')) bar.style.width = bar.dataset.share * moved(t, cue(0, 'email')) * 100 + '%' */ }];
+
+function fig(el) { // the one place marked text is written: fills one mark, its row found as the dashboard finds it
+  const dec = (s) => { try { return decodeURIComponent(s); } catch { return s; } };
+  const {source, field, where, row: n} = el.dataset, d = dash.data(source), rows = d.status === 'ok' && Array.isArray(d.data) ? d.data : [];
+  const row = where == null ? rows[+(n ?? 0)] : rows.find((r) => where.split('&').every((p) => {
+    const i = p.indexOf('='); return i > 0 && String(r[dec(p.slice(0, i)).trim()] ?? '') === dec(p.slice(i + 1)); }));
+  const v = row?.[field];
+  write(el, v == null || v === '' ? '—' : (fmt[source + '.' + field] ?? String)(v));
+}
+dash.draw('fig', fig); // every marked figure in the HTML is data-draw="fig"
+for (const name of ['runs', 'now', 'copy']) dash.draw(name, () => {}); // drawings the engine writes in at its own times
+const due = new Map(); // the second each sentence starts at, by its span; not a property of the span, since Safari has a span.cue of its own
+function timing() { // after the figures: filling moves where the words fall
+  said = chs.map((_, i) => says(i).map(words).join(' ')); durs = said.map((s) => s.length / 15 + 1);
+  chs.forEach((_, i) => { let at = 0; for (const s of says(i)) { const w = words(s), j = said[i].indexOf(w, at); due.set(s, (j < 0 ? at : j) / 15); if (j >= 0) at = j + w.length; } });
+  write(vs.querySelector('.vs-runs'), String(Math.round(d3.sum(durs) / 5) * 5));
+}
+function draw(i, t) {
+  scenes[i]?.(still.matches || t >= paced(durs[i]) ? Infinity : t); // under reduced motion the drawing is whole, and the sentences still take their turns
+  const ss = says(i), k = begun ? ss.findLastIndex((s) => t >= paced(due.get(s))) : 0; // the sentence being said; before the first Play, the first
+  ss.forEach((s, j) => s.classList.toggle('vs-on', j === Math.max(0, k)));
+}
+function frame() {
+  draw(cur, t);
+  mks.forEach((m, j) => { for (const bar of m.children) bar.style.width = (j < cur ? 1 : j > cur ? 0 : t === Infinity ? +begun : Math.min(1, t / paced(durs[cur]))) * 100 + '%'; }); // whole: full, but for the title before the first Play
+}
+function show(i, from) {
+  if (i !== cur) { draw(cur, Infinity); if (!phase()) write(vs.querySelector('.vs-now'), called(i)); } // what leaves is left whole: its marks are still checked
+  [cur, t] = [i, from];
+  for (const set of [chs, caps]) set.forEach((el, j) => el.classList.toggle('vs-on', j === i));
+  chs.forEach((ch, j) => ch.setAttribute('aria-hidden', String(j !== i))); // not the captions: Listen skips what is aria-hidden
+  for (const set of [mks, caps]) set.forEach((el, j) => (j === i ? el.setAttribute('aria-current', 'true') : el.removeAttribute('aria-current')));
+  mks.forEach((m, j) => m.getAttribute('aria-label') === called(j) || m.setAttribute('aria-label', called(j))); // so that a hand edit of the label reaches the chapter mark
+  frame();
+}
+function tick(now) {
+  raf = 0;
+  if (!vs.isConnected || (phase() ? phase() !== 'playing' : !playing)) return;
+  t += last ? Math.min(0.1, (now - last) / 1000) : 0; last = now;
+  if (phase() || t < durs[cur]) frame(); // in a reading the chapter waits, whole, for the voice, and the clock runs on to time it
+  else if (cur < chs.length - 1) show(cur + 1, 0);
+  else return play(false);
+  raf = requestAnimationFrame(tick);
+}
+const kick = () => { if (!raf) { last = 0; raf = requestAnimationFrame(tick); } };
+function look() { const on = phase() ? /starting|playing/.test(phase()) : playing; vs.classList.toggle('vs-playing', on); vs.querySelector('.vs-controls .vs-toggle')?.setAttribute('aria-label', on ? 'Pause' : 'Play'); } // Play or Pause by the voice's phase, or by the page's own clock when there is no voice; the dashboard reads vs-playing too
+function play(on) { playing = on; begun ||= on; look(); frame(); if (on) kick(); }
+// While a reading is open, the dashboard hears the same presses (data-read-pause, data-read-move) and the voice keeps time: a press here shows its chapter, and starts and stops no clock.
+const from = (i) => (show(Math.max(0, Math.min(chs.length - 1, i)), 0), phase() || play(true));
+const on = (q, f) => { const b = vs.querySelector('.vs-controls ' + q); if (b) b.onclick = f; }; // a piece may leave a control out
+on('.vs-toggle', () => phase() || (playing ? play(false) : t < durs[cur] ? play(true) : from(cur === chs.length - 1 ? 0 : cur)));
+on('.vs-back', () => from(cur - 1));
+on('.vs-next', () => from(cur + 1));
+mks.forEach((m, j) => (m.onclick = () => from(j)));
+on('.vs-cc', (e) => e.currentTarget.setAttribute('aria-pressed', String(!vs.classList.toggle('vs-hush')))); // captions on or off, until the page is loaded again
+// vs-idle: a mouse still for 3 s counts as gone, unless its last move was onto the controls (vs-held); vs-touch: a finger or pen, which may leave no hover, counts as on the stage
+stage.onpointermove = stage.onpointerdown = (e) => {
+  const m = e.pointerType === 'mouse', move = e.type === 'pointermove', l = stage.classList;
+  if (move && Math.abs(e.clientX - stage.x) + Math.abs(e.clientY - stage.y) < 4) return; // no move: a click can drift a pixel, and a still mouse gets a move when the page changes under it
+  [stage.x, stage.y] = [e.clientX, e.clientY];
+  l.toggle('vs-idle', false); l.toggle('vs-touch', !m); l.toggle('vs-held', move && !!e.target.closest('.vs-controls'));
+  clearTimeout(stage.idle); if (m) stage.idle = setTimeout(() => l.add('vs-idle'), 3000);
+};
+still.onchange = () => (vs.isConnected ? frame() : (still.onchange = null)); // switched while paused in mid-chapter
+
+const mo = new MutationObserver(() => {
+  if (!vs.isConnected) return mo.disconnect();
+  const now = vs.querySelector('[data-dash-read-now]'), p = phase(), again = p === 'starting' && was !== 'starting'; // each start reads its caption from the top
+  const through = heard && p === 'playing' && was === 'playing'; // the voice went on by itself, so t is how long the caption took
+  const before = was; was = p;
+  if (!p) { if (heard) t /= pace; heard = null; if (before) play(/starting|playing/.test(before)); return; } // the voice is off: go on without it from here, playing if it was starting or playing
+  playing = false; begun = true; look(); // the voice keeps time now
+  write(vs.querySelector('.vs-now'), ''); // else a later move to the chapter it names would not be announced, since write() skips unchanged text
+  if (now && (now !== heard || again)) {
+    if (through) pace = Math.max(0.5, Math.min(1.5, t / (durs[cur] - 1) || 1));
+    const i = caps.indexOf((heard = now));
+    if (i >= 0) show(i, 0); // a stamp on anything but a caption moves nothing
+  }
+  if (p === 'ended') show(cur, Infinity); // read to its end, or a reader edits by hand: whole
+  kick();
+});
+mo.observe(root, {subtree: true, attributes: true, attributeFilter: ['data-dash-read-phase', 'data-dash-read-now']});
+
+// Lays each caption over the row its chapter keeps for it under the headline; with no row, over the top of the drawing.
+function seat() {
+  const top = vs.querySelector('.vs-in').getBoundingClientRect().top;
+  chs.forEach((ch, i) => { const row = ch.querySelector('.vs-say, .vs-draw'); if (row && caps[i]) caps[i].style.top = row.getBoundingClientRect().top - top + 'px'; }); // a person may have deleted either
+  if (durs.length) frame();
+}
+
+let box = vs.parentElement; // the box the page scrolls in
+while (box.parentElement && !/auto|scroll/.test(getComputedStyle(box).overflowY)) box = box.parentElement;
+const fit = () => vs.style.setProperty('--room', Math.max(240, box.getBoundingClientRect().bottom - box.scrollTop - vs.getBoundingClientRect().top
+  - parseFloat(getComputedStyle(root).paddingBottom) - parseFloat(getComputedStyle(box).paddingBottom)) + 'px'); // the box may be padded for a bar that floats over its foot
+const ro = new ResizeObserver(() => (vs.isConnected ? (fit(), seat()) : ro.disconnect())); for (const el of [box, stage, ...vs.querySelectorAll('.vs-draw')]) ro.observe(el); // the stage too: when only its width changes, the dashboard draws each chart again, whole, without settle, and this puts the chapter showing back at t; each drawing's box, which changes height when a headline above it rewraps, as under Translate
+document.fonts.ready.then(() => vs.isConnected && seat()); // a web font that comes late moves the rows
+
+dash.onData(fit);
+dash.draw('settle', () => { timing(); show(cur, t); seat(); }); // the last drawing in the HTML, so it runs once the others have
+```

package/skills/claude-data/artifact-type/reference/visual-short-skeleton.md

@@ -0,0 +1,131 @@
+# A Visual short's skeleton: HTML and CSS
+
+Working HTML and CSS that, with the script in
+`artifact-type/reference/visual-short-script.md`, already do the engine's
+part of `visual-short.md`: one writer for each part, the fit, the
+containers, filling each marked figure, cues worked out after filling, one
+clock, keeping step with Listen, captions that have a row of their own, and the
+controls. Start from them and change whatever the piece needs,
+keeping the class names the script looks for. What is left to write is the piece
+itself: the chapters and captions, the calcs, a `dash.draw` per chart, one
+function in `scenes` per chapter, `fmt`, and the look of the drawings.
+
+## One reply has a limit
+
+One reply of yours can only be so long, thinking included, and a call that the
+limit cuts short is never run: all of it is lost. Thinking is often the larger
+part of a long reply. Calls sent together are still one reply; your next reply
+starts once they have been answered. A Visual short planned and written in one
+reply can come near the limit, so it need not be the one batch of `SKILL.md`'s
+step 3. Whether to split the writes, and how, is yours to judge.
+
+The code is three files: `files/vs.css`, the CSS below and the look of your
+drawings; `files/vs.js`, the script; and `files/index.html`, the HTML below,
+which names them. A remix writes them under its draft, as
+`artifact-type/reference/remix.md` says.
+
+However you write the piece:
+
+- **The script is best left as one file.** A page's scripts each run in a scope
+  of their own and this script's parts share names, so two files would need all
+  of those on `window`.
+- **Each file written draws an open page again, and the page is checked as it
+  then stands.** Stored before its script, `index.html` shows the person an
+  unfinished page and can fail the check. On a new dashboard, once a file lands
+  more than a few seconds after `index.html`, the check stops listing errors
+  left uncaught in a timer, a listener or a promise. Until the last file is in,
+  the check says nothing of the finished page, so read it after that write. A
+  new dashboard with no `index.html` says it is missing once your turn ends.
+- **A later change that touches several files goes as one batch**, so that
+  nobody sees half of it. In one too long for a reply, each write shows at once
+  to everyone looking at that page, and a file `index.html` names that isn't
+  there yet is left out, with no note on the page. Read its check only after the
+  last write.
+
+```html
+<meta name="dash-one-writer">
+<link rel="stylesheet" href="vs.css">
+<div class="vs">
+  <section class="vs-stage" data-read-stage><div class="vs-in">
+    <div class="vs-chapters">
+      <article class="vs-ch">
+        <p class="vs-label">Part of the story</p>
+        <h2>A sentence that states the finding</h2>
+        <div class="vs-say"></div><!-- on every chapter, and empty: the row where the script lays its caption -->
+        <div class="vs-draw"><div data-draw="d1" data-source="orders"></div></div><!-- a chart is a drawing, stored empty; words and single figures beside it are HTML, each figure data-draw="fig" -->
+        <p class="vs-src">Measure, who, dates. Runs about <span class="vs-runs" data-draw="runs">—</span> seconds.</p>
+      </article>
+      <!-- one .vs-ch per chapter; only the first, the title, has "Runs about … seconds." -->
+    </div>
+    <div class="vs-caps" data-read lang="en"><!-- lang: the language the captions are written in -->
+      <p class="vs-cap" data-read-step><span class="vs-s">An email order cost about <span data-draw="fig" data-source="said" data-field="cost" data-where="channel=Email">—</span>.</span> <span class="vs-s">The next sentence.</span></p>
+      <!-- one .vs-cap per chapter, in the same order; one .vs-s per sentence; nothing else in here: whatever is, is read aloud too -->
+    </div>
+    <div class="vs-line">
+      <button class="vs-mk" data-read-move aria-label="Part of the story"><i></i></button>
+      <!-- one .vs-mk per chapter, in the same order, named for its label; the script names it again, in case the label has been edited since -->
+    </div>
+    <div class="vs-controls">
+      <button class="vs-toggle" data-read-pause aria-label="Play"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M6.44 3.682L11.59 6.765C12.022 7.024 12.286 7.497 12.286 8C12.286 8.503 12.022 8.976 11.59 9.235L6.44 12.318C6.241 12.437 6.014 12.5 5.782 12.5C5.074 12.5 4.5 11.926 4.5 11.218L4.5 4.782C4.5 4.074 5.074 3.5 5.782 3.5C6.014 3.5 6.241 3.563 6.44 3.682Z"/></svg><svg viewBox="0 0 16 16" aria-hidden="true"><rect x="3.5" y="3.5" width="3" height="9" rx=".75"/><rect x="9.5" y="3.5" width="3" height="9" rx=".75"/></svg></button>
+      <button class="vs-back" data-read-move aria-label="Back"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M10 3.5L5.5 8L10 12.5"/></svg></button><button class="vs-next" data-read-move aria-label="Next"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M6 3.5L10.5 8L6 12.5"/></svg></button>
+      <button data-read-sound aria-label="Read aloud" aria-pressed="true"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M12.9 5.5C13.284 6.25 13.5 7.1 13.5 8C13.5 8.9 13.284 9.75 12.9 10.5M10.599 6.5C10.854 6.941 11 7.454 11 8C11 8.546 10.854 9.059 10.599 9.5M8.5 12.899C8.5 13.328 8 13.558 7.671 13.275L4.783 10.748C4.6 10.588 4.367 10.5 4.124 10.5L3.5 10.5C2.948 10.5 2.5 10.053 2.5 9.5L2.5 6.75M5.768 4.391L7.671 2.726C8 2.443 8.5 2.672 8.5 3.102L8.5 7.25M2.5 4L11 12.5"/></svg><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M12.9 5.5C13.284 6.25 13.5 7.1 13.5 8C13.5 8.9 13.284 9.75 12.9 10.5M10.599 6.5C10.854 6.941 11 7.454 11 8C11 8.546 10.854 9.059 10.599 9.5M3.5 5.5L4.124 5.5C4.366 5.5 4.6 5.412 4.783 5.253L7.671 2.726C8 2.443 8.5 2.672 8.5 3.102L8.5 12.899C8.5 13.328 8 13.558 7.671 13.275L4.783 10.748C4.6 10.588 4.367 10.5 4.124 10.5L3.5 10.5C2.948 10.5 2.5 10.053 2.5 9.5L2.5 6.5C2.5 5.948 2.948 5.5 3.5 5.5Z"/></svg></button><!-- on at first, struck out once the voice is off. The dashboard keeps aria-pressed, and hides the button where there is no voice -->
+      <button class="vs-cc" aria-label="CC, captions" aria-pressed="true">CC</button>
+    </div>
+    <p class="vs-now" aria-live="polite" data-draw="now"></p>
+  </div></section>
+  <i data-draw="settle"></i><!-- keep it last: drawings run in order, and this one needs the others filled -->
+</div>
+<script src="vs.js"></script>
+```
+
+```css
+.vs, .vs-stage { container-type: inline-size; }
+.vs-stage { box-sizing: border-box; aspect-ratio: 16 / 9; width: min(100%, calc(var(--room, 70dvh) * 16 / 9)); margin-inline: auto; overflow: clip;
+  background: var(--color-panel); border: 1px solid var(--color-border-line); border-radius: var(--cds-radius); }
+@container (max-width: 800px) { .vs-stage { aspect-ratio: 1; width: min(100%, var(--room, 70dvh)); } }
+@container (max-width: 560px) { .vs-stage { aspect-ratio: 4 / 5; width: min(100%, calc(var(--room, 70dvh) * 4 / 5)); } }
+.vs-in { box-sizing: border-box; height: 100%; padding: 0 3.6cqi 3cqi; display: grid; grid-template-rows: auto minmax(0, 1fr); position: relative; }
+.vs-chapters { display: grid; box-sizing: border-box; isolation: isolate; } /* isolated, or a z-index in a drawing lifts it over the caption and the controls */
+.vs-in, .vs-chapters, .vs-ch { grid-template-columns: minmax(0, 1fr); } /* Without this, one wide child widens every column. */
+.vs-ch, .vs-cap { margin: 0; opacity: 0; transition: opacity 400ms var(--cds-ease-out); }
+.vs-ch.vs-on, .vs-cap.vs-on { opacity: 1; } .vs-ch:not(.vs-on) { pointer-events: none; }
+.vs-ch { grid-area: 1 / 1; display: grid; grid-template-rows: auto auto auto minmax(0, 1fr) auto; }
+.vs-say { grid-row: 3; } .vs-draw { grid-row: 4; } .vs-src { grid-row: 5; } /* by name: a chapter that has lost a row keeps its drawing's */
+.vs-draw { container-type: size; display: flex; flex-direction: column; justify-content: safe center; font-size: max(12px, 1.8cqi); } /* a container of its own: inside it, cqh is 1% of the drawing's height, which comes from .vs-ch's 1fr row, not from what it holds */
+/* The chapter marks: a band of bars across the top of the stage, which stays up. Each is a button as tall as the band that draws a 3px bar. --marks is the band's height, --row the controls', --ctl their width. */
+.vs-in { --marks: max(24px, 4cqi); --row: 32px; --ctl: 176px; }
+@media (pointer: coarse) { .vs-in { --marks: max(32px, 4cqi); --row: 52px; --ctl: 240px; } }
+.vs-line { grid-area: 1 / 1; height: var(--marks); display: flex; gap: 6px; }
+.vs-mk { flex: 1; min-inline-size: 0; position: relative; display: flex; align-items: center; padding: 0; border: 0; background: none; cursor: pointer; forced-color-adjust: none; outline-offset: -3px; } /* the stage would clip a focus ring drawn outside it */
+.vs-mk::before { content: ''; position: absolute; inset-inline: 0; background: var(--cds-chart-muted); }
+.vs-mk i { position: relative; display: block; width: 0; background: var(--color-fg); }
+.vs-mk::before, .vs-mk i { height: 3px; border-radius: 3px; }
+@media (forced-colors: active) { .vs-mk::before { background: GrayText; } .vs-mk i { background: CanvasText; } }
+/* The caption is a line of plain words under the headline, where it covers nothing drawn. Each chapter keeps a row for it, .vs-say, as tall whatever is being said and with captions off,
+   so the drawing never moves; the script lays the caption over that row. It is placed against .vs-in, so .vs-caps must stay unpositioned. Presses pass through it. */
+.vs-chapters, .vs-caps { grid-area: 2 / 1; }
+.vs-caps, .vs-say { font-size: max(14px, 2cqi); line-height: 1.4; }
+.vs-say { block-size: 2lh; } .vs-ch h2 { margin: 0.1em 0 0.3em; } /* the caption stands close under the headline */
+.vs-cap { position: absolute; inset-inline: 3.6cqi; display: grid; font-weight: var(--cds-font-weight-medium); }
+/* One sentence shows at a time. The rest, and all of them with captions off, are hidden from the eye alone. */
+.vs-s { grid-area: 1 / 1; opacity: 0; } .vs-s.vs-on { opacity: 1; }
+.vs-caps { pointer-events: none; } .vs-hush .vs-caps { opacity: 0; }
+/* The controls: bare icons and CC at the top right, on the label's line, away from claude.ai's own bars under the page. On a narrow stage they have a row of their own above the label. */
+.vs-label { margin: 0; padding-block: calc((var(--row) - 1lh) / 2); padding-inline-end: var(--ctl); text-transform: uppercase; } /* one line of it stands level with the controls, and clear of them */
+.vs-controls { position: absolute; inset-block-start: var(--marks); inset-inline-end: calc(3.6cqi - 6px); height: var(--row); display: flex; align-items: center; gap: 8px; } /* 6px out, so that CC's letters end where the marks do */
+/* vs-idle, vs-held and vs-touch come from the script. The controls fade by opacity, not display, so a keyboard and a screen reader still reach them.
+   :focus-visible, not :focus-within: in most browsers a button pressed with the mouse keeps focus, which would hold them up. */
+.vs-controls { transition: opacity 200ms var(--cds-ease-out); }
+@media (hover: hover) { .vs-playing .vs-stage:is(.vs-idle:not(.vs-held), :not(:hover, .vs-touch)):not(:has(:focus-visible)) .vs-controls { opacity: 0; transition: opacity var(--cds-dur-slow) var(--cds-ease-out) 300ms; } }
+@media (prefers-reduced-motion: reduce) { .vs-controls { transition: none !important; } }
+.vs-controls > button { flex: none; height: calc(100% - 8px); min-inline-size: 24px; padding-inline: 6px; font: inherit; font-size: 13px; color: var(--color-fg); background: none; border: 0; border-radius: 6px; cursor: pointer; }
+@media (hover: hover) { .vs-controls > button:hover { background: var(--cds-border); } .vs-mk:hover::before, .vs-mk:hover i { height: 5px; } } /* on touch, hover sticks after a tap */
+.vs-controls > button:has(svg) { display: grid; place-items: center; padding-inline: 4px; }
+.vs-controls svg { grid-area: 1 / 1; inline-size: 16px; block-size: 16px; fill: none; stroke: currentColor; stroke-linecap: round; stroke-linejoin: round; } /* CDS's Play, Pause, CaretLeft, CaretRight, SpeakerSlash and Speaker, 16px, as its Icon draws them: a page has no icon font */
+@media (pointer: coarse) { .vs-controls > button:has(svg) { min-inline-size: 40px; } .vs-controls svg { inline-size: 20px; block-size: 20px; } }
+.vs-cc[aria-pressed="false"] { color: var(--color-fg-muted); text-decoration: line-through; }
+.vs.vs-playing .vs-toggle > :first-child, .vs:not(.vs-playing) .vs-toggle > :last-child { visibility: hidden; }
+[data-read-sound][aria-pressed="true"] > :first-child, [data-read-sound]:not([aria-pressed="true"]) > :last-child { visibility: hidden; }
+@container (max-width: 560px) { .vs-line { gap: 4px; } .vs-say { block-size: 3lh; } .vs-chapters { padding-top: calc(var(--row) + 4px); } .vs-label { padding: 0; } }
+.vs-now { position: absolute; width: 1px; height: 1px; margin: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+```

package/skills/claude-data/artifact-type/reference/visual-short.md

@@ -0,0 +1,63 @@
+# Visual short
+
+A Visual short is a dashboard that plays, for people who would rather watch than read. It tells one finding in a few chapters on one stage, with nothing around it. Each chapter is a drawing that builds while a caption says what it shows, and the whole piece runs a minute or two. It works when one idea is on screen at a time and each mark arrives with the words that name it.
+
+`artifact-type/reference/visual-short-skeleton.md` (HTML and CSS) and `artifact-type/reference/visual-short-script.md` are working code for what follows. Read both before you write, and start from them; what is left is the piece itself.
+
+## Chapters
+
+The script finds elements by class name and pairs them in order: each `.vs-ch` with one `.vs-cap`, one `.vs-mk` and one scene. An empty `.vs-say` in each chapter keeps a row under the headline for the caption to lie over. Without it the caption covers the drawing. A chapter's label names its `.vs-mk` button and, on a wide stage, shares a line with the controls, so every chapter, the title too, has a short one.
+
+The first chapter is the title, which says what the piece is, the period it covers and how long it runs. The piece rests on it, whole, and a thumbnail shows it too. It plays only when someone presses Play or picks a chapter, with the voice or without: motion nobody asked for distracts, and no voice can start before a press. What is faded in the last chapter stays faded, since it stays up when the piece ends.
+
+A waiting chapter is faded with `opacity`, since under `display: none` its drawings measure 0 wide and its marks go unchecked. It is also `aria-hidden` and takes no pointer. None of that stops the keyboard, so nothing in a chapter takes focus: no link, control or `tabindex`.
+
+The dashboard pauses the piece when someone opens Sources, picks a figure there or comments, and has each chapter stand whole while they edit by hand, so the script has no pause of its own for these.
+
+## Drawings and motion
+
+The dashboard compares each rendered mark that names one value with its data, at any opacity and at any moment, so such a mark holds its real value from the first draw. Drawings are made whole, and scenes only style them, but for a number that counts up: that is an unmarked `aria-hidden="true"` copy, a drawing of its own, laid over the marked one, which shows again once the count ends; `count` in the script does this.
+
+Each chapter is a function of its own time `t` in seconds, whole at `t` = `Infinity`, so it can be held, replayed or jumped to. A CSS animation, a transition or a timer can't be, since the engine doesn't know of it. A scene takes each time from `cue(i, word)`, the moment the caption reaches that word, so motion follows the words and, where there is one, a voice's pace. With no voice, a chapter lasts a second for every 15 characters of its caption, plus one. Under `prefers-reduced-motion` the script draws each drawing whole and only the fade moves, while the sentences take their turns. Motion written anywhere but in `scenes` would still play.
+
+A scene sets state such as `class` and `style`, and writes no text or element outside a drawing. Any text or element written under `#dash-root` has the dashboard check every mark again, so a drawing's text is written only when it changes, as `write` in the script does.
+
+The stage is a container, so sizes inside it are in `cqi` (`max(14px, 2cqi)`). Nothing above the page is one, so outside `.vs` `cqi` is the window's. `.vs-draw` is a container of both its sizes. Inside it `cqh` and `cqi` are 1% of its height and width and `1em` is the size of the labels on the marks, and a drawing sized from those fills it, where a fixed number of pixels doesn't. The skeleton sizes only the caption and the drawing. A headline that your CSS doesn't size is 14px, smaller than the caption on a wide stage. `max(18px, 3.4cqi)` suits it, 12cqi a big number and `max(11px, 1.3cqi)` the source line. The longest bar leaves room for its value.
+
+Values are labeled on their marks. Where they don't all fit, the chart gets axis numbers. Every chart gets a tooltip, inside its drawing. A bar or dot painted with `background` vanishes in forced colors unless it has `forced-color-adjust: none` and a system color there, as the skeleton's chapter marks have.
+
+## Captions
+
+Each sentence is its own `.vs-s` span and shows alone, in a row two lines high (three on a narrow stage). One that needs more lines lies over the drawing; under about 100 characters it doesn't.
+
+Captions are hidden by `opacity` alone, so that a screen reader and a voice still get every word. Both lose the words under `display: none`, `visibility: hidden`, `hidden` or `aria-hidden`, and under `display: none` or `hidden` a figure in the caption goes unchecked too. A sentence the data rules out is the one that gets `hidden`: the script leaves it out of the timing and a voice doesn't read it.
+
+Every number in a caption is marked and filled from the data. Words in the HTML reach everyone who opens the dashboard and never change, while each reader's page runs a live query with that reader's own access, unless someone shares its connector. A typed number could show a figure to someone with no access to it, or contradict their own, and it would go stale. A word that turns on the data (up, down, more) is filled too, from a `dash.calc`. What you type is the gist, which holds whatever the numbers turn out to be. A Visual short usually tells of a period that has ended, and unless its queries pin their dates, the numbers move on and the words don't. A certified query keeps its mark whatever its filters are set to, and loses it if its call changes. So its date is pinned by its date filter's value in `dash/params`, which the page first runs with unless a script sets another. One with no date filter can't be pinned, but a query of your own beside it can, and isn't certified.
+
+By default a caption rounds its figures while the stage shows the exact ones. A mark that shows $100 for 102.08 differs from its data, so the rounding is a `dash.calc` and the caption's mark names it (`said` in the script). A calc can return words too ("almost half"), which the dashboard can't check.
+
+## What makes a good one
+
+Suggestions, which give way to what the person asks for.
+
+**The piece.** On the title, the one figure the story turns on can stand under a headline, and how long the piece runs is worked out from the captions, not typed, so it stays true as they change. The last chapter is what to do next, and reads best ending with every mark at full strength, since it stays up. The stage stands alone: tiles, filters, tabs, tables or text around it pull the eye from what is playing.
+
+**A chapter's frame** is the same each time, so only the content changes: a small uppercase label for the part of the story, a one-sentence headline that states the finding and not the topic, one drawing, and a small muted source line (measure, who, dates).
+
+**The drawing** is the one that shows the sentence. A share of people: a 10 by 10 grid of dots that fills, then recolors. A total: one big number that counts, with what made it up beside it. A comparison: horizontal bars from zero, slightly rounded. A gap between two: two bars and a bracket naming the gap. A run of chapters that are all bars is a sign another drawing would fit somewhere. It fills its box, which is most of the stage: bars share its height, each row 100cqh over their number with some air around the bar, and stay bars where they are few; columns stand its full height, less their labels; a dot grid is the largest square it holds, `min(100cqh, 100cqi)` a side. What can't fill the box sits in its middle.
+
+**How marks arrive.** Bars grow from zero, a value fades in once its bar lands, dots come in a quick wave. Quick and eased out (`d3.easeCubicOut`) feels right; camera moves, 3D and bounce pull the eye from it. Marks are `--cds-chart-muted` first, with one accent color on what the sentence is about. To focus, fade the rest rather than add a color, since another color reads as another meaning.
+
+**The words.** A caption is one paragraph of a few short sentences, since a chapter lasts as long as its caption. It is written as if said aloud, with no symbols a voice would trip on, and each sentence reads well around a filled figure. The figure is rounded as a person would say it ($100 for 102.08, 1,900 for 1,937), with "about" before it where it helps. A caption can also leave the number out and let the stage show it.
+
+## The voice
+
+Some readers have a voice that reads the captions; many don't, and the piece plays whole without it. It reads only the captions, so each caption says what its chapter shows. The skeleton marks them to be read, and `lang` on their holder, `.vs-caps`, names the language they are written in. Whatever else is in it is read aloud too, and words in `[brackets]` are shown but not said, so a caption has none. The skeleton's controls and script already follow the voice: read `artifact-type/reference/read-aloud.md` before you change either.
+
+## Telling the person
+
+The person will want to know that Play starts the piece, and how long it runs. A reply mentions the voice only if the person asked to listen.
+
+## A retired player
+
+A page whose `.vs-controls` holds a `data-read-play` button has a player that is no longer made. Whenever you change such a page and it stays a Visual short, read the skeleton and the script, swap in their controls, CSS and engine, and keep the page's chapters, captions, calcs, `fmt`, drawings and `scenes`.