retake-dev 0.4.0 → 0.5.1

package/src/shell/10-dock.js

@@ -8,9 +8,14 @@ const dock = $("#wb-dock")
 const track = $(".track")
 const cv = $(".lines") // the timeline canvas
 
+// Timelines are "Timeline 1", "Timeline 2"... until the user renames one.
+const defaultName = (id) => `Timeline ${id}`
+// Older sessions named them "Main" and "Take N": those defaults
+// (and only those) read as the new ones.
+const migratedName = (b) => (b.name === (b.id === 1 ? "Main" : `Take ${b.id}`) ? defaultName(b.id) : b.name)
 const newBranch = (forkAt, parentId = null) => {
   const id = ++D.branchSeq
-  const b = { id, name: id === 1 ? "Main" : `Take ${id}`, forkAt, parentId, json: null, end: forkAt, born: performance.now() }
+  const b = { id, name: defaultName(id), forkAt, parentId, json: null, end: forkAt, born: performance.now() }
   D.branches.push(b)
   return b
 }
@@ -85,6 +90,10 @@ function swapIn(b) {
   } catch {}
   f.className = "live"
   f.removeAttribute("aria-hidden")
+  // The new frame is the one on show before the old one goes: the old one
+  // blurs as it's removed, which must not read as ⌘ let go (F99).
+  D.frame = f
+  D.PT = pt
   if (old) {
     let canvas = false
     try {
@@ -97,14 +106,14 @@ function swapIn(b) {
       setTimeout(() => delete f.dataset.enter, 200)
     } else old.remove()
   }
-  D.frame = f
-  D.PT = pt
   D.frameBranch = b.branchId != null ? b.branchId : D.activeId
   D.building = null
   window.__retakeShell.rebuilding = false
   D.scopeEl = null // an element of the old frame
   noteBuilt(b)
   hookFrameKeys(f.contentWindow)
+  // A tool that's on stays on, in the new frame, over what's under the pointer.
+  syncPicking()
   if (b.fork) forkNow()
   else if (b.play) pt.play()
 }
@@ -257,6 +266,7 @@ window.__retakeShell = {
     b.version = old.version // a new timeline starts on its parent's code
     D.activeId = b.id
     D.frameBranch = b.id // the visible frame carries on as the new timeline
+    flash(`${b.name} started`, { warn: false })
   },
 }
 
@@ -548,6 +558,7 @@ function render() {
   const dh = dockHeight()
   dock.style.height = dh + "px"
   document.body.style.setProperty("--dock-h", dh + "px")
+  tellDock(D.collapsed ? 0 : dh)
   if (!s || !D.frame) return
   autoStart(s)
   if (D.perfNoDraw) return // (perf measurements: the runtime alone)
@@ -561,6 +572,21 @@ function render() {
   renderShield(s)
   if (s.started) renderTimeline(s, shownT)
   renderExtras(s)
+  renderFocusOverlay(s)
+  if (D.collapsed && fab.dataset.phase !== readoutPhase.dataset.phase) fab.dataset.phase = readoutPhase.dataset.phase
+}
+
+// The app is full-window under the dock. So that it can leave room, the frame
+// on show gets `window.__retakeDockHeight` (the px the dock covers at the
+// bottom, 0 when folded) and a `retake:dock` event ({ detail: { height } })
+// whenever that changes.
+function tellDock(height) {
+  try {
+    const win = /** @type {any} */ (D.frame && D.frame.contentWindow)
+    if (!win || win.__retakeDockHeight === height) return
+    win.__retakeDockHeight = height
+    win.dispatchEvent(new win.CustomEvent("retake:dock", { detail: { height } }))
+  } catch {}
 }
 
 // A frame built behind can take the window's focus (its replay focused a
@@ -667,11 +693,16 @@ const refocus = () => D.frame && D.frame.contentWindow && D.frame.contentWindow.
 document.addEventListener("click", (e) => {
   const target = /** @type {Element} */ (e.target)
   const b = /** @type {HTMLButtonElement | null} */ (target.closest("button, [data-branch], [data-note]"))
+  // A press on the track while writing a note (the element row, a range, the
+  // playhead) keeps the note open.
+  const held = D.focusHold
+  D.focusHold = false
   if (!b) {
-    if (!target.closest(".card")) closeCard()
+    if (!target.closest(".card") && !(held && target.closest(".track"))) closeCard()
     return
   }
   const a = b.dataset.a
+  if (a === "expand") return setCollapsed(false)
   if (a === "play") togglePlay()
   if (a === "fresh") return startFresh()
   if (a === "undo") return undoFresh()
@@ -695,35 +726,193 @@ document.addEventListener("click", (e) => {
 // The dock never grows by itself (that would resize the app mid-recording);
 // only the divider changes it.
 const MIN_H = 96
+const DEFAULT_H = 200
 // Never so short that the lanes (at their closest) don't fit under the ruler.
+const minDockHeight = () => Math.max(MIN_H, 56 + 24 + D.branches.length * 10 + 16)
 const dockHeight = () => {
-  const min = Math.max(MIN_H, 56 + 24 + D.branches.length * 10 + 16)
+  const min = minDockHeight()
   return Math.round(clamp(D.height, min, Math.max(min, innerHeight * 0.7)))
 }
 
-// Resize by dragging the top edge, like docked DevTools.
+// Resize by dragging the top edge, like docked DevTools. Below the minimum
+// height the dock keeps following the pointer: it slides down (a transform, so
+// neither its layout nor the app's changes mid-drag) all the way off the edge.
+// Let go far enough down and it settles into the corner icon; anywhere higher
+// it springs back up to the minimum.
 const divider = $(".divider")
 divider.addEventListener("pointerdown", (e) => {
   divider.setPointerCapture(e.pointerId)
   document.body.classList.add("dragging")
   const startY = e.clientY
   const startH = dock.offsetHeight
+  const min = minDockHeight()
+  let fold = false
+  let lastY = startY
+  let raf = 0
+  // One write per frame, whatever the pointer's rate.
+  const paint = () => {
+    raf = 0
+    const want = startH + startY - lastY
+    D.height = Math.round(clamp(want, min, innerHeight * 0.7))
+    const drop = clamp(min - want, 0, min + 24)
+    fold = drop > min / 2 || lastY >= innerHeight - FOLD_EDGE
+    dock.style.transform = drop ? `translateY(${drop}px)` : ""
+    dock.classList.toggle("will-collapse", fold)
+  }
   const move = (ev) => {
-    D.height = Math.round(clamp(startH + startY - ev.clientY, MIN_H, innerHeight * 0.7))
+    lastY = ev.clientY
+    if (!raf) raf = requestAnimationFrame(paint)
   }
-  const up = () => {
+  // A touch the browser takes back (pointercancel) ends the drag too, or the
+  // app would stay unclickable under body.dragging.
+  const up = (ev) => {
+    for (const type of ["pointermove", "pointerup", "pointercancel", "lostpointercapture"]) divider.removeEventListener(type, type === "pointermove" ? move : up)
+    if (raf) cancelAnimationFrame(raf)
+    if (ev.type !== "pointercancel" && ev.type !== "lostpointercapture") {
+      lastY = ev.clientY
+      paint()
+    }
+    // From where the finger left it: on into the icon, or back up.
     document.body.classList.remove("dragging")
-    divider.removeEventListener("pointermove", move)
-    divider.removeEventListener("pointerup", up)
+    dock.classList.remove("will-collapse")
+    dock.style.transform = ""
     store.set("height", D.height)
+    if (fold && ev.type !== "pointercancel") setCollapsed(true)
   }
   divider.addEventListener("pointermove", move)
-  divider.addEventListener("pointerup", up)
+  for (const type of ["pointerup", "pointercancel", "lostpointercapture"]) divider.addEventListener(type, up)
+})
+
+// Folded: the timeline is a round button (bottom-right at first) and the app
+// has the whole window. It keeps recording; the button (or ⌥T) brings the dock
+// back at its default height. Remembered across reloads.
+const FOLD_EDGE = 48 // px from the bottom edge: let go there and it folds
+const fab = $("#wb-fab")
+function applyCollapsed() {
+  document.body.classList.toggle("collapsed", D.collapsed)
+  fab.hidden = !D.collapsed
+  dock.inert = D.collapsed
+  if (D.collapsed) placeFab()
+}
+
+// The button can be dragged anywhere (mouse or finger). Past a few px it's a
+// drag, not a click; let go and it eases to the nearer side edge. Where it is
+// (`D.fab`: that side, and how far down) is stored, so a reload or a resized
+// window puts it back in the same place, always fully on screen.
+const FAB_SIZE = 44
+const FAB_MARGIN = 16
+const FAB_SLOP = 5 // px a press may move and still be a click
+let fabDragged = false // the press that just ended was a drag: not a click
+// The notch and the home bar (viewport-fit=cover), measured once per layout.
+const safeProbe = document.createElement("div")
+safeProbe.style.cssText =
+  "position:fixed;visibility:hidden;pointer-events:none;padding:env(safe-area-inset-top,0px) env(safe-area-inset-right,0px) env(safe-area-inset-bottom,0px) env(safe-area-inset-left,0px)"
+document.body.appendChild(safeProbe)
+function fabBounds() {
+  const cs = getComputedStyle(safeProbe)
+  const left = FAB_MARGIN + (parseFloat(cs.paddingLeft) || 0)
+  const top = FAB_MARGIN + (parseFloat(cs.paddingTop) || 0)
+  const right = Math.max(left, innerWidth - FAB_SIZE - FAB_MARGIN - (parseFloat(cs.paddingRight) || 0))
+  const bottom = Math.max(top, innerHeight - FAB_SIZE - FAB_MARGIN - (parseFloat(cs.paddingBottom) || 0))
+  return { left, top, right, bottom }
+}
+function moveFab(x, y) {
+  fab.style.left = Math.round(x) + "px"
+  fab.style.top = Math.round(y) + "px"
+}
+function placeFab() {
+  const b = fabBounds()
+  moveFab(D.fab.side === "left" ? b.left : b.right, b.top + D.fab.y * (b.bottom - b.top))
+}
+applyCollapsed()
+addEventListener("resize", () => D.collapsed && !fab.classList.contains("moving") && placeFab())
+
+fab.addEventListener("pointerdown", (e) => {
+  fabDragged = false
+  if (e.button !== 0) return
+  const r = fab.getBoundingClientRect()
+  const grabX = e.clientX - r.left
+  const grabY = e.clientY - r.top
+  const x0 = e.clientX
+  const y0 = e.clientY
+  let moving = false
+  fab.setPointerCapture(e.pointerId)
+  const move = (ev) => {
+    if (!moving && Math.hypot(ev.clientX - x0, ev.clientY - y0) < FAB_SLOP) return
+    if (!moving) {
+      moving = true
+      fab.classList.remove("snapping")
+      fab.classList.add("moving")
+    }
+    const b = fabBounds()
+    moveFab(clamp(ev.clientX - grabX, b.left, b.right), clamp(ev.clientY - grabY, b.top, b.bottom))
+  }
+  const up = () => {
+    for (const type of ["pointermove", "pointerup", "pointercancel"]) fab.removeEventListener(type, type === "pointermove" ? move : up)
+    if (!moving) return
+    fabDragged = true
+    fab.classList.remove("moving")
+    // Where it was let go (its left/top: the rect would include the lift's scale).
+    const b = fabBounds()
+    const x = parseFloat(fab.style.left) || 0
+    const y = parseFloat(fab.style.top) || 0
+    D.fab = {
+      side: x + FAB_SIZE / 2 < innerWidth / 2 ? "left" : "right",
+      y: b.bottom > b.top ? clamp((y - b.top) / (b.bottom - b.top), 0, 1) : 1,
+    }
+    store.set("fab", D.fab)
+    fab.classList.add("snapping")
+    placeFab()
+    setTimeout(() => fab.classList.remove("snapping"), 400)
+  }
+  fab.addEventListener("pointermove", move)
+  fab.addEventListener("pointerup", up)
+  fab.addEventListener("pointercancel", up)
 })
+// The click that ends a drag doesn't open the dock.
+fab.addEventListener(
+  "click",
+  (e) => {
+    if (!fabDragged) return
+    fabDragged = false
+    e.stopPropagation()
+    e.preventDefault()
+  },
+  true,
+)
+function setCollapsed(on) {
+  if (on === D.collapsed) return
+  const hadFocus = on ? dock.contains(document.activeElement) : document.activeElement === fab
+  if (on) {
+    setPicking(null)
+    closeCard()
+  } else {
+    D.height = DEFAULT_H
+    store.set("height", D.height)
+  }
+  D.collapsed = on
+  store.set("collapsed", on)
+  applyCollapsed()
+  if (hadFocus) (on ? fab : playBtn).focus({ preventScroll: true })
+}
 
 window.addEventListener("keydown", (e) => {
   if (e.key === "Meta") return window.__retakeShell.meta(true)
+  // The corner button is a real button: Enter and Space press it.
+  if (e.target === fab && (e.key === "Enter" || e.code === "Space")) return
+  // Not while typing in the dock (a note, a timeline's name): ⌥T types there († on a Mac).
+  if (e.altKey && e.code === "KeyT" && !typing(e.target)) {
+    e.preventDefault()
+    return setCollapsed(!D.collapsed)
+  }
+  // Tab with the dock's window focused cycles what's under the pointer, as in the app.
+  if (e.key === "Tab" && !e.metaKey && mode() && !typing(e.target) && layers.length > 1) {
+    e.preventDefault()
+    return cycleLayer(e.shiftKey ? -1 : 1)
+  }
   if (e.key === "Escape") {
+    // An open clip closes first, then a selected range, then the note.
+    if (closeFocusClip() || clearRange()) return
     setPicking(null)
     closeCard()
     return
@@ -750,5 +939,11 @@ function hookFrameKeys(win) {
     )
   } catch {}
 }
-window.addEventListener("keyup", (e) => e.key === "Meta" && window.__retakeShell.meta(false))
-window.addEventListener("blur", () => window.__retakeShell.meta(false))
+window.addEventListener("keyup", (e) => e.key === "Meta" && setMeta(false))
+// The dock's window losing focus lets go of ⌘, unless the focus only went
+// into the app's frame (whose own blur, if it goes, says so).
+window.addEventListener("blur", () => {
+  const a = document.activeElement
+  if (a && a.tagName === "IFRAME") return
+  window.__retakeShell.meta(false)
+})

package/src/shell/15-session.js

@@ -2,11 +2,13 @@
 // (/__retake/session, kept on disk under <project>/.retake/) so a reload or a
 // restart doesn't lose them; each timeline's recording goes to
 // /__retake/recording/:id. Agents reply to notes over /__retake/events.
-// When the server has no session API (it answers 404), everything stays in
-// memory for this page.
+// When the server has no session API (it answers 404), or the page says
+// there's no server at all (`__retakeConfig.server === false`, a static
+// deploy), everything stays in memory for this page.
 const TOKEN = window.__RETAKE_TOKEN || ""
+const SERVER = !(window.__retakeConfig && window.__retakeConfig.server === false)
 const net = {
-  on: true, // false: in-memory only
+  on: SERVER, // false: in-memory only
   restoring: true, // nothing is saved until what's on disk has been read
   savedSession: null, // the last session body the server has
   savedRec: new Map(), // branch id → the recording string the server has
@@ -14,15 +16,21 @@ const net = {
   activeSavedAt: 0,
 }
 
+const GZIP_OVER = 1 << 20
+
 async function api(method, path, body) {
   const headers = {}
   if (method !== "GET") headers["x-retake-token"] = TOKEN
   if (body !== undefined) headers["content-type"] = "application/json"
-  const res = await fetch("/__retake/" + path, {
-    method,
-    headers,
-    body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body),
-  })
+  /** @type {string | Blob | undefined} */
+  let data = body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body)
+  // A large upload goes gzipped (JSON shrinks ~10x): a Next.js middleware
+  // (retake-dev/next) gets 10 MB of a request body at most.
+  if (typeof data === "string" && data.length > GZIP_OVER && typeof CompressionStream === "function") {
+    data = await new Response(new Blob([data]).stream().pipeThrough(new CompressionStream("gzip"))).blob()
+    headers["content-encoding"] = "gzip"
+  }
+  const res = await fetch("/__retake/" + path, { method, headers, body: data })
   if (res.status === 404) return { missing: true }
   if (!res.ok) throw new Error(`${method} /__retake/${path}: ${res.status}`)
   const text = await res.text()
@@ -40,7 +48,7 @@ function sessionBody() {
 }
 
 function applySession(s) {
-  D.branches = s.branches.map((b) => ({ ...b, version: b.codeVersion || undefined, json: null, end: b.end ?? b.forkAt, born: -1e9 }))
+  D.branches = s.branches.map((b) => ({ ...b, name: migratedName(b), version: b.codeVersion || undefined, json: null, end: b.end ?? b.forkAt, born: -1e9 }))
   D.branchSeq = Math.max(0, ...D.branches.map((b) => b.id))
   D.activeId = D.branches.some((b) => b.id === s.activeId) ? s.activeId : D.branches[0].id
   D.markers = Array.isArray(s.markers) ? s.markers : []
@@ -83,6 +91,7 @@ async function restore() {
     return b.id
   }
   try {
+    if (!SERVER) return
     const r = await api("GET", "session")
     if (r.missing) {
       net.on = false
@@ -93,7 +102,7 @@ async function restore() {
     applySession(s)
     net.savedSession = JSON.stringify(sessionBody())
     known = true
-    const json = await recordingOf(activeBranch())
+    const json = newerThanSaved(await recordingOf(activeBranch()))
     if (D.frame) {
       // Opened fresh already (the session was slow): that visit is its own.
       D.frameBranch = ownTimeline()
@@ -119,6 +128,53 @@ async function restore() {
   }
 }
 
+// Leaving the page (a new address typed in, a reload of the dock) while
+// recording: the server has the recording as it was at the last save, up to
+// five seconds ago. What came after is kept in this tab's sessionStorage on
+// the way out, and restore() carries on from it (F78).
+const LIVE_KEY = KEY + "live"
+function takeLiveStash() {
+  try {
+    const v = sessionStorage.getItem(LIVE_KEY)
+    sessionStorage.removeItem(LIVE_KEY) // the app's frame shares this storage
+    return v ? JSON.parse(v) : null
+  } catch {
+    return null
+  }
+}
+const liveStash = SERVER ? takeLiveStash() : null
+// The saved recording, or what this tab kept of the same recording (same
+// timeline, same epoch) when it's further along.
+function newerThanSaved(json) {
+  const kept = liveStash
+  if (!json || !kept || kept.branchId !== D.activeId || typeof kept.rec !== "string") return json
+  try {
+    const saved = JSON.parse(json)
+    const rec = JSON.parse(kept.rec)
+    if (rec.epoch !== saved.epoch || !(rec.end > saved.end)) return json
+  } catch {
+    return json
+  }
+  activeBranch().json = kept.rec
+  return kept.rec
+}
+window.addEventListener("pagehide", () => {
+  if (!net.on || net.restoring || net.hold || !D.PT || D.building || D.frameBranch !== D.activeId) return
+  try {
+    const s = D.PT.state()
+    if (!s.started || s.seeking) return
+    const rec = JSON.stringify(D.PT.history())
+    if (rec === net.savedRec.get(D.activeId)) return
+    sessionStorage.setItem(LIVE_KEY, JSON.stringify({ branchId: D.activeId, rec }))
+  } catch {}
+})
+// Back from the back/forward cache: this page carries on, nothing to keep.
+window.addEventListener("pageshow", (e) => {
+  try {
+    if (e.persisted) sessionStorage.removeItem(LIVE_KEY)
+  } catch {}
+})
+
 // The active timeline's recording is saved when it's still (paused), and every
 // few seconds while it's live.
 function activeSig(s) {

package/src/shell/20-timeline.js

@@ -41,7 +41,6 @@ const MONO = '10px "Geist Mono", ui-monospace, "SF Mono", Menlo, monospace'
 
 const tip = $("#wb-tip")
 const gutter = $(".gutter")
-const liveBtn = $(".live-btn")
 const readoutT = $(".readout .t")
 // Minutes and seconds, then the hundredths dimmer.
 readoutT.innerHTML = '<span class="ms"></span><span class="cs"></span>'
@@ -100,7 +99,7 @@ function setView(from, to, { animate = true } = {}) {
   const r = pinStart({ from: mid - span / 2, to: mid + span / 2 }, D.last)
   D.view.fit = false
   D.view.followSpan = r.to - r.from
-  if (D.last && D.last.playing) D.view.detached = true
+  if (D.last && D.last.playing) (D.view.detached = true), (D.view.detachedAt = performance.now())
   if (animate) D.view.target = r
   else {
     D.view.from = r.from
@@ -117,6 +116,8 @@ function fitRange(a, b) {
   const pad = Math.max((b - a) * 0.15, 10)
   setView(a - pad, b + pad)
 }
+// How long a manual scroll of a live timeline holds the view before it follows again.
+const FOLLOW_AGAIN_MS = 3000
 function followLive() {
   D.view.detached = false
   D.view.fit = false
@@ -131,6 +132,8 @@ function stepView(s) {
   const v = D.view
   // Started playing: follow again. Paused: stay exactly where it is.
   if (s.playing && !v.wasPlaying) v.detached = false
+  // Scrolled away while it records: it follows again once you leave it alone.
+  if (s.playing && !s.future && v.detached && now - (v.detachedAt || 0) > FOLLOW_AGAIN_MS) v.detached = false
   if (!s.playing && v.wasPlaying) {
     v.fit = false
     v.target = null
@@ -195,7 +198,9 @@ function treeOrder() {
 }
 
 function layoutLanes(g) {
-  const avail = g.h - RULER - 4
+  // The focused element's row (32-anims.js) takes its height first.
+  const fh = focusHeight(g)
+  const avail = g.h - RULER - 4 - fh
   const order = treeOrder()
   const n = order.length
   const compact = n * LANE > avail
@@ -209,6 +214,7 @@ function layoutLanes(g) {
     y += pitch
   })
   D.rowOrder = order.map((b) => b.id)
+  D.focusRow = fh ? { y0: Math.min(Math.round(y) + 2, g.h - fh), h: fh } : null
   return lanes
 }
 
@@ -310,11 +316,13 @@ function drawRuler(g, s, xNow) {
     const isMajor = rel % major === 0
     ctx.fillStyle = isMajor ? INK.dim : INK.faint
     ctx.fillRect(x - 0.5, RULER - (isMajor ? 6 : 3), 1, isMajor ? 5 : 2)
-    // A label the playhead's cap would sit on is left out.
-    if (isMajor && !(x + 3 < xNow + 8 && x + 36 > xNow - 8)) {
+    // A label that would run past the right edge is left out.
+    if (isMajor) {
+      const text = label(t)
+      if (x + 3 + ctx.measureText(text).width > g.w) continue
       ctx.fillStyle = INK.dim
-      ctx.fillText(label(t), x + 3, RULER - 8)
-      labels.push(label(t))
+      ctx.fillText(text, x + 3, RULER - 8)
+      labels.push(text)
     }
   }
   return labels
@@ -457,7 +465,6 @@ function renderTimeline(s, shownT) {
   D.lanes = lanes
   renderGutter(lanes)
   const following = s.playing && !D.view.detached
-  liveBtn.hidden = !(s.playing && !s.future && D.view.detached)
   checkPendingFork(s)
 
   if (band.id !== D.activeId) {
@@ -475,6 +482,7 @@ function renderTimeline(s, shownT) {
     D.branches.map((b) => `${b.id}.${b.end.toFixed(0)}.${b.forkAt}`).join(","),
     tl.markers.length, act ? act.values.length : -1, D.notes.map((n) => `${n.id}.${n.status}.${n.branchId}`).join(","),
     D.markers.length, lensClips ? D.lens.key : "", D.branchT, D.snapT, D.dragT, growing || bandFading ? performance.now() : 0, D.hoverRow,
+    focusKey(), D.range ? `${D.range.from}-${D.range.to}` : "",
   ].join("|")
   if (key === sceneKey) return
   sceneKey = key
@@ -528,6 +536,9 @@ function renderTimeline(s, shownT) {
   scene.lanes.push({ id: active.id, y: p.y, x0: p.x0, x1: p.x1, color, active: true, empty: p.empty })
   scene.actions = drawActions(g, tl.markers, A.y, lo, activeEnd, dim)
   if (lensClips) scene.capsules = drawLens(g, lensClips, A.y)
+  // The focused element's own row, and a range of recording time (Shift+drag).
+  if (D.focus) scene.focus = drawFocusRow(g, s)
+  if (D.range) scene.range = drawRecordingRange(g)
 
   // Bookmarks, on the ruler.
   ctx.fillStyle = "#f2f2f5"
@@ -598,6 +609,12 @@ function renderTimeline(s, shownT) {
       scene.notes.push({ id: n.id, x, y: L.y, r: 5 })
       return
     }
+    // A range note: a thin bracket from its start to its end.
+    if (n.range && n.range.to > n.range.from) {
+      const x1 = xOf(n.range.to, g)
+      ctx.fillRect(x, L.y - 12, Math.max(1, x1 - x), 1)
+      ctx.fillRect(x1 - 0.5, L.y - 14, 1, 5)
+    }
     const label = String(i + 1)
     const w = 8 + label.length * 5
     roundRect(x - w / 2, L.y - 17, w, 12, 6)
@@ -623,6 +640,8 @@ function hitAt(clientX, clientY) {
   const sc = D.scene
   if (!sc) return null
   for (const n of sc.notes) if (Math.abs(x - n.x) <= n.r && Math.abs(y - n.y) <= n.r) return { kind: "note", id: n.id }
+  const fh = focusHit(x, y)
+  if (fh) return fh
   for (const c of sc.capsules) if (x >= c.x0 - 2 && x <= c.x1 + 2 && Math.abs(y - c.y) <= 8) return { kind: "capsule", clip: c.clip }
   if (y < RULER) for (const b of sc.bookmarks) if (Math.abs(x - b.x) <= 5) return { kind: "bookmark", id: b.id }
   let best = null
@@ -638,7 +657,8 @@ let gutterKey = ""
 const invalidateGutter = () => (gutterKey = "")
 function renderGutter(lanes) {
   if (gutter.querySelector("input")) return // renaming
-  const key = D.compact + ":" + D.rowPitch + D.branches.map((b) => `${b.id}:${b.name}:${lanes.get(b.id).y}:${b.id === D.activeId}`).join("|")
+  const fr = D.focus && D.focusRow ? `${D.focus.label}@${D.focusRow.y0}:${D.focusRow.h}` : ""
+  const key = D.compact + ":" + D.rowPitch + D.branches.map((b) => `${b.id}:${b.name}:${lanes.get(b.id).y}:${b.id === D.activeId}`).join("|") + fr
   if (key === gutterKey) return
   gutterKey = key
   // Short dock: just the colour dots (the name shows on hover).
@@ -651,7 +671,7 @@ function renderGutter(lanes) {
       const title = D.compact ? ` title="${esc(b.name)}"` : ""
       return `<div class="${cls}" data-lane="${b.id}" style="top:${L.y}px;height:${D.rowPitch}px;margin-top:${-D.rowPitch / 2}px;--c:${colorOf(b)}"${title}><i></i><span>${esc(b.name)}</span></div>`
     })
-    .join("")
+    .join("") + (fr ? `<div class="focus-name" style="top:${D.focusRow.y0}px;height:${Math.min(D.focusRow.h, 26)}px" title="${esc(D.focus.label)}">${esc(D.focus.label)}</div>` : "")
 }
 
 // ---- the header ---------------------------------------------------------------------
@@ -696,17 +716,28 @@ function renderHead(s, shownT) {
   const playing = (!!s.playing || !!(D.building && D.building.play)) && D.dragT == null
   playBtn.classList.toggle("playing", playing)
   playBtn.setAttribute("aria-label", playing ? "Pause" : "Play")
-  // The hint area is only for a short warning (see flash()).
+  // The hint area is only for a short warning (see flash()), or, while a
+  // clip of the focused element is open, where the playhead is on its clock.
   if (performance.now() < flashUntil) return
+  const ro = focusReadout(s, shownT)
+  if (ro) {
+    if (hintEl.textContent !== ro) hintEl.textContent = ro
+    hintEl.classList.add("show", "readout")
+    hintEl.classList.remove("warn")
+    return
+  }
   if (hintEl.textContent) hintEl.textContent = ""
-  hintEl.classList.remove("show", "warn")
+  hintEl.classList.remove("show", "warn", "readout")
 }
 
-// A short message in the hint's place (a refused checkout, say).
-function flash(msg) {
-  flashUntil = performance.now() + 3500
+// A short message in the hint's place: a warning (a refused checkout, say),
+// or with `warn: false` news ("Timeline 2 started").
+function flash(msg, { warn = true } = {}) {
+  flashUntil = performance.now() + (warn ? 3500 : 2500)
+  hintEl.classList.remove("readout")
   hintEl.textContent = msg
-  hintEl.classList.add("show", "warn")
+  hintEl.classList.add("show")
+  hintEl.classList.toggle("warn", warn)
 }
 
 // ---- a new timeline from a chosen moment -------------------------------------------

package/src/shell/25-input.js

@@ -289,6 +289,12 @@ track.addEventListener("pointerdown", (e) => {
   }
   const hit = hitAt(e.clientX, e.clientY)
   if (hit && hit.kind === "note") return goToNoteId(hit.id)
+  // The focused element's row (32-anims.js): open a clip, pin a point, drag a range.
+  if (hit && (hit.kind.startsWith("focus") || hit.kind === "range-edge") && focusPointerDown(e, hit)) return
+  // A press on the track while writing a note moves the note's moment with it.
+  if (D.focus) (D.focusHold = true), (D.focus.touched = true)
+  // Shift+drag: a range of recording time, for the next element picked.
+  if (e.shiftKey) return rangePointerDown(e, s)
   if (hit && hit.kind === "capsule") {
     // ⌘ held on one of the element's animations: fit it, go to its start.
     const c = hit.clip
@@ -334,6 +340,13 @@ track.addEventListener("pointermove", (e) => {
   if (!s || !s.started) return
   const g = geom()
   overTrack = e
+  if (D.focusDrag && focusPointerMove(e)) return
+  if (D.rangeDrag && rangePointerMove(e)) return
+  if (D.focus) {
+    const fh = focusHit(e.clientX - g.left, e.clientY - g.top)
+    D.focus.hoverT = fh && fh.kind === "focus-row" && D.dragT == null ? fh.t : null
+    D.focus.hoverClip = fh && fh.kind === "focus-clip" ? fh.clip : null
+  }
   if (D.dragT != null) {
     if (!D.dragMoved && Math.abs(e.clientX - D.dragX0) < DEAD_PX) return
     D.dragMoved = true
@@ -352,9 +365,11 @@ track.addEventListener("pointermove", (e) => {
   if (e.ctrlKey) return
   hover(e, s, g)
 })
-track.addEventListener("pointerup", endScrub)
-track.addEventListener("pointercancel", endScrub)
+const endPress = () => focusPointerUp() || rangePointerUp() || endScrub()
+track.addEventListener("pointerup", endPress)
+track.addEventListener("pointercancel", endPress)
 track.addEventListener("pointerleave", () => {
+  if (D.focus) D.focus.hoverT = D.focus.hoverClip = null
   overTrack = null
   setBranchGuide(false)
   D.hoverRow = null
@@ -512,14 +527,26 @@ function dockKey(e, fromApp) {
   if (e.metaKey || e.ctrlKey || (!fromApp && typing(e.target))) return false
   const s = D.last
   if (!s || !s.started) return false
+  // Esc in a view-only app: an open clip closes, then a selected range goes, then the note.
+  if (e.key === "Escape" && (closeFocusClip() || clearRange())) return true
+  if (e.key === "Escape" && fromApp && !card.hidden) {
+    closeCard()
+    return true
+  }
   if (e.code === "Space" || (e.altKey && e.code === "KeyP")) {
     togglePlay()
     return true
   }
   if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
+    // An open clip of the focused element: its own frames and keyframes.
+    if (focusStep(e.key === "ArrowRight" ? 1 : -1, e.shiftKey)) return true
     stepBy(e.key === "ArrowRight" ? 1 : -1, e.shiftKey)
     return true
   }
+  if (e.altKey && e.code === "KeyT") {
+    setCollapsed(!D.collapsed)
+    return true
+  }
   if (e.altKey) return false
   if (e.code === "KeyF") {
     fitAll()