@kitlangton/knobs 0.4.0-next.2 → 0.4.0-next.4

package/dist/types/tokens/schema.d.ts

@@ -409,6 +409,24 @@ export declare const TOKENS: readonly [{
         readonly css: "var(--k-warn)";
     };
     readonly doc: "Modified lines.";
+}, {
+    readonly name: "before";
+    readonly tier: "semantic";
+    readonly type: "color";
+    readonly group: "Data";
+    readonly source: {
+        readonly css: "var(--k-fg-3)";
+    };
+    readonly doc: "Before in a comparison, and only Before: its label and side of the seam. Neutral unless a theme gives it a colour.";
+}, {
+    readonly name: "after";
+    readonly tier: "semantic";
+    readonly type: "color";
+    readonly group: "Data";
+    readonly source: {
+        readonly css: "var(--k-fg)";
+    };
+    readonly doc: "After in a comparison, and only After.";
 }, {
     readonly name: "series-1";
     readonly tier: "semantic";
@@ -510,6 +528,168 @@ export declare const TOKENS: readonly [{
         readonly value: "288px";
     };
     readonly doc: "Panel width.";
+}, {
+    readonly name: "space-inside";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "var(--k-unit)";
+    };
+    readonly doc: "Parts of one thing: an icon and its label, a meta line and its title.";
+}, {
+    readonly name: "space-sibling";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 2)";
+    };
+    readonly doc: "Siblings in a group: buttons in a row, a list item's lines.";
+}, {
+    readonly name: "space-title";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 3)";
+    };
+    readonly doc: "A heading and what it heads.";
+}, {
+    readonly name: "space-group";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 12)";
+    };
+    readonly doc: "Groups inside a section (prose, video, diff), stacked media, feed items (a hairline in the middle).";
+}, {
+    readonly name: "space-section";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 24)";
+    };
+    readonly doc: "Sections of a page (the intro, the updates, each PR), a hairline in the middle.";
+}, {
+    readonly name: "space-column";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 6)";
+    };
+    readonly doc: "Columns: a contents rail and the page, media side by side.";
+}, {
+    readonly name: "pad-page";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 6)";
+    };
+    readonly doc: "A page's edge; 16px under 640px wide.";
+}, {
+    readonly name: "pad-card";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Space";
+    readonly source: {
+        readonly css: "calc(var(--k-unit) * 3)";
+    };
+    readonly doc: "Inside a card or popover.";
+}, {
+    readonly name: "type-heading";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "20px";
+    };
+    readonly doc: "Section headings (a PR's title, under its kicker), weight 500.";
+}, {
+    readonly name: "leading-heading";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "28px";
+    };
+    readonly doc: "Line height for type-heading.";
+}, {
+    readonly name: "type-title";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "16px";
+    };
+    readonly doc: "A page's title, weight 500.";
+}, {
+    readonly name: "leading-title";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "24px";
+    };
+    readonly doc: "Line height for type-title.";
+}, {
+    readonly name: "type-body";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "13px";
+    };
+    readonly doc: "Prose, questions, list rows, step titles; 400, or 500 for emphasis.";
+}, {
+    readonly name: "leading-body";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "20px";
+    };
+    readonly doc: "Line height for type-body.";
+}, {
+    readonly name: "type-label";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "12px";
+    };
+    readonly doc: "Labels over media, weight 500; mono inside body text.";
+}, {
+    readonly name: "leading-label";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "16px";
+    };
+    readonly doc: "Line height for type-label.";
+}, {
+    readonly name: "type-small";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "11px";
+    };
+    readonly doc: "Meta, controls, keys, timestamps; mono inside labels.";
+}, {
+    readonly name: "leading-small";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Type";
+    readonly source: {
+        readonly value: "16px";
+    };
+    readonly doc: "Line height for type-small.";
 }, {
     readonly name: "font-size";
     readonly tier: "semantic";

package/dist/types/ui/compare-css.d.ts

@@ -1 +1 @@
-export declare const compareCss = "\n:where(.knobs-compare,.knobs-compare *,.knobs-cmp-strip,.knobs-cmp-strip *){box-sizing:border-box}\n.knobs-ui.knobs-compare{--_ku-cmp-diff:var(--k-compare-diff,var(--_k-ok));--_ku-cmp-line:var(--_k-compare-divider);\n  --_ku-cmp-stage:var(--_k-compare-stage);\n  display:flex;flex-direction:column;gap:6px;width:100%;height:100%;min-height:160px;outline:none;user-select:none;-webkit-user-select:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-ui) :is(.knobs-cmp-mode,.knobs-cmp-toggle){all:revert;box-sizing:border-box;font:inherit;color:inherit;letter-spacing:inherit;background:transparent;border:0;margin:0;padding:0;outline:none;box-shadow:none}\n.knobs-cmp-bar{flex:none;display:flex;align-items:center;gap:2px;height:24px;padding:0 2px}\n.knobs-cmp-modes{display:flex;align-items:center;gap:2px}\n.knobs-ui .knobs-cmp-mode,.knobs-ui .knobs-cmp-toggle{height:22px;padding:0 7px;border-radius:max(0px,calc(var(--_k-radius) - 2px));color:var(--_k-fg-3);cursor:pointer;white-space:nowrap;\n  transition:color .15s,background .15s}\n.knobs-ui .knobs-cmp-mode:is(:hover,:focus-visible),.knobs-ui .knobs-cmp-toggle:is(:hover,:focus-visible){color:var(--_k-fg);background:var(--_ku-wash)}\n.knobs-ui .knobs-cmp-mode[aria-checked=\"true\"],.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--_k-fg);font-weight:var(--_k-weight-label)}\n.knobs-cmp-fill{flex:1}\n.knobs-cmp-toggle[hidden]{display:none}\n/* One surface: on a card (a walkthrough's step, a split's pane, anything .knobs-surface) or marked\n   data-nested, the stage drops its fill and the sides sit on that card. */\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-compare,.knobs-ui.knobs-compare[data-nested]{--_ku-cmp-stage:var(--k-compare-stage,transparent)}\n/* In a page's flow (a container with no height), it takes the height its sides need. */\n.knobs-ui.knobs-compare[data-auto]{height:auto}\n.knobs-compare[data-auto] .knobs-cmp-stage{flex:none;min-height:0}\n.knobs-cmp-stage{position:relative;flex:1;min-height:96px;overflow:hidden;border-radius:var(--_k-radius-panel);background:var(--_ku-cmp-stage);touch-action:pan-y;outline:none}\n.knobs-compare[data-frame=\"flat\"] .knobs-cmp-stage{border-radius:0}\n.knobs-compare[data-mode=\"wipe\"] .knobs-cmp-stage{cursor:ew-resize}\n/* Unzoomed, a finger still scrolls the page up and down; zoomed, the stage takes every gesture. */\n.knobs-compare[data-zoomed] .knobs-cmp-stage{cursor:grab;touch-action:none}\n.knobs-compare[data-panning],.knobs-compare[data-panning] *{cursor:grabbing!important}\n.knobs-compare[data-dragging],.knobs-compare[data-dragging] *{cursor:ew-resize!important}\n.knobs-cmp-sizer{position:absolute;left:0;right:0;top:0;height:0;visibility:hidden;pointer-events:none}\n.knobs-cmp-canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n.knobs-cmp-media{position:absolute;left:0;top:0;display:block;max-width:none;margin:0;padding:0;border:0;object-fit:fill;transform-origin:0 0;pointer-events:none;will-change:transform}\n.knobs-compare[data-renderer=\"gpu\"] .knobs-cmp-media{opacity:0}\n/* Glass: what's behind shows through, blurred, on the knobs tokens. */\n.knobs-cmp-label,.knobs-cmp-zoom{background:color-mix(in srgb,var(--_k-bg) 52%,transparent);-webkit-backdrop-filter:blur(14px) saturate(1.6);backdrop-filter:blur(14px) saturate(1.6);\n  box-shadow:inset 0 0 0 .5px var(--_k-border),inset 0 1px 0 var(--_k-rim),0 2px 10px rgba(0,0,0,calc(.18 * var(--_k-shadow-k,1)))}\n.knobs-cmp-label{position:absolute;left:0;top:0;padding:1px 7px;border-radius:999px;font-size:var(--_k-text-meta);line-height:16px;color:var(--_k-fg-2);white-space:nowrap;pointer-events:none;will-change:transform;transition:color .15s}\n.knobs-cmp-label[data-lit]{color:var(--_k-fg)}\n.knobs-cmp-label[data-dim]{color:var(--_k-fg-3)}\n/* The wipe: a hairline down the line with a grip at its middle; a wider strip takes the hand and\n   the keys (a slider). It fades with the mode. */\n.knobs-cmp-handle{cursor:ew-resize;position:absolute;left:-12px;top:0;width:24px;height:0;opacity:0;pointer-events:none;outline:none;will-change:transform;transition:opacity .18s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-handle[data-on]{opacity:1;pointer-events:auto;transition:opacity .22s cubic-bezier(.2,.8,.2,1)}\n.knobs-cmp-handle::before{content:\"\";position:absolute;top:0;bottom:0;left:11.5px;width:1px;background:var(--_ku-cmp-line);box-shadow:0 0 0 .5px rgba(0,0,0,.28),0 0 6px rgba(0,0,0,.25)}\n.knobs-cmp-handle::after{content:\"\";position:absolute;top:50%;left:9px;width:6px;height:28px;margin-top:-14px;border-radius:3px;background:var(--_ku-cmp-line);\n  box-shadow:0 1px 3px rgba(0,0,0,.35),0 0 0 .5px rgba(0,0,0,.2);transition:scale .18s var(--_ku-ease),box-shadow .15s}\n.knobs-compare[data-dragging] .knobs-cmp-handle::after{scale:1.12}\n.knobs-cmp-handle:focus-visible::after,.knobs-compare[data-keyboard] .knobs-cmp-handle:focus::after{box-shadow:0 1px 3px rgba(0,0,0,.35),0 0 0 3px color-mix(in srgb,var(--_k-accent) 40%,transparent)}\n/* The split's hairline, down the middle side by side. */\n.knobs-cmp-split{position:absolute;left:0;top:0;width:1px;height:0;margin-left:-.5px;background:color-mix(in srgb,var(--_k-bg) 72%,transparent);pointer-events:none;will-change:transform,opacity}\n/* Zoomed: how far, and a way back, in the stage's corner; it fades in and out, nothing shifts. */\n.knobs-cmp-zoom{position:absolute;right:8px;bottom:8px;display:flex;align-items:center;gap:4px;height:26px;padding:0 3px 0 10px;border-radius:999px;\n  color:var(--_k-fg);font-size:var(--_k-text-meta);font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";white-space:nowrap;\n  opacity:0;scale:.96;pointer-events:none;transition:opacity .16s cubic-bezier(.4,0,1,1),scale .16s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-zoom[data-on]{opacity:1;scale:1;pointer-events:auto;transition:opacity .2s cubic-bezier(.2,.8,.2,1),scale .2s cubic-bezier(.2,.8,.2,1)}\n:where(.knobs-ui) .knobs-cmp-zoom-reset{all:revert;box-sizing:border-box;font:inherit;letter-spacing:inherit;margin:0;border:0;outline:none;box-shadow:none;\n  height:20px;padding:0 8px;border-radius:999px;background:transparent;color:var(--_k-fg-2);cursor:pointer;transition:color .15s,background .15s}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){color:var(--_k-fg);background:color-mix(in srgb,var(--_k-fg) 12%,transparent)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);font-size:var(--_k-text-meta);pointer-events:none}\n.knobs-cmp-note:empty{display:none}\n.knobs-cmp-strip-host{flex:none;height:60px;min-height:0}\n.knobs-cmp-timeline-host{flex:none;height:56px;min-height:0}\n/* The frame strip: Before over After per column, a difference bar under them, a dot where it peaks. */\n.knobs-ui.knobs-cmp-strip{--_ku-cmp-diff:var(--k-compare-diff,var(--_k-ok));position:relative;width:100%;height:100%;min-height:40px;overflow:hidden;cursor:col-resize;touch-action:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg)}\n.knobs-cmp-strip>canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n@media(prefers-reduced-motion:reduce){:is(.knobs-compare,.knobs-cmp-strip) :where(*,::before,::after){transition-duration:.12s!important}}\n";
+export declare const compareCss = "\n:where(.knobs-compare,.knobs-compare *,.knobs-cmp-strip,.knobs-cmp-strip *){box-sizing:border-box}\n.knobs-ui.knobs-compare{--_ku-cmp-diff:var(--k-compare-diff,var(--_k-ok));--_ku-cmp-line:var(--_k-compare-divider);\n  --_ku-cmp-stage:var(--_k-compare-stage);\n  display:flex;flex-direction:column;gap:6px;width:100%;height:100%;min-height:160px;outline:none;user-select:none;-webkit-user-select:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-ui) :is(.knobs-cmp-mode,.knobs-cmp-toggle){all:revert;box-sizing:border-box;font:inherit;color:inherit;letter-spacing:inherit;background:transparent;border:0;margin:0;padding:0;outline:none;box-shadow:none}\n.knobs-cmp-bar{flex:none;display:flex;align-items:center;gap:var(--_k-gap);height:var(--_k-control-h)}\n/* The modes: one fill, the selection pill on the one picked; a mode isn't brighter for being\n   picked: the pill's bright copy is. */\n.knobs-cmp-modes{position:relative;display:inline-flex;height:var(--_k-control-h);border-radius:var(--_k-radius);background:var(--_k-fill)}\n.knobs-cmp-modes[hidden]{display:none}\n.knobs-ui .knobs-cmp-mode{display:inline-flex;align-items:center;height:100%;padding:0 8px;border-radius:var(--_k-radius);color:var(--_k-fg-2);cursor:pointer;white-space:nowrap;\n  transition:color calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-mode:is(:hover,:focus-visible){color:var(--_k-fg)}\n/* Toggles: icon buttons, the accent's wash when on. */\n.knobs-ui .knobs-cmp-toggle{display:inline-flex;align-items:center;justify-content:center;width:var(--_k-control-h);height:var(--_k-control-h);border-radius:var(--_k-radius);color:var(--_k-fg-3);cursor:pointer;\n  transition:color calc(var(--_k-hover-out) * 1ms),background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-toggle:is(:hover,:focus-visible){color:var(--_k-fg);background:var(--_ku-wash)}\n.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--_k-accent-fg);background:var(--_k-accent-soft)}\n.knobs-cmp-toggle svg{display:block}\n.knobs-cmp-fill{flex:1}\n.knobs-cmp-toggle[hidden]{display:none}\n/* One surface: on a card (a walkthrough's step, a split's pane, anything .knobs-surface) or marked\n   data-nested, the stage drops its fill and the sides sit on that card. */\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-compare,.knobs-ui.knobs-compare[data-nested]{--_ku-cmp-stage:var(--k-compare-stage,transparent)}\n/* In a page's flow (a container with no height), it takes the height its sides need. */\n.knobs-ui.knobs-compare[data-auto]{height:auto}\n.knobs-compare[data-auto] .knobs-cmp-stage{flex:none;min-height:0}\n.knobs-cmp-stage{position:relative;flex:1;min-height:96px;overflow:hidden;border-radius:var(--_k-radius-panel);background:var(--_ku-cmp-stage);touch-action:pan-y;outline:none}\n.knobs-compare[data-frame=\"flat\"] .knobs-cmp-stage{border-radius:0}\n.knobs-compare[data-mode=\"wipe\"] .knobs-cmp-stage{cursor:ew-resize}\n/* Unzoomed, a finger still scrolls the page up and down; zoomed, the stage takes every gesture. */\n.knobs-compare[data-zoomed] .knobs-cmp-stage{cursor:grab;touch-action:none}\n.knobs-compare[data-panning],.knobs-compare[data-panning] *{cursor:grabbing!important}\n/* Wiping, the grip stands in for the cursor. */\n.knobs-compare[data-dragging],.knobs-compare[data-dragging] *{cursor:none!important}\n.knobs-cmp-sizer{position:absolute;left:0;right:0;top:0;height:0;visibility:hidden;pointer-events:none}\n.knobs-cmp-canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n.knobs-cmp-media{position:absolute;left:0;top:0;display:block;max-width:none;margin:0;padding:0;border:0;object-fit:fill;transform-origin:0 0;pointer-events:none;will-change:transform}\n.knobs-compare[data-renderer=\"gpu\"] .knobs-cmp-media{opacity:0}\n/* Glass: what's behind shows through, blurred, on the knobs tokens. */\n.knobs-cmp-label,.knobs-cmp-zoom{background:color-mix(in srgb,var(--_k-bg) 52%,transparent);-webkit-backdrop-filter:blur(14px) saturate(1.6);backdrop-filter:blur(14px) saturate(1.6);\n  box-shadow:inset 0 0 0 .5px var(--_k-border),inset 0 1px 0 var(--_k-rim),0 2px 10px rgba(0,0,0,calc(.18 * var(--_k-shadow-k,1)))}\n/* \u2717 Before \u00B7 \u2713 After: Before quieter (fg-3), After in full text. Neutral: no colour of its own. */\n.knobs-cmp-label{position:absolute;left:0;top:0;display:flex;align-items:center;gap:4px;padding:1px 7px 1px 5px;border-radius:999px;font-size:var(--_k-text-meta);line-height:16px;font-weight:var(--_k-weight-label);\n  white-space:nowrap;pointer-events:none;will-change:transform}\n.knobs-cmp-label[data-side=\"before\"]{color:var(--_k-fg-3)}\n.knobs-cmp-label[data-side=\"after\"]{color:var(--_k-fg)}\n.knobs-cmp-mark svg{display:block;width:12px;height:12px}\n/* The wipe: a hairline down the line with a raised grip at the pointer's height; a wider strip\n   takes the hand and the keys (a slider). It fades with the mode; wiping, line and grip brighten. */\n.knobs-cmp-handle{cursor:ew-resize;position:absolute;left:-12px;top:0;width:24px;height:0;opacity:0;pointer-events:none;outline:none;will-change:transform;transition:opacity .18s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-handle[data-on]{opacity:1;pointer-events:auto;transition:opacity .22s cubic-bezier(.2,.8,.2,1)}\n.knobs-cmp-handle::before{content:\"\";position:absolute;top:0;bottom:0;left:11.5px;width:1px;background:color-mix(in srgb,var(--_ku-cmp-line) 72%,transparent);box-shadow:0 0 0 .5px rgba(0,0,0,.28),0 0 6px rgba(0,0,0,.25)}\n.knobs-compare[data-dragging] .knobs-cmp-handle::before{background:var(--_ku-cmp-line)}\n.knobs-cmp-grip{position:absolute;top:0;left:4px;width:16px;height:28px;border-radius:min(8px,calc(var(--_k-radius) * 999));background:var(--_k-bg-overlay);\n  box-shadow:var(--_k-shadow-overlay),inset 0 0 0 1px var(--_k-border),inset 0 1px 0 var(--_k-rim);will-change:transform;transition:box-shadow calc(var(--_k-hover-out) * 1ms)}\n.knobs-cmp-grip::before,.knobs-cmp-grip::after{content:\"\";position:absolute;top:10px;width:1px;height:8px;background:var(--_k-fg-3);transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-cmp-grip::before{left:6px}\n.knobs-cmp-grip::after{left:9px}\n.knobs-compare[data-dragging] .knobs-cmp-grip{box-shadow:var(--_k-shadow-overlay),inset 0 0 0 1px var(--_k-border-strong),inset 0 1px 0 var(--_k-rim)}\n.knobs-compare[data-dragging] .knobs-cmp-grip::before,.knobs-compare[data-dragging] .knobs-cmp-grip::after{background:var(--_k-fg)}\n.knobs-cmp-handle:focus-visible .knobs-cmp-grip,.knobs-compare[data-keyboard] .knobs-cmp-handle:focus .knobs-cmp-grip{box-shadow:var(--_k-shadow-overlay),0 0 0 2px var(--_k-accent)}\n/* The split's hairline, down the middle side by side. */\n.knobs-cmp-split{position:absolute;left:0;top:0;width:1px;height:0;margin-left:-.5px;background:color-mix(in srgb,var(--_k-bg) 72%,transparent);pointer-events:none;will-change:transform,opacity}\n/* Zoomed: how far, and a way back, in the stage's corner; it fades in and out, nothing shifts. */\n.knobs-cmp-zoom{position:absolute;right:8px;bottom:8px;display:flex;align-items:center;gap:4px;height:26px;padding:0 3px 0 10px;border-radius:999px;\n  color:var(--_k-fg);font-size:var(--_k-text-meta);font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";white-space:nowrap;\n  opacity:0;scale:.96;pointer-events:none;transition:opacity .16s cubic-bezier(.4,0,1,1),scale .16s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-zoom[data-on]{opacity:1;scale:1;pointer-events:auto;transition:opacity .2s cubic-bezier(.2,.8,.2,1),scale .2s cubic-bezier(.2,.8,.2,1)}\n:where(.knobs-ui) .knobs-cmp-zoom-reset{all:revert;box-sizing:border-box;font:inherit;letter-spacing:inherit;margin:0;border:0;outline:none;box-shadow:none;\n  display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;padding:0;border-radius:999px;background:transparent;color:var(--_k-fg-2);cursor:pointer;transition:color .15s,background .15s}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){color:var(--_k-fg);background:color-mix(in srgb,var(--_k-fg) 12%,transparent)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);font-size:var(--_k-text-meta);pointer-events:none}\n.knobs-cmp-note:empty{display:none}\n.knobs-cmp-strip-host{flex:none;height:60px;min-height:0}\n.knobs-cmp-timeline-host{flex:none;min-height:0}\n/* The frame strip: Before over After per column, a difference bar under them, a dot where it peaks. */\n.knobs-ui.knobs-cmp-strip{--_ku-cmp-diff:var(--k-compare-diff,var(--_k-ok));position:relative;width:100%;height:100%;min-height:40px;overflow:hidden;cursor:col-resize;touch-action:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg)}\n.knobs-cmp-strip>canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n@media(prefers-reduced-motion:reduce){:is(.knobs-compare,.knobs-cmp-strip) :where(*,::before,::after){transition-duration:.12s!important}}\n";

package/dist/types/ui/compare-gpu.d.ts

@@ -3,7 +3,6 @@ export declare const MODE_INDEX: {
     readonly side: 0;
     readonly wipe: 1;
     readonly difference: 2;
-    readonly flicker: 3;
 };
 export interface CompareDraw {
     /** Device px: where each side's picture lands (zoomed, it's larger than its clip). */
@@ -22,10 +21,6 @@ export interface CompareDraw {
     readonly to: number;
     /** 0 shows `from`, 1 shows `to`. */
     readonly mix: number;
-    /** Before in After's place (X held). */
-    readonly flick: boolean;
-    /** Flicker mode's phase: Before showing. */
-    readonly phase: boolean;
     readonly threshold: number;
     readonly gain: number;
     readonly accent: readonly [number, number, number];

package/dist/types/ui/compare-model.d.ts

@@ -1,5 +1,18 @@
 import type { TimeView } from "./timeline-model.js";
-export type CompareMode = "side" | "wipe" | "difference" | "flicker";
+/** Side by side, a wipe, or (opt in) a difference. */
+export type CompareMode = "side" | "wipe" | "difference";
+/**
+ * The modes a viewer offers (`["side", "wipe"]` unless given; `difference` only when asked for),
+ * in their order, and the mode it starts in (the first offered when the asked one isn't).
+ */
+export declare function compareModes(modes?: readonly CompareMode[], mode?: CompareMode): {
+    readonly modes: readonly CompareMode[];
+    readonly mode: CompareMode;
+};
+/** The mode a key picks among those offered: a digit by position, or S, W, D. */
+export declare function modeForKey(key: string, modes: readonly CompareMode[]): CompareMode | null;
+/** A mode's letter key (S, W, D). */
+export declare const modeKey: (mode: CompareMode) => string;
 export type MediaKind = "video" | "image";
 /** A source's kind: as given, else by its extension (a video's, or an image). */
 export declare function mediaKind(src: string, kind?: MediaKind): MediaKind;
@@ -76,7 +89,7 @@ export interface CompareLayout {
         readonly after: Rect;
         readonly split: number;
     };
-    /** Overlaid (wipe, difference, flicker): both in the same place. */
+    /** Overlaid (wipe, difference): both in the same place. */
     readonly overlay: {
         readonly before: Rect;
         readonly after: Rect;
@@ -134,6 +147,22 @@ export declare function wipeGrab(x: number, rect: Rect, wipe: number, slop?: num
     onLine: boolean;
     offset: number;
 };
+/**
+ * Wiping, Before and After ride either side of the seam at `x`, `gap` from it, each fading out as
+ * its side runs out of room (`left`/`right`: the wipe's edges; `wb`/`wa`: the labels' widths).
+ */
+export declare function seamLabels(x: number, left: number, right: number, wb: number, wa: number, gap?: number): {
+    before: {
+        x: number;
+        opacity: number;
+    };
+    after: {
+        x: number;
+        opacity: number;
+    };
+};
+/** Where the wipe's grip sits for a pointer at `y`: its top, kept `margin` inside the line. */
+export declare function gripTop(y: number, rect: Rect, grip: number, margin?: number): number;
 /** The wipe moved by a key: 1% a press, 10% with Shift. */
 export declare const wipeKey: (wipe: number, dir: -1 | 1, big?: boolean) => number;
 export interface StripColumn {

package/dist/types/ui/compare.d.ts

@@ -29,8 +29,13 @@ export interface CompareSource {
 export interface CompareOptions extends UiLook {
     readonly before: CompareSource;
     readonly after: CompareSource;
-    /** `"side"` (side by side) by default. */
+    /** The first of `modes` (`"side"`, side by side) by default. */
     readonly mode?: CompareMode;
+    /**
+     * The modes it offers, in the mode bar's order and on `1`–`3`: `["side", "wipe"]` by default.
+     * Add `"difference"` to offer a difference. One mode hides the bar.
+     */
+    readonly modes?: readonly CompareMode[];
     /** Where the wipe's line sits, 0 (all After) to 1 (all Before); 0.5. */
     readonly wipe?: number;
     /** Frames per second (the bound timeline's, else 30): steps, and where paused videos land. */
@@ -41,8 +46,8 @@ export interface CompareOptions extends UiLook {
     readonly threshold?: number;
     /**
      * The clock: an existing `timeline()` (its time drives both sides; while playing it follows
-     * After), or `true` for one of its own under the viewer. Without one, `seek`, `play` and keys
-     * still work.
+     * After), or `true` for a slim one of its own under the viewer (the `"lane"` variant: its
+     * markers are chapter ticks). Without one, `seek`, `play` and keys still work.
      */
     readonly timeline?: Timeline | boolean;
     /** The frame strip over the timeline (off; one timeline is made if there's none). */
@@ -68,6 +73,8 @@ export interface CompareOptions extends UiLook {
 export interface Compare {
     readonly element: HTMLElement;
     readonly mode: CompareMode;
+    /** The modes it offers. */
+    readonly modes: readonly CompareMode[];
     readonly wipe: number;
     readonly loupe: boolean;
     /** Seconds. */
@@ -85,7 +92,13 @@ export interface Compare {
     readonly loop: CompareLoop | null;
     /** New sources, mode, wipe, loupe, threshold or fps. A new mode glides in. */
     update(next: Partial<Pick<CompareOptions, "before" | "after" | "mode" | "wipe" | "loupe" | "threshold" | "fps">>): void;
-    seek(time: number): void;
+    /**
+     * `glide`: a jump the hand didn't make (a chapter's click): the timeline's playhead catches up
+     * from where it is while the videos land at once.
+     */
+    seek(time: number, options?: {
+        readonly glide?: boolean;
+    }): void;
     /** Moves by `seconds`, the timeline's playhead gliding there (playing carries on). */
     seekBy(seconds: number): void;
     play(): void;

package/dist/types/ui/history-css.d.ts

@@ -0,0 +1 @@
+export declare const historyCss = "\n:where(.knobs-history,.knobs-history *){box-sizing:border-box}\n.knobs-ui.knobs-history{--hy-gutter:128px;--hy-lane:28px;--hy-bar:18px;--hy-axis:20px;--hy-bandrow:0px;--hy-c:var(--_k-fg-3);\n  --hy-fade:linear-gradient(to right,#000 calc(100% - 1.5em),transparent);\n  position:relative;display:flex;flex-direction:column;width:100%;min-width:0;outline:none;color:var(--_k-fg);\n  font:var(--_k-weight) var(--_k-type-body)/var(--_k-leading-body) var(--_k-font);font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";\n  text-align:left;letter-spacing:normal;-webkit-font-smoothing:antialiased;user-select:none;-webkit-user-select:none}\n.knobs-history[data-bands]{--hy-bandrow:var(--_k-leading-small)}\n.knobs-history[data-narrow]{--hy-gutter:0px}\n.knobs-history [hidden]{display:none!important}\n:where(.knobs-ui) :is(.knobs-hy-ev,.knobs-hy-span,.knobs-hy-jump){all:revert;box-sizing:border-box;font:inherit;color:inherit;letter-spacing:inherit;\n  background:transparent;border:0;border-radius:0;margin:0;padding:0;min-width:0;box-shadow:none;outline:none}\n.knobs-history [data-tone=\"good\"]{--hy-c:var(--_k-ok)}\n.knobs-history [data-tone=\"warn\"]{--hy-c:var(--_k-warn)}\n.knobs-history [data-tone=\"bad\"]{--hy-c:var(--_k-danger)}\n.knobs-history [data-tone=\"info\"]{--hy-c:var(--_k-info)}\n.knobs-history [data-tone=\"dim\"]{--hy-c:var(--_k-fg-3)}\n\n/* \u2014\u2014\u2014 the chart: lane labels beside the plot (above each lane where it's narrow) \u2014\u2014\u2014 */\n.knobs-hy-chart{position:relative;display:grid;grid-template-columns:var(--hy-gutter) minmax(0,1fr)}\n.knobs-hy-axis{position:relative;grid-column:2;grid-row:1;height:calc(var(--hy-bandrow) + var(--hy-axis))}\n:is(.knobs-hy-tick,.knobs-hy-now,.knobs-hy-blabel){position:absolute;white-space:nowrap;font-size:var(--_k-type-small);line-height:var(--_k-leading-small);color:var(--_k-fg-3)}\n.knobs-hy-tick{bottom:2px;padding-left:4px}\n.knobs-hy-now{bottom:2px;color:var(--_k-accent-fg);font-weight:var(--_k-weight-label)}\n.knobs-hy-blabel{top:0;padding-left:4px;overflow:hidden;color:var(--_k-fg-2)}\n.knobs-hy-label{grid-column:1;align-self:center;min-width:0;margin-right:var(--_k-space-title);overflow:hidden;white-space:nowrap;\n  font-size:var(--_k-type-label);line-height:var(--_k-leading-label);color:var(--_k-fg-2)}\n.knobs-history[data-narrow] .knobs-hy-label{grid-column:2;align-self:end;margin:0;font-size:var(--_k-type-small);line-height:var(--_k-leading-small)}\n:is(.knobs-hy-label,.knobs-hy-blabel)[data-overflow]{-webkit-mask-image:var(--hy-fade);mask-image:var(--hy-fade)}\n.knobs-hy-track{position:relative;grid-column:2;height:var(--hy-lane)}\n.knobs-hy-layer{position:absolute;inset:0;grid-column:2;grid-row:1/-1;pointer-events:none}\n\n/* Bands and month lines behind the lanes; today, the selection and the pointer's line over them. */\n.knobs-hy-band{position:absolute;top:0;bottom:0;background:color-mix(in oklch,var(--_k-fg) 3.5%,transparent)}\n:is(.knobs-hy-grid,.knobs-hy-today,.knobs-hy-hover,.knobs-hy-sel){position:absolute;left:0;top:calc(var(--hy-bandrow) + var(--hy-axis));bottom:0;width:1px;margin-left:-.5px}\n.knobs-hy-grid{background:var(--_k-border-subtle)}\n.knobs-hy-today{top:calc(var(--hy-bandrow) + var(--hy-axis) - 4px);background:var(--_k-accent)}\n.knobs-hy-hover{background:color-mix(in oklch,var(--_k-fg) 32%,transparent);opacity:0;transition:opacity calc(var(--_k-hover-out) * 1ms)}\n.knobs-hy-hover[data-on]{opacity:1;transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-hy-sel{background:var(--_k-fg-2);opacity:0}\n.knobs-hy-sel[data-on]{opacity:.6}\n\n/* Spans: a soft bar in their state's tone, inferred ones hatched; the tag at the end. */\n.knobs-hy-span{position:absolute;top:calc((var(--hy-lane) - var(--hy-bar)) / 2);height:var(--hy-bar);border-radius:var(--_k-radius-sm);cursor:pointer;\n  background:color-mix(in oklch,var(--hy-c) 24%,transparent);transition:background calc(var(--_k-hover-out) * 1ms),box-shadow calc(var(--_k-hover-out) * 1ms)}\n.knobs-hy-span[data-inferred]{background:repeating-linear-gradient(135deg,color-mix(in oklch,var(--hy-c) 34%,transparent) 0 2px,color-mix(in oklch,var(--hy-c) 9%,transparent) 2px 6px)}\n.knobs-hy-span[data-hover]{background-color:color-mix(in oklch,var(--hy-c) 34%,transparent);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-hy-span[data-selected]{box-shadow:inset 0 0 0 1px var(--hy-c)}\n.knobs-hy-span[data-clip-start]{border-top-left-radius:0;border-bottom-left-radius:0;-webkit-mask-image:linear-gradient(to right,transparent,#000 16px);mask-image:linear-gradient(to right,transparent,#000 16px)}\n.knobs-hy-span[data-clip-end]{border-top-right-radius:0;border-bottom-right-radius:0;-webkit-mask-image:linear-gradient(to left,transparent,#000 16px);mask-image:linear-gradient(to left,transparent,#000 16px)}\n.knobs-hy-tag{position:absolute;top:0;right:6px;line-height:var(--hy-bar);font-size:var(--_k-type-small);font-weight:var(--_k-weight-label);white-space:nowrap;pointer-events:none;\n  color:color-mix(in oklch,var(--hy-c) 55%,var(--_k-fg))}\n.knobs-hy-tag[data-place=\"after\"]{right:auto;left:calc(100% + 6px)}\n.knobs-hy-tag[data-place=\"none\"]{visibility:hidden}\n\n/* Event marks (their kind named in the tooltip): a dot for a commit, a diamond for a release, a cross for a deletion, a square for a\n   channel's switch, a triangle for a finding; inferred ones hollow. */\n.knobs-hy-ev{position:absolute;top:0;width:16px;height:var(--hy-lane);margin-left:-8px;cursor:pointer;--hy-c:var(--_k-fg-2);--hy-s:9px}\n.knobs-hy-ev::before{content:\"\";position:absolute;left:50%;top:50%;width:var(--hy-s);height:var(--hy-s);margin:calc(var(--hy-s) / -2) 0 0 calc(var(--hy-s) / -2);\n  border-radius:50%;background:var(--hy-c);transition:scale calc(var(--_k-motion-snappy-ms) * 1ms) var(--_k-motion-snappy)}\n.knobs-hy-ev[data-range]{width:calc(var(--hy-w) + 16px)}\n.knobs-hy-ev[data-range]::before{left:calc(8px - var(--hy-s) / 2);right:calc(8px - var(--hy-s) / 2);width:auto;margin-left:0;border-radius:var(--_k-round)}\n.knobs-hy-ev[data-type=\"release\"]{--hy-s:8px}\n.knobs-hy-ev[data-type=\"release\"]::before{border-radius:1.5px;rotate:45deg}\n.knobs-hy-ev[data-type=\"channel\"]{--hy-s:8px}\n.knobs-hy-ev[data-type=\"channel\"]::before{border-radius:2px}\n.knobs-hy-ev[data-type=\"audit\"]{--hy-s:10px}\n.knobs-hy-ev[data-type=\"audit\"]::before{border-radius:0;clip-path:polygon(50% 4%,100% 92%,0 92%)}\n.knobs-hy-ev[data-type=\"deletion\"]::before{border-radius:0;rotate:45deg;\n  background:linear-gradient(var(--hy-c),var(--hy-c)) center/100% 1.75px no-repeat,linear-gradient(var(--hy-c),var(--hy-c)) center/1.75px 100% no-repeat}\n.knobs-hy-ev[data-inferred]:not([data-type=\"audit\"],[data-type=\"deletion\"])::before{background:transparent;box-shadow:inset 0 0 0 1.5px var(--hy-c)}\n.knobs-hy-ev[data-inferred]:is([data-type=\"audit\"],[data-type=\"deletion\"])::before{opacity:.5}\n.knobs-hy-ev[data-hover]::before{scale:1.25}\n.knobs-hy-ev[data-selected]::before{scale:1.3}\n.knobs-hy-ev[data-selected]::after{content:\"\";position:absolute;left:50%;top:50%;width:calc(var(--hy-s) + 9px);height:calc(var(--hy-s) + 9px);\n  margin:calc((var(--hy-s) + 9px) / -2) 0 0 calc((var(--hy-s) + 9px) / -2);border-radius:50%;box-shadow:0 0 0 1.5px var(--hy-c)}\n.knobs-hy-ev[data-range][data-selected]::after{left:3px;right:3px;width:auto;margin-left:0;border-radius:var(--_k-round)}\n.knobs-history:focus-visible .knobs-hy-ev[data-selected]::after{box-shadow:0 0 0 2px var(--_k-focus)}\n.knobs-history:focus-visible .knobs-hy-span[data-selected]{box-shadow:inset 0 0 0 2px var(--_k-focus)}\n\n/* \u2014\u2014\u2014 legend: only what the chart can't say itself \u2014\u2014\u2014 */\n.knobs-hy-legend{display:flex;flex-wrap:wrap;gap:var(--_k-space-inside) var(--_k-space-title);margin-top:var(--_k-space-sibling);padding-left:var(--hy-gutter);\n  font-size:var(--_k-type-small);line-height:var(--_k-leading-small);color:var(--_k-fg-3)}\n.knobs-hy-key{display:inline-flex;align-items:center;gap:6px;white-space:nowrap}\n.knobs-hy-swatch{flex:none;width:14px;height:8px;border-radius:2px;background:color-mix(in oklch,var(--hy-c) 34%,transparent)}\n.knobs-hy-swatch[data-inferred]{background:repeating-linear-gradient(135deg,color-mix(in oklch,var(--hy-c) 60%,transparent) 0 1.5px,transparent 1.5px 4px)}\n\n/* \u2014\u2014\u2014 the detail: one area under the chart, its height on a spring \u2014\u2014\u2014 */\n.knobs-hy-detail{position:relative;overflow:hidden;user-select:text;-webkit-user-select:text}\n.knobs-hy-detail[data-moving]{-webkit-mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent);mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent)}\n.knobs-hy-dc{padding:var(--_k-space-title) 0 0 var(--hy-gutter);transition:opacity calc(var(--_k-motion-snappy-ms) * 1ms) var(--_k-motion-snappy)}\n.knobs-hy-dc:is([data-enter],[data-leave]){opacity:0}\n.knobs-hy-dc[data-leave]{position:absolute;left:0;right:0;top:0;transition-duration:calc(var(--_k-motion-snappy-ms) * .8ms)}\n.knobs-hy-dmeta{display:flex;flex-wrap:wrap;gap:0 var(--_k-space-sibling);font-size:var(--_k-type-small);line-height:var(--_k-leading-small);color:var(--_k-fg-3)}\n.knobs-hy-dmeta>[data-tone]{color:var(--hy-c)}\n.knobs-hy-dtitle{margin-top:var(--_k-space-inside);font-weight:var(--_k-weight-title);color:var(--_k-fg);text-wrap:balance}\n.knobs-hy-dtext{margin:var(--_k-space-inside) 0 0;max-width:68ch;color:var(--_k-fg-2);text-wrap:pretty}\n.knobs-hy-dtext code{font:calc(1em - 1px) var(--_k-mono);padding:1px 4px;border-radius:var(--_k-radius-sm);background:var(--_k-fill)}\n.knobs-hy-dfoot{display:flex;flex-wrap:wrap;align-items:center;gap:6px;margin-top:var(--_k-space-sibling)}\n.knobs-hy-dfoot:empty{display:none}\n.knobs-hy-evidence{display:inline-flex;align-items:center;height:20px;padding:0 6px;border-radius:var(--_k-radius-sm);background:var(--_k-fill);color:var(--_k-fg-2);\n  font:var(--_k-type-small)/1 var(--_k-mono);text-decoration:none;transition:background calc(var(--_k-hover-out) * 1ms),color calc(var(--_k-hover-out) * 1ms)}\na.knobs-hy-evidence:hover{background:var(--_k-fill-hover);color:var(--_k-fg);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui .knobs-hy-jump{display:inline-flex;align-items:center;gap:4px;height:20px;padding:0 6px 0 8px;border-radius:var(--_k-radius-sm);color:var(--_k-fg-2);cursor:pointer;\n  font-size:var(--_k-type-small);transition:background calc(var(--_k-hover-out) * 1ms),color calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-hy-jump:is(:hover,:focus-visible){background:var(--_k-fill);color:var(--_k-fg);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-hy-jump svg{width:12px;height:12px}\n\n/* \u2014\u2014\u2014 the pointer's tooltip: title, date, one line \u2014\u2014\u2014 */\n.knobs-hy-tip{position:absolute;left:0;top:0;max-width:280px;padding:6px 8px;border-radius:var(--_k-radius-md);background:var(--_k-bg-overlay);\n  box-shadow:var(--_k-shadow-overlay),0 0 0 1px var(--_k-border);pointer-events:none;opacity:0;transition:opacity calc(var(--_k-hover-out) * 1ms)}\n.knobs-hy-tip[data-on]{opacity:1;transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-hy-tt{font-size:var(--_k-type-label);line-height:var(--_k-leading-label);font-weight:var(--_k-weight-label);color:var(--_k-fg);text-wrap:balance}\n:is(.knobs-hy-td,.knobs-hy-tl){font-size:var(--_k-type-small);line-height:var(--_k-leading-small);color:var(--_k-fg-3)}\n.knobs-hy-tl{margin-top:2px;color:var(--_k-fg-2);text-wrap:pretty}\n.knobs-hy-tl:empty{display:none}\n\n@media(prefers-reduced-motion:reduce){\n  .knobs-history :where(*,::before,::after){transition-property:opacity,background,color,box-shadow!important}\n  .knobs-hy-dc{transition-duration:calc(var(--_k-hover-out) * 1ms)!important}\n}\n";

package/dist/types/ui/history-model.d.ts

@@ -0,0 +1,236 @@
+export type HistoryTone = "good" | "warn" | "bad" | "info" | "dim";
+export type HistoryProvenance = "verified" | "inferred";
+/** A small tag that backs a claim: a PR, a commit, a log, as a link or not. */
+export interface HistoryEvidence {
+    readonly label: string;
+    readonly href?: string;
+}
+/** A stretch of a lane in one state: "v1 works", "v2 broken". */
+export interface HistorySpan {
+    readonly id?: string;
+    /** ISO date (`2026-09-19`), or as a page writes it (`"Sep 19, 2026"`). */
+    readonly from: string;
+    /** Left out: still so today. */
+    readonly to?: string;
+    /** A key in `states`, or a word of its own. */
+    readonly state: string;
+    /** Its tag at the end, in place of the state's (`"31d broken"`). */
+    readonly label?: string;
+    /** Its detail's title, in place of "lane · state". */
+    readonly title?: string;
+    readonly detail?: string;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence?: readonly HistoryEvidence[];
+    /** A step it's about, for `onJump`. */
+    readonly step?: string;
+}
+/** A row of the chart: a channel or a track, with its spans. */
+export interface HistoryLane {
+    readonly id: string;
+    readonly label: string;
+    readonly spans?: readonly HistorySpan[];
+}
+/** A dated moment: a commit, a release, a deletion. */
+export interface HistoryEvent {
+    readonly id?: string;
+    /** ISO, or as written: "Apr 9, 2026", "Oct 14–16, 2026", "May 7–8". */
+    readonly date: string;
+    /** Where it ran over days: its last day. */
+    readonly to?: string;
+    /** The lane it sits on (`"code"` by default). */
+    readonly lane?: string;
+    readonly title: string;
+    readonly detail?: string;
+    /** Its mark: a commit a dot, a release a diamond, a deletion a cross, an audit a triangle. */
+    readonly type?: "commit" | "release" | "deletion" | "channel" | "audit" | (string & {});
+    readonly tone?: HistoryTone;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence?: readonly HistoryEvidence[];
+    readonly step?: string;
+}
+/** A faint labelled stretch behind every lane: a phase. */
+export interface HistoryBand {
+    readonly from: string;
+    readonly to?: string;
+    readonly label: string;
+}
+/** What a span's state means: its name in the legend, its colour and its tag (`{d}` the days). */
+export interface HistoryState {
+    readonly label?: string;
+    readonly tone?: HistoryTone;
+    /** `"{d}d broken"` (the default `"{d}d"`), or words of its own (`"v1"`). */
+    readonly tag?: string;
+}
+/** The walkthrough's older shape: events under headings. */
+export interface HistoryGroup {
+    readonly heading?: string;
+    readonly summary?: string;
+    readonly events?: readonly HistoryEvent[];
+    readonly rows?: readonly HistoryEvent[];
+}
+/** What `history()` draws: plain JSON. */
+export interface HistoryData {
+    readonly axis?: {
+        readonly from?: string;
+        readonly to?: string;
+        readonly today?: string;
+    };
+    readonly lanes?: readonly HistoryLane[];
+    readonly events?: readonly HistoryEvent[];
+    readonly bands?: readonly HistoryBand[];
+    readonly states?: Readonly<Record<string, HistoryState>>;
+    /** The walkthrough's older shape: each group's events go on the code lane under a band. */
+    readonly groups?: readonly HistoryGroup[];
+}
+/** Days since 1970-01-01 (UTC): every date in the model. */
+export type Day = number;
+export interface HyItem {
+    readonly id: string;
+    readonly kind: "event" | "span";
+    readonly lane: string;
+    readonly from: Day;
+    readonly to: Day;
+    /** A span still running today. */
+    readonly open: boolean;
+    readonly title: string;
+    readonly detail?: string;
+    readonly tone: HistoryTone;
+    readonly type?: string;
+    readonly inferred: boolean;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence: readonly HistoryEvidence[];
+    readonly step?: string;
+    /** A span's state key. */
+    readonly state?: string;
+    /** A span's end tags, longest first: its own or the state's, then the days alone. */
+    readonly tags: readonly string[];
+}
+export interface HyLane {
+    readonly id: string;
+    readonly label: string;
+    readonly spans: readonly HyItem[];
+    readonly events: readonly HyItem[];
+}
+export interface HyBand {
+    readonly from: Day;
+    readonly to: Day;
+    readonly label: string;
+}
+export interface HyState {
+    readonly key: string;
+    readonly label: string;
+    readonly tone: HistoryTone;
+}
+export interface HistoryModel {
+    readonly from: Day;
+    readonly to: Day;
+    readonly today: Day;
+    readonly lanes: readonly HyLane[];
+    /** Every event, in the order ←/→ walk them. */
+    readonly events: readonly HyItem[];
+    readonly bands: readonly HyBand[];
+    /** The states the spans use, in the order they first appear. */
+    readonly states: readonly HyState[];
+    /** The event types used, in the order they first appear. */
+    readonly types: readonly string[];
+    readonly inferred: boolean;
+    readonly items: ReadonlyMap<string, HyItem>;
+}
+export declare const dayOf: (y: number, m: number, d: number) => Day;
+export declare const todayDay: (now?: number) => Day;
+/**
+ * A date as written, as whole days: ISO (`2026-04-09`, a time after it ignored), or `"Apr 9, 2026"`,
+ * `"Oct 14–16, 2026"`, `"Jun 26 – Jul 2, 2026"`; with no year, `year`. Null when it's neither.
+ */
+export declare function parseDay(text: string, year?: number): {
+    from: Day;
+    to: Day;
+    year?: number;
+} | null;
+/** `"Jun 26, 2026"`. */
+export declare function formatDay(day: Day): string;
+/** One day, or a range as short as it reads: `"Oct 14–16, 2026"`, `"Sep 19, 2026 – today"`. */
+export declare function formatRange(from: Day, to: Day, open?: boolean): string;
+/** `"1 day"`, `"31 days"`. */
+export declare const formatDays: (n: number) => string;
+/** A state's colour from its name when `states` doesn't give one. */
+export declare function guessTone(state: string): HistoryTone;
+/** A group heading as a band's label: its number and a trailing "(Apr – May 2026)" go. */
+export declare const bandLabel: (heading: string) => string;
+/**
+ * The walkthrough's older shape in the new one: every group's events on the code lane, each group
+ * with a heading a faint band from its first event to its last. Dates with no year take the year
+ * of the event before (or the first one written).
+ */
+export declare function fromGroups(groups: readonly HistoryGroup[], today: Day): {
+    events: HistoryEvent[];
+    bands: HistoryBand[];
+};
+/** A day as ISO `2026-04-09`. */
+export declare function iso(day: Day): string;
+/** The document filled in: whole days, lanes with their spans and events, the axis and the order. */
+export declare function normalizeHistory(data: HistoryData, now?: Day): HistoryModel;
+/** The order ←/→ walk: by date, then lane (top first), then as written. */
+export declare function eventOrder(events: readonly {
+    item: HyItem;
+    index: number;
+    laneIndex: number;
+}[]): HyItem[];
+/**
+ * The event ←/→ land on from `current`: the next or the one before, stopping at the ends; from
+ * nothing (or a span), → the first and ← the last.
+ */
+export declare function stepEvent(order: readonly HyItem[], current: string | null, dir: 1 | -1): HyItem | null;
+/** Where a day sits across `width` (pixels), and the day at an x. */
+export declare function dayScale(from: Day, to: Day, width: number): {
+    x: (day: number) => number;
+    day: (x: number) => number;
+    /** As a fraction of the width, for `left: n%`. */
+    f: (day: number) => number;
+};
+export interface MonthTick {
+    readonly day: Day;
+    /** `"Apr"`, or the year on January. */
+    readonly label: string;
+}
+/**
+ * A tick on the first of each month inside the axis, thinned to every 2, 3, 6 or 12 months until
+ * neighbours sit at least `minGap` pixels apart. January says its year.
+ */
+export declare function monthTicks(from: Day, to: Day, width: number, minGap?: number): MonthTick[];
+/**
+ * Which labels to draw, left to right: each starts at its `x` and is `w` wide, and one is left out
+ * where it would touch the one before (within `gap`), a reserved box (today's label), or run past
+ * `width`.
+ */
+export declare function fitLabels(labels: readonly {
+    x: number;
+    w: number;
+}[], width: number, reserved?: readonly {
+    x0: number;
+    x1: number;
+}[], gap?: number): boolean[];
+/** A span clipped to the axis, and which ends were cut; null when it's outside it. */
+export declare function clipSpan(from: Day, to: Day, axisFrom: Day, axisTo: Day): {
+    from: Day;
+    to: Day;
+    clipStart: boolean;
+    clipEnd: boolean;
+} | null;
+/**
+ * Where a span's tag goes: the longest of `widths` (pixels, longest first) that fits inside the
+ * bar with `pad` either side, else one that fits after it in `roomAfter`; else none.
+ */
+export declare function fitTag(widths: readonly number[], spanWidth: number, roomAfter: number, pad?: number): {
+    index: number;
+    place: "inside" | "after";
+} | null;
+/** Each band's label room: from its start to its end or the next band's start, if sooner. */
+export declare function bandRoom(bands: readonly HyBand[], x: (day: Day) => number): number[];
+/** The event nearest `day` within `tolerance` days, else null. */
+export declare function nearestEvent(events: readonly HyItem[], day: number, tolerance: number): HyItem | null;
+/** The first sentence of a detail: a tooltip's one line. */
+export declare function firstSentence(text: string | undefined): string;

package/dist/types/ui/history.d.ts

@@ -0,0 +1,33 @@
+import { type HistoryData, type HistoryModel } from "./history-model.js";
+import { type UiLook } from "./look.js";
+export type { HistoryBand, HistoryData, HistoryEvent, HistoryEvidence, HistoryGroup, HistoryLane, HistoryProvenance, HistorySpan, HistoryState, HistoryTone, } from "./history-model.js";
+export interface HistoryOptions extends UiLook {
+    /** Lanes of spans and events (or the walkthrough's `groups` of events): plain JSON. */
+    readonly data: HistoryData;
+    /** The selected event or span's id. */
+    readonly selected?: string | null;
+    /** Clicks and keys moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string | null) => void;
+    /** Draws "Go to step" in the detail of anything with a `step`, and Enter on it. */
+    readonly onJump?: (step: string) => void;
+    /** Its accessible name. */
+    readonly label?: string;
+    /** Under this width (px) lane labels sit above their lanes instead of beside them (560). */
+    readonly narrow?: number;
+}
+export interface History {
+    readonly element: HTMLElement;
+    /** The data filled in: whole days, lanes, the axis and the order ←/→ walk. */
+    readonly model: HistoryModel;
+    readonly selected: string | null;
+    /** Selects an event or span (`null` clears); doesn't call `onSelect`. */
+    select(id: string | null): void;
+    set(data: HistoryData): void;
+    focus(): void;
+    dispose(): void;
+    /** The same as `dispose`. */
+    destroy(): void;
+}
+/** Adds the history's stylesheet once per document. */
+export declare function injectHistoryStyles(doc: Document): void;
+export declare function history(container: HTMLElement, options: HistoryOptions): History;