retake-dev 0.4.0

package/src/shell/40-code.js

@@ -0,0 +1,80 @@
+// Code versions per timeline (with `--code-branches`): when the prototype's
+// source changes, the timeline you're on takes the new code and the moment is
+// rebuilt on it. Each timeline remembers its code; stepping into one checks its
+// code back out, so timelines can differ in code as well as in what happened.
+
+const CODE_BRANCHES = !!(window.__retakeConfig && window.__retakeConfig.codeBranches)
+
+// Checks a version out. { ok } once the files on disk are that version;
+// `left` is the snapshot the server took of the files just before (the real
+// code of the timeline being left, edits of the last moments included).
+async function checkoutCode(version) {
+  try {
+    const r = await api("POST", `checkout?v=${encodeURIComponent(version)}`)
+    if (r.missing) return { ok: false }
+    const v = r.value && typeof r.value === "object" ? r.value : {}
+    return { ok: v.ok !== false, left: v.left || null }
+  } catch (err) {
+    console.warn("[retake] couldn't check out that timeline's code", err)
+    return { ok: false }
+  }
+}
+
+// What the server last said about the code on disk.
+const code = { newest: null }
+async function codeState() {
+  try {
+    const v = await (await fetch("/__retake/version")).json()
+    return v && v.version ? v : null
+  } catch {
+    return null
+  }
+}
+
+// After a checkout: the timeline we left gets the code it really had. The
+// server says so (`left`); an older server doesn't, so a snapshot that
+// appeared during the checkout and belongs to no timeline is taken as it.
+async function settleLeftVersion(leaving, r) {
+  if (!leaving) return
+  if (r.left) {
+    leaving.version = r.left
+    return
+  }
+  const v = await codeState()
+  if (v && v.newest && v.newest !== code.newest && !D.branches.some((b) => b.version === v.newest)) leaving.version = v.newest
+  if (v && v.newest) code.newest = v.newest
+}
+
+if (CODE_BRANCHES) {
+  setInterval(async () => {
+    if (D.switching || !D.PT || D.building || net.restoring) return
+    const v = await codeState()
+    if (!v || D.switching || !D.PT || D.building) return
+    const version = v.version
+    const cur = activeBranch()
+    // Code the server put back at startup isn't an edit made on this
+    // timeline: put this timeline's own code back instead of adopting it.
+    if (v.restored) {
+      if (cur.version && version !== cur.version) await checkoutCode(cur.version)
+      else if (!cur.version) cur.version = version
+      return
+    }
+    if (v.newest) code.newest = v.newest
+    if (!cur.version) {
+      cur.version = version
+      return
+    }
+    if (version === cur.version) return
+    // Not recording yet: just show the new code.
+    if (!D.PT.state().started) {
+      cur.version = version
+      return freshFrame()
+    }
+    // The code changed: the timeline you're on takes it (no new timeline;
+    // those only come from the +). Rebuild this moment on the new code.
+    const st = D.PT.state()
+    const t = st.previewing ? st.previewAt : st.now
+    cur.version = version
+    D.PT.load(JSON.stringify(D.PT.history()), t)
+  }, 500)
+}

package/src/shell/90-handle.js

@@ -0,0 +1,15 @@
+// A handle for tests and debugging. `state` is the live dock state object.
+window.__retakeDock = {
+  state: D,
+  notes: () => D.notes,
+  prompt: (n) => prompt(n),
+  branches: () => D.branches.map((b) => ({ ...b, json: undefined, active: b.id === D.activeId })),
+  scope: () => D.scopeEl,
+  deleteTimeline: (id) => deleteTimeline(id),
+  switchTo: (id, t) => switchTo(id, t),
+  newTimelineAt: (t) => newTimelineAt(t),
+  fitAll: () => fitAll(),
+  checkpoint: () => (D.cp ? { at: D.cp.at, branchId: D.cp.branchId, ready: checkpointReady(D.cp) } : null),
+  goTo: (t, opts) => goTo(t, opts),
+  building: () => (D.building ? { id: D.building.id, target: D.building.target, via: D.building.via, play: !!D.building.play, fork: !!D.building.fork, visible: !!D.building.visible, ready: !!D.building.pt } : null),
+}

package/src/shell/shell.css

@@ -0,0 +1,295 @@
+/* The dock: a glass notch rising from the bottom edge, 16px in from the sides. Sans
+   for words, monospace only for numbers. Each timeline has its own colour;
+   blue dots are things you did, amber is notes. Spacing on a 4/8 grid, 32px
+   controls, every transition under 300ms. */
+:root {
+  --page: #0e0e11;
+  --glass: rgba(20, 20, 24, 0.74);
+  --glass-strong: rgba(26, 26, 31, 0.94);
+  --hair: rgba(255, 255, 255, 0.08);
+  --hair-2: rgba(255, 255, 255, 0.14);
+  --fill: rgba(255, 255, 255, 0.06);
+  --fill-2: rgba(255, 255, 255, 0.1);
+  --fg: #f2f2f5;
+  --white: #fff;
+  --muted: rgba(255, 255, 255, 0.62);
+  --dim: rgba(255, 255, 255, 0.4);
+  --faint: rgba(255, 255, 255, 0.16);
+  --ink: #16161a; /* text on light fills */
+  --amber: #ffb224;
+  --blue: #60a5fa;
+  --green: #4cc38a;
+  --red: #ff6b6b;
+  --mono: "Geist Mono", ui-monospace, "SF Mono", SFMono-Regular, Menlo, monospace;
+  --sans: Geist, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --ease: cubic-bezier(.2, .8, .2, 1);
+  --shadow: 0 16px 48px rgba(0, 0, 0, 0.45), 0 2px 8px rgba(0, 0, 0, 0.3);
+  color-scheme: dark;
+}
+* { box-sizing: border-box; }
+html, body { height: 100%; margin: 0; background: transparent; overflow: hidden; }
+body { font: 400 13px/16px var(--sans); color: var(--fg); -webkit-font-smoothing: antialiased; }
+
+/* ---- stage: the prototype fills the whole window; the notch floats over its
+   bottom edge, so the app's size never changes with the dock's. ---- */
+#wb-stage { position: fixed; inset: 0; overflow: hidden; background: transparent; }
+#wb-stage iframe { position: absolute; left: 0; top: 0; width: 100%; height: 100%; border: 0; display: block; background: transparent; }
+/* Frames being built behind the visible one are never seen (an app with no
+   background of its own would show through), but stay rendered: their replay
+   waits on animation frames. Not visibility:hidden (that would make them unfocusable). */
+#wb-stage iframe.building, #wb-stage iframe.checkpoint { z-index: 0; opacity: 0; pointer-events: none; }
+#wb-stage iframe.live { z-index: 1; }
+/* A swap on a page with a canvas: the real moment fades in over the preview. */
+#wb-stage iframe.leaving { z-index: 0; pointer-events: none; }
+#wb-stage iframe.live[data-enter] { animation: wb-enter 120ms ease-out; }
+@keyframes wb-enter { from { opacity: 0; } }
+/* In the past the app is view-only, like a paused video. */
+#wb-shield { position: absolute; inset: 0; z-index: 2; cursor: default; pointer-events: none; }
+#wb-shield[hidden] { display: none; }
+body.dragging #wb-stage, body.scrubbing #wb-stage { pointer-events: none; }
+
+/* ---- the notch: glass rising from the bottom edge ---- */
+#wb-dock { position: fixed; left: 16px; right: 16px; bottom: 0; z-index: 10; height: 200px; display: flex; flex-direction: column;
+  border-radius: 18px 18px 0 0; border: 0;
+  background: linear-gradient(to bottom, rgba(255, 255, 255, 0.06), rgba(255, 255, 255, 0) 36px), var(--glass);
+  -webkit-backdrop-filter: blur(28px) saturate(160%); backdrop-filter: blur(28px) saturate(160%);
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.10), 0 -8px 32px rgba(0, 0, 0, 0.35); }
+@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+  #wb-dock { background: linear-gradient(to bottom, rgba(255, 255, 255, 0.06), rgba(255, 255, 255, 0) 36px), rgba(20, 20, 24, 0.92); }
+}
+/* The grab handle at the top centre: always there, brighter on hover. */
+.divider { position: absolute; left: 0; right: 0; top: 0; height: 12px; cursor: ns-resize; z-index: 3; display: flex; justify-content: center; }
+.divider span { margin-top: 4px; width: 36px; height: 4px; border-radius: 999px; background: rgba(255, 255, 255, 0.18); transition: background .15s var(--ease), width .15s var(--ease); }
+.divider:hover span, body.dragging .divider span { background: rgba(255, 255, 255, 0.45); width: 44px; }
+
+button { all: unset; cursor: pointer; display: inline-flex; align-items: center; justify-content: center; color: var(--muted);
+  transition: color .15s var(--ease), background-color .15s var(--ease), border-color .15s var(--ease), transform .1s var(--ease); }
+button:focus-visible { outline: 2px solid rgba(96, 165, 250, 0.6); outline-offset: 2px; }
+button:active { transform: scale(0.96); }
+
+/* One 48px row, everything on one centre line; 16px sides like the ruler. */
+.head { position: relative; flex: none; height: 48px; margin-top: 8px; display: flex; align-items: center; gap: 8px; padding: 0 16px; }
+.left, .right { display: flex; align-items: center; gap: 8px; flex: none; }
+.right { margin-left: auto; }
+/* Phone width: the tools scroll sideways rather than run off the edge. */
+@media (max-width: 520px) { .head { padding: 0 10px; gap: 6px; } .readout .phase { display: none; } .right { flex: 0 1 auto; min-width: 0; overflow-x: auto; scrollbar-width: none; } .right::-webkit-scrollbar { display: none; } }
+/* One button style for the text controls: 32px, full round, a ghost fill. */
+.btn { flex: none; height: 32px; padding: 0 14px; gap: 8px; border-radius: 999px; background: var(--fill); color: var(--muted);
+  font: 500 13px/1 var(--sans); box-shadow: inset 0 0 0 1px var(--hair); }
+@media (hover: hover) { .btn:hover { color: var(--white); background: var(--fill-2); } }
+
+/* Transport: play and the clock in one capsule. */
+.transport { display: flex; align-items: center; gap: 10px; height: 36px; padding: 0 14px 0 4px; border-radius: 999px;
+  background: rgba(255, 255, 255, 0.045); box-shadow: inset 0 0 0 1px var(--hair), inset 0 1px 0 rgba(255, 255, 255, 0.05); }
+.play { flex: none; width: 28px; height: 28px; border-radius: 999px; color: var(--ink);
+  background: linear-gradient(to bottom, #fff, #dcdce2); box-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), inset 0 -1px 0 rgba(0, 0, 0, 0.08); }
+@media (hover: hover) { .play:hover { background: linear-gradient(to bottom, #fff, #ececf0); } }
+.play svg { display: block; }
+.play .i-play { margin-left: 2px; }
+.play .i-pause { display: none; }
+.play.playing .i-play { display: none; }
+.play.playing .i-pause { display: block; }
+
+.readout { display: inline-flex; align-items: center; gap: 10px; white-space: nowrap; }
+.readout .t { display: inline-block; min-width: 8ch; font: 500 13px/1 var(--mono); color: var(--fg); font-variant-numeric: tabular-nums; letter-spacing: -0.01em; }
+.readout .t .cs { color: var(--dim); }
+.readout .phase { display: inline-flex; align-items: center; gap: 6px; padding-left: 10px; border-left: 1px solid var(--hair);
+  font: 500 12px/1 var(--sans); color: var(--muted); }
+.readout .phase::before { content: ""; width: 6px; height: 6px; border-radius: 999px; background: var(--dim); }
+.readout .phase[data-phase="live"] { color: var(--fg); }
+.readout .phase[data-phase="live"]::before { background: var(--green); box-shadow: 0 0 0 3px rgba(76, 195, 138, 0.18); animation: live-pulse 2s var(--ease) infinite; }
+.readout .phase[data-phase="playing"]::before { background: var(--blue); box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.18); }
+.readout .phase[data-phase="paused"]::before, .readout .phase[data-phase="scrubbing"]::before { background: var(--amber); box-shadow: 0 0 0 3px rgba(255, 178, 36, 0.16); }
+@keyframes live-pulse { 50% { box-shadow: 0 0 0 5px rgba(76, 195, 138, 0); } }
+
+/* Tools: Hand and Comment as one segmented capsule. */
+.tools { display: flex; gap: 2px; height: 36px; padding: 3px; border-radius: 999px; background: rgba(255, 255, 255, 0.045); box-shadow: inset 0 0 0 1px var(--hair); }
+.tool { width: 30px; height: 30px; border-radius: 999px; color: var(--muted); }
+@media (hover: hover) { .tool:hover { color: var(--white); } }
+.tool.on { color: var(--white); background: var(--fill-2); box-shadow: inset 0 0 0 1px var(--hair-2), 0 1px 2px rgba(0, 0, 0, 0.3); }
+.tool.disabled { opacity: .35; cursor: default; }
+@media (hover: hover) { .tool.disabled:hover { color: var(--muted); } }
+
+/* Notes: just the count, as a badge on the icon. */
+.notes-count { position: relative; flex: none; display: inline-grid; place-items: center; width: 36px; height: 36px; color: var(--dim); }
+.notes-count.has { color: var(--muted); }
+.notes-count .n { position: absolute; top: 2px; right: 0; min-width: 16px; height: 16px; padding: 0 4px; border-radius: 999px; box-sizing: border-box;
+  display: grid; place-items: center; font: 600 10px/1 var(--mono); color: var(--ink); background: var(--amber);
+  box-shadow: 0 0 0 2px rgba(22, 22, 26, 0.9); transform: scale(0); opacity: 0; transition: transform .2s var(--ease), opacity .2s var(--ease); }
+.notes-count.has .n { transform: none; opacity: 1; }
+
+/* The one hint: a small pill. */
+/* Warnings only, centred on the dock. */
+.hint { position: absolute; left: 50%; top: 12px; transform: translateX(-50%); height: 24px; padding: 0 12px; display: inline-flex; align-items: center; border-radius: 999px;
+  font: 500 12px/1 var(--sans); color: var(--muted); background: var(--fill); border: 1px solid var(--hair); white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis; min-width: 0; opacity: 0; transform: translate(-50%, 2px);
+  transition: opacity .2s var(--ease), transform .2s var(--ease); }
+.hint:empty { visibility: hidden; }
+.hint.show { opacity: 1; transform: translateX(-50%); }
+.hint.warn { color: var(--red); border-color: rgba(255, 107, 107, 0.35); }
+
+/* Start fresh's safety net: a toast where the hint sits. */
+#wb-toast { position: absolute; left: 50%; top: 16px; transform: translateX(-50%); z-index: 4; height: 32px; padding: 0 4px 0 12px;
+  display: inline-flex; align-items: center; gap: 8px; border-radius: 999px; background: var(--glass-strong); border: 1px solid var(--hair-2);
+  box-shadow: var(--shadow); font: 500 12px/1 var(--sans); color: var(--fg); animation: card-in .16s var(--ease); }
+#wb-toast[hidden] { display: none; }
+#wb-toast button { height: 24px; padding: 0 10px; border-radius: 999px; background: var(--fill-2); color: var(--white); font: 600 12px/1 var(--sans); }
+@media (hover: hover) { #wb-toast button:hover { background: rgba(255, 255, 255, 0.18); } }
+.head:has(#wb-toast:not([hidden])) .hint { visibility: hidden; }
+
+/* ---- timeline: lane names + the drawing ---- */
+.body { position: relative; flex: 1; min-height: 0; display: flex; padding: 0 16px; }
+.gutter { position: relative; flex: none; width: 120px; overflow: hidden; }
+/* A label: its colour's dot and a short name, on its row; the active row
+   (and the hovered one) have a faint band, which carries on across the track. */
+.lane-name { position: absolute; left: 0; right: 0; padding: 0 8px; display: flex; align-items: center; gap: 8px;
+  font: 500 12px/1 var(--sans); color: rgba(255, 255, 255, 0.55); white-space: nowrap; cursor: pointer; user-select: none;
+  background: transparent; transition: color .15s var(--ease), background-color .15s var(--ease), top .2s var(--ease); }
+.lane-name i { flex: none; width: 8px; height: 8px; border-radius: 999px; background: var(--c); opacity: .55; transition: opacity .15s var(--ease); }
+.lane-name span { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+.lane-name.active { color: var(--white); background: rgba(255, 255, 255, 0.03); }
+.lane-name.active i { opacity: 1; }
+@media (hover: hover) { .lane-name:not(.active):hover { color: var(--fg); background: rgba(255, 255, 255, 0.02); } .lane-name:not(.active):hover i { opacity: .8; } }
+/* A short dock: just the colour dots, the name on hover. */
+.gutter.dots { width: 28px; }
+.gutter.dots .lane-name { padding: 0; justify-content: center; }
+.gutter.dots .lane-name span { display: none; }
+.gutter.dots .lane-name.active i { box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.25); }
+.lane-name input { all: unset; width: 100%; font: inherit; color: var(--white); border-bottom: 1px solid var(--dim); }
+
+.track { position: relative; flex: 1; min-width: 80px; overflow: hidden; cursor: default; touch-action: none; }
+.lines { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; user-select: none; }
+body.scrubbing, body.scrubbing .track { cursor: ew-resize; }
+body.branching .track, body.branching .track * { cursor: crosshair !important; }
+
+/* Following was stopped by hand: this brings it back. */
+.live-btn { position: absolute; right: 8px; top: 24px; z-index: 2; height: 24px; padding: 0 10px; border-radius: 999px;
+  background: var(--fill-2); color: var(--white); font: 500 12px/1 var(--sans); }
+@media (hover: hover) { .live-btn:hover { background: rgba(255, 255, 255, 0.18); } }
+.live-btn[hidden] { display: none; }
+
+/* ruler: numbers are monospace */
+.lines .rule { stroke: var(--hair); stroke-width: 1; }
+.lines .tick { stroke: var(--faint); stroke-width: 1; }
+.lines .tick.major { stroke: var(--dim); }
+.lines .tlabel { font: 400 10px/1 var(--mono); fill: var(--dim); }
+
+/* lanes: each in its colour, full when active, faint otherwise */
+.lines .lane { fill: none; stroke-width: 2; stroke-linecap: round; opacity: .3; transition: opacity .15s var(--ease); }
+.lines .lane.active { opacity: 1; }
+.lines .lane.active.ahead { opacity: .45; }
+.lines .lane.hit { stroke: transparent !important; stroke-width: 16; opacity: 1; cursor: pointer; }
+.lines .lane.hit[data-active] { cursor: default; }
+.lines .lane-end { fill: var(--page); stroke-width: 1.5; }
+
+/* animation blocks: faint, thicker, on the active lane */
+.lines .band { opacity: .22; transition: opacity .15s var(--ease); }
+.lines .band.hot { opacity: .42; }
+.lines .band-hit { fill: transparent; }
+
+/* markers: blue dots for what you did, grey ticks for the rest */
+.lines .mk-dot { fill: var(--blue); stroke: var(--page); stroke-width: 1; }
+.lines .mk-tick { stroke: var(--dim); stroke-width: 1; }
+.lines .mk-tick.hot { stroke: var(--white); }
+.lines .mk-hit { fill: transparent; }
+.lines .bookmark { fill: var(--fg); }
+
+/* playhead and guides */
+.lines .head { stroke: var(--white); stroke-width: 1; pointer-events: none; }
+.lines .head-cap { fill: var(--white); pointer-events: none; }
+.lines .guide { stroke-width: 1; pointer-events: none; }
+.lines .guide-chip { pointer-events: none; }
+.lines .guide-label { font: 500 9px/1 var(--mono); fill: var(--ink); pointer-events: none; }
+.lines .snap { stroke: var(--white); stroke-width: 1; stroke-dasharray: 1 2; pointer-events: none; }
+.lines .snap-dot { fill: var(--page); stroke: var(--white); stroke-width: 1; pointer-events: none; }
+
+/* notes on the timeline */
+.lines .note-mark { cursor: pointer; }
+.lines .note-mark text { font: 600 8px/1 var(--mono); fill: var(--ink); pointer-events: none; }
+
+/* The one hover tooltip: an animation block's, small, above the dock. */
+.tip { position: fixed; z-index: 25; pointer-events: none; max-width: 240px; padding: 6px 8px; font: 400 11px/15px var(--sans); color: var(--fg);
+  background: var(--glass-strong); border: 1px solid var(--hair-2); border-radius: 8px; box-shadow: var(--shadow); animation: card-in .12s var(--ease); }
+.tip[hidden] { display: none; }
+.tip .row { display: flex; gap: 4px; white-space: nowrap; overflow: hidden; }
+.tip .row b { font-weight: 500; flex: none; }
+.tip .row span { color: var(--muted); overflow: hidden; text-overflow: ellipsis; }
+.tip .more { color: var(--dim); }
+
+/* ---- on the prototype ---- */
+#wb-hl { position: fixed; pointer-events: none; border: 1.5px solid var(--amber); border-radius: 4px; z-index: 20; display: none; }
+#wb-hl::after { content: attr(data-label); position: absolute; left: -1.5px; top: -24px; font: 500 11px/1 var(--sans);
+  color: var(--ink); background: var(--amber); padding: 4px 8px; border-radius: 999px; white-space: nowrap; }
+#wb-hl.select { border-color: var(--white); }
+#wb-hl.pseudo { border-style: dashed; }
+/* The layer picker's chip, beside the pointer. */
+#wb-layers { position: fixed; z-index: 21; pointer-events: none; min-width: 140px; max-width: 280px; padding: 4px; border-radius: 8px;
+  background: var(--glass-strong); border: 1px solid var(--hair-2); box-shadow: var(--shadow); font: 400 11px/16px var(--mono); color: var(--muted); }
+#wb-layers[hidden] { display: none; }
+#wb-layers .layer { padding: 2px 6px; border-radius: 4px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#wb-layers .layer.pseudo { padding-left: 14px; }
+#wb-layers .layer.on { color: var(--ink); background: var(--amber); }
+#wb-layers .more { padding: 2px 6px; color: var(--dim); }
+#wb-hl.select::after { background: var(--white); }
+#wb-scope { position: fixed; pointer-events: none; border: 1px dashed var(--muted); border-radius: 8px; z-index: 14; display: none; }
+#wb-pins { position: fixed; inset: 0; pointer-events: none; z-index: 15; }
+.canvas-pin { position: fixed; pointer-events: auto; width: 20px; height: 20px; margin: -10px 0 0 -10px; border-radius: 999px; background: var(--amber);
+  color: var(--ink); font: 600 11px/1 var(--mono); box-shadow: 0 0 0 2px rgba(22, 22, 26, 0.85), var(--shadow); transition: transform .12s var(--ease), opacity .15s var(--ease); }
+@media (hover: hover) { .canvas-pin:hover { transform: scale(1.12); } }
+.canvas-pin.away { opacity: .45; }
+@media (hover: hover) { .canvas-pin.away:hover { opacity: 1; } }
+
+/* ---- popovers: a note, a context menu ---- */
+.card { position: fixed; z-index: 30; width: 320px; padding: 16px; border-radius: 12px; color: var(--fg);
+  background: var(--glass-strong); -webkit-backdrop-filter: blur(24px) saturate(140%); backdrop-filter: blur(24px) saturate(140%);
+  border: 1px solid var(--hair-2); box-shadow: var(--shadow); animation: card-in .16s var(--ease); }
+@keyframes card-in { from { opacity: 0; transform: translateY(4px); } }
+.card[hidden] { display: none; }
+/* The arrow points at the exact spot the note is about. */
+.card .arrow { position: absolute; width: 12px; height: 12px; background: var(--glass-strong); border: 1px solid var(--hair-2); transform: rotate(45deg); }
+.card[data-side="below"] .arrow { top: -7px; border-right: 0; border-bottom: 0; }
+.card[data-side="above"] .arrow { bottom: -7px; border-left: 0; border-top: 0; }
+.card[data-side="right"] .arrow { left: -7px; border-right: 0; border-top: 0; }
+.card[data-side="left"] .arrow { right: -7px; border-left: 0; border-bottom: 0; }
+
+.note-meta { display: flex; align-items: center; gap: 8px; font: 500 12px/16px var(--sans); color: var(--muted); min-width: 0; }
+.note-meta .dot { flex: none; width: 8px; height: 8px; border-radius: 999px; }
+.note-meta .time { flex: none; font-family: var(--mono); color: var(--fg); }
+.note-meta .el { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--amber); }
+.card textarea { display: block; width: 100%; margin-top: 8px; resize: none; background: transparent; border: 0; color: var(--fg);
+  font: 400 14px/20px var(--sans); outline: none; padding: 0; }
+.card textarea::placeholder { color: var(--dim); }
+.note-text { margin: 8px 0 0; font-size: 14px; line-height: 20px; white-space: pre-wrap; overflow-wrap: anywhere; }
+.note-clip { margin-top: 8px; font: 400 12px/16px var(--sans); color: var(--muted); }
+.details { margin-top: 8px; font-size: 12px; line-height: 16px; color: var(--muted); }
+.details summary { cursor: pointer; list-style: none; color: var(--dim); user-select: none; }
+.details summary::-webkit-details-marker { display: none; }
+.details summary::before { content: "›"; display: inline-block; width: 12px; transition: transform .15s var(--ease); }
+.details[open] summary::before { transform: rotate(90deg); }
+.details dl { margin: 8px 0 0; display: grid; grid-template-columns: auto 1fr; gap: 4px 8px; }
+.details dt { color: var(--dim); }
+.details dd { margin: 0; font-family: var(--mono); font-size: 11px; color: var(--fg); overflow-wrap: anywhere; }
+.replies { margin-top: 8px; display: flex; flex-direction: column; gap: 8px; border-top: 1px solid var(--hair); padding-top: 8px; }
+.reply { font-size: 13px; line-height: 18px; color: var(--fg); }
+.reply .who { display: block; font: 500 11px/16px var(--sans); color: var(--dim); }
+.reply.agent .who { color: var(--blue); }
+.note-actions { display: flex; justify-content: flex-end; align-items: center; gap: 8px; margin-top: 16px; }
+.note-actions .status { margin-right: auto; font: 500 11px/1 var(--sans); color: var(--amber); }
+.note-actions .status.s-acknowledged { color: var(--blue); }
+.note-actions .status.s-resolved { color: var(--green); }
+.note-actions .status.s-dismissed { color: var(--dim); }
+.note-actions button { height: 32px; padding: 0 12px; white-space: nowrap; border-radius: 8px; font: 500 13px/1 var(--sans); color: var(--muted); }
+@media (hover: hover) { .note-actions button:hover { color: var(--white); background: var(--fill-2); } }
+.note-actions button.quiet { padding: 0 8px; color: var(--dim); }
+@media (hover: hover) { .note-actions button.quiet:hover { color: var(--red); background: rgba(255, 107, 107, 0.1); } }
+.note-actions button.primary { background: var(--white); color: var(--ink); }
+@media (hover: hover) { .note-actions button.primary:hover { background: #e6e6ea; color: var(--ink); } }
+
+
+.ctx { width: auto; min-width: 180px; padding: 4px; }
+.ctx button { display: flex; width: 100%; justify-content: flex-start; padding: 8px; border-radius: 8px; font: 500 13px/1 var(--sans); }
+@media (hover: hover) { .ctx button:hover { background: var(--fill); color: var(--white); } }
+.ctx button.danger { color: var(--red); }
+.ctx .menu-note { padding: 8px; color: var(--dim); font-size: 12px; line-height: 16px; }
+
+@media (prefers-reduced-motion: reduce) { * { animation-duration: 0s !important; transition-duration: 0s !important; } }

package/src/shell/shell.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Prototype</title>
+    <style>/*CSS*/</style>
+  </head>
+  <body>
+    <div id="wb-stage"><div id="wb-shield" hidden></div></div>
+    <div id="wb-dock" role="region" aria-label="Retake timeline">
+      <div class="divider" role="separator" aria-orientation="horizontal" aria-label="Resize the timeline"><span></span></div>
+      <div class="head">
+        <div class="left">
+          <div class="transport">
+            <button class="play" data-a="play" aria-label="Play">
+              <svg class="i-play" viewBox="0 0 16 16" width="12" height="12"><path d="M5 3.4v9.2c0 .5.55.8.97.53l7.1-4.6a.63.63 0 0 0 0-1.06l-7.1-4.6A.63.63 0 0 0 5 3.4z" fill="currentColor"/></svg>
+              <svg class="i-pause" viewBox="0 0 16 16" width="12" height="12"><rect x="3.5" y="3" width="3" height="10" rx="1" fill="currentColor"/><rect x="9.5" y="3" width="3" height="10" rx="1" fill="currentColor"/></svg>
+            </button>
+            <span class="readout" aria-live="off"><b class="t">00:00.00</b><span class="phase">Live</span></span>
+          </div>
+        </div>
+        <div class="hint" aria-live="polite"></div>
+        <div id="wb-toast" role="status" hidden><span>Session cleared</span><button data-a="undo">Undo</button></div>
+        <div class="right">
+          <div class="tools" role="tablist" aria-label="Tool">
+            <button class="tool" data-tool="hand" role="tab" aria-label="Hand">
+              <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M18 11V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 10.5V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2v8"/><path d="M18 8a2 2 0 1 1 4 0v6a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/></svg>
+            </button>
+            <button class="tool" data-tool="comment" role="tab" aria-label="Comment">
+              <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"/></svg>
+            </button>
+          </div>
+          <span class="notes-count" role="status" aria-label="No notes on this timeline" title="Notes on this timeline">
+            <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M14 9a2 2 0 0 1-2 2H6l-4 4V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2z"/><path d="M18 9h2a2 2 0 0 1 2 2v11l-4-4h-6a2 2 0 0 1-2-2v-1"/></svg>
+            <span class="n">0</span>
+          </span>
+          <button class="btn fresh" data-a="fresh">Start fresh</button>
+        </div>
+      </div>
+      <div class="body">
+        <div class="gutter" aria-label="Timelines"></div>
+        <div class="track">
+          <canvas class="lines" aria-label="Timeline"></canvas>
+          <button class="live-btn" data-a="live" hidden>Live →</button>
+        </div>
+      </div>
+    </div>
+    <div id="wb-tip" class="tip" hidden></div>
+    <div id="wb-layers" hidden></div>
+    <div id="wb-hl"></div>
+    <div id="wb-scope"></div>
+    <div id="wb-pins"></div>
+    <div id="wb-note" class="card" hidden></div>
+    <div id="wb-menu" class="card ctx" hidden></div>
+    <script>/*CONFIG*/</script>
+    <script>/*JS*/</script>
+  </body>
+</html>

package/types/client.d.ts

@@ -0,0 +1,73 @@
+// Types for the runtime API, `window.__retake`, in the dock's app frame
+// (CONTRACT.md, "Runtime API"). Add them to a project with
+// `/// <reference types="retake-dev/client" />` or `"types": ["retake-dev/client"]`.
+//
+// In a page Retake isn't running in (any iframe the dock didn't make), it's
+// `{ inert: true }`; with no Retake at all it's undefined.
+
+export interface RetakeMarker {
+  t: number
+  /** "type" is one burst of typing (gaps under 800ms). */
+  end?: number
+  kind: "click" | "submit" | "route" | "focus" | "type"
+  label: string
+  selector?: string
+}
+
+export interface RetakeClip {
+  id: string | number
+  start: number
+  end: number | null
+  kind: "transition" | "css-animation" | "waapi"
+  label: string
+  selector: string
+  component?: string
+  property?: string
+  path: Array<string | number>
+  iterations?: "infinite" | number
+  pseudoElement?: string
+}
+
+/** 10 Hz samples: `v` 0..1 is the share of the viewport that changed (baselined); `t` is the window start. */
+export type RetakeActivity = Array<{ t: number; v: number }> & { step?: number; t0?: number; values?: number[] }
+
+export interface RetakeTimeline {
+  now: number
+  end: number
+  viewport: { w: number; h: number }
+  /** User actions only. */
+  markers: RetakeMarker[]
+  clips: RetakeClip[]
+  activity: RetakeActivity
+}
+
+export interface RetakeRuntime {
+  readonly inert?: false
+  version: string
+  /** The virtual clock, in ms. */
+  now(): number
+  timeline(): RetakeTimeline
+  /** Clips on that element and its descendants, looping ones included. */
+  clipsFor(target: Element | string): RetakeClip[]
+  /** The latest clip running at `t` (on `selector`, or inside it); `offset` is ms into it. */
+  clipAt(t: number, selector?: string): { clip: RetakeClip; offset: number } | null
+  /** True only while playing at the live edge. */
+  isInteractive(): boolean
+  isPaused(): boolean
+  /** Called on every play/pause change. Returns an unsubscribe. */
+  onPlayState(fn: (state: { playing: boolean; now: number }) => void): () => void
+  /** Play from here: replays the recorded future, then carries on live. */
+  play(): void
+  pause(): void
+  /** Starts the timeline, or resumes recording from its end. */
+  record(): void
+  /** Go to moment `t` (ends a preview). False before anything was recorded. */
+  seek(t: number, play?: boolean): boolean | void
+  setToolActive(on: boolean): void
+}
+
+declare global {
+  interface Window {
+    __retake?: RetakeRuntime | { readonly inert: true }
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,111 @@
+// Types for `retake-dev`: the Vite plugin and the pieces a server shares to
+// dock Retake into pages it serves (src/plugin.js, src/core.js).
+import type { Transform } from "node:stream"
+import type { Plugin } from "vite"
+
+/** Options for the Vite plugin. Dev only: it does nothing in builds. */
+export interface RetakeOptions {
+  /** `false` turns the plugin off (the pages are served as they are). Default `true`. */
+  enabled?: boolean
+  /**
+   * Each timeline keeps its own version of the code: stepping into a
+   * timeline checks its code out on disk. It rewrites your source files.
+   * Default `false`.
+   */
+  codeBranches?: boolean
+  /**
+   * The token mutating `/__retake/` requests must carry (header
+   * `x-retake-token`). Default: a random one per server start.
+   */
+  token?: string
+  /** Where `.retake/` (sessions, recordings, notes) goes. Default: Vite's root. */
+  root?: string
+  /** `false` hides the "Retake  timeline docked at …" line on startup. Default `true`. */
+  banner?: boolean
+}
+
+/**
+ * The Vite plugin: the dock for page loads, the time runtime in the dock's
+ * frame, and the session API under `/__retake/`.
+ *
+ * ```ts
+ * import { defineConfig } from "vite"
+ * import { retake } from "retake-dev"
+ * export default defineConfig({ plugins: [retake()] })
+ * ```
+ */
+export function retake(options?: RetakeOptions): Plugin[]
+export default retake
+
+/** How the runtime is set up for the server it runs behind (`RT` in the runtime). */
+export interface RuntimeConfig {
+  /**
+   * How the dock's frame is known: `"url"` (its URL carries `__wb=app`, the
+   * Vite plugin's way) or `"header"` (the server tells by `Sec-Fetch-Dest`).
+   * Default `"url"`.
+   */
+  marker?: "url" | "header"
+  /** When the clock starts: at DOMContentLoaded (`"dcl"`, default) or at `load`. */
+  bootAt?: "dcl" | "load"
+  /** The dev server's own traffic (regular expression sources), never recorded or held. */
+  exemptUrls?: string[]
+  /** Scripts added after load are held to their recorded moment. Default `false`. */
+  holdScripts?: boolean
+  /**
+   * The Next.js major version, for its dev debug channel; `"auto"`: the
+   * runtime asks Next's client. Default `null` (not Next).
+   */
+  next?: number | "auto" | null
+  /** This page's kept copy on the front server. Default `null`. */
+  docId?: string | null
+  /** Whether this page is that kept copy. Default `false`. */
+  docStored?: boolean
+}
+
+/** The time runtime as JavaScript source: one IIFE, to run as the page's first script. */
+export function runtimeSource(rt?: RuntimeConfig): string
+
+/** Options for the dock page. */
+export interface ShellOptions {
+  /** Show the code-branch controls (needs a server running with code branches). */
+  codeBranches?: boolean
+  /**
+   * The path the dock's frame always loads (a static build that ships the
+   * app as a page of its own). Default: the page's own URL.
+   */
+  appPage?: string
+  /** How the dock marks its frame; see {@link RuntimeConfig.marker}. Default `"url"`. */
+  marker?: "url" | "header"
+  /** Rebuilds ask the server for the page as it was recorded (front server only). */
+  docs?: boolean
+  /** The token mutating `/__retake/` requests carry. */
+  token?: string
+}
+
+/** The dock page: a complete HTML document with the app in a frame. */
+export function shellHtml(options?: ShellOptions): string
+
+export interface RuntimeTagOptions {
+  /** The runtime's setup. */
+  rt?: RuntimeConfig
+  /** A CSP nonce for the `<script>` tag. */
+  nonce?: string | null
+  /** The script to wrap. Default: the guarded runtime for `rt`. */
+  script?: string
+}
+
+/**
+ * The `<script data-retake>` tag a server injects into a page: it removes
+ * itself, then runs the runtime only in a frame the dock made.
+ */
+export function runtimeTag(options?: RuntimeTagOptions): string
+
+/**
+ * A byte stream transform that inserts `tag` into an HTML document as it
+ * streams: after the `<head>` opening tag (and a `<meta charset>` right after
+ * it), else before the first `<body>`, `<script>`, `<link>`, `<meta>`,
+ * `<style>` or `<title>`. A compressed body (`encoding`: gzip, br, deflate,
+ * zstd) is decoded first and the output is plain. Throws for an encoding it
+ * can't decode.
+ */
+export function injectHtml(tag: string, options?: { encoding?: string }): Transform