k0-board 0.1.0

package/web/refs.js

@@ -0,0 +1,176 @@
+// ── The references inside a document ──────────────────────────────────────────
+// Documents point at each other constantly — a table listing eight files, "the answers end up
+// in observations/", "it produces out/report.pdf and out/report.html" — and until now that was
+// all dead text: to open any of it you had to go back to the listing and hunt by hand.
+//
+// This decides, given the document you are reading and a piece of text, whether that piece is
+// a reference to something real. There is one rule: **it has to exist**. There is no list of
+// words to avoid, and none is needed: in a README full of `TRUE`, `spacing`, `active: false`
+// and `bold`, existence throws all of them out by itself.
+//
+// The hard part is not finding the names, it is choosing **which** file. In a repository with
+// nine `README.md` files, the right one is the one in the directory you are reading in — and
+// failing that, the one in the directory above. Somebody writing `README.md` inside
+// `interviews/` means the one in `interviews/`, not one picked at random.
+
+/** The extensions the viewer can show. Same list as `DOC_EXT` on the server. */
+const DOC = new Set([
+  '.md', '.markdown', '.mdx', '.html', '.htm', '.txt', '.rtf',
+  '.pdf', '.docx', '.doc', '.odt', '.pages',
+])
+
+/**
+ * A piece of text that might be a name or a path. It is a string rather than a ready-made
+ * regular expression because the code that walks the real document needs it too, and a global
+ * regex carries around the position it last reached.
+ */
+export const TOKEN_SRC = '[A-Za-z0-9.][A-Za-z0-9._/~-]*'
+const tokenRe = () => new RegExp(TOKEN_SRC, 'g')
+
+/** Punctuation stuck on the end is not part of the name: "…it is in from-the-call.md." */
+export const trim = (t) => t.replace(/[.\-~]+$/, '')
+
+const nameOf = (p) => p.slice(p.lastIndexOf('/') + 1)
+const dirOf = (p) => p.slice(0, Math.max(0, p.lastIndexOf('/')))
+const extOf = (p) => {
+  const n = nameOf(p)
+  const i = n.lastIndexOf('.')
+  return i > 0 ? n.slice(i).toLowerCase() : ''
+}
+
+/**
+ * The path a reference written inside a document points at: `../x/y.md` read from `a/b/c.md`
+ * makes `a/x/y.md`. It lives here and not in the viewer because it is the same operation
+ * markdown links and names found in the text both need.
+ */
+export function resolveRel(from, target) {
+  const clean = target.split('#')[0].split('?')[0]
+  if (!clean) return null
+  const parts = (clean.startsWith('/') ? [] : dirOf(from).split('/')).concat(clean.split('/'))
+  const out = []
+  for (const p of parts) {
+    if (!p || p === '.') continue
+    if (p === '..') out.pop()
+    else out.push(p)
+  }
+  return out.join('/')
+}
+
+/**
+ * A path that goes through a hidden directory. They stay out: `.claude/` and friends are
+ * configuration, not things to read, and the listing has never shown them.
+ */
+const hidden = (p) => p.split('/').some((s) => s.startsWith('.') && s !== '.' && s !== '..')
+
+/**
+ * The indexes the search runs on. `dirs` holds every directory with at least one file in the
+ * listing: a directory the viewer cannot list is not a place to send you.
+ */
+export function index(files) {
+  const byPath = new Map()
+  const byName = new Map()
+  // Lower case → as it is written on disk. The comparison has to ignore case — somebody
+  // writing "Onboarding" in a sentence means the `onboarding` directory — but what comes back
+  // has to be the real path, otherwise the directory opens empty.
+  const dirs = new Map()
+  for (const f of files || []) {
+    const p = f.p
+    byPath.set(p.toLowerCase(), p)
+    const n = nameOf(p).toLowerCase()
+    const a = byName.get(n)
+    if (a) a.push(p)
+    else byName.set(n, [p])
+    const parts = p.split('/')
+    parts.pop()
+    for (let i = 1; i <= parts.length; i++) {
+      const d = parts.slice(0, i).join('/')
+      if (!dirs.has(d.toLowerCase())) dirs.set(d.toLowerCase(), d)
+    }
+  }
+  return { byPath, byName, dirs }
+}
+
+/**
+ * Is this piece of text worth trying to resolve?
+ *
+ * In plain prose the signal is the extension or the slash: "README" written in a sentence is a
+ * word, `README.md` is a file. Inside backticks the rule is looser — somebody who reached for
+ * backticks was already pointing at something — and a single word gets through too, which may
+ * turn out to be a directory.
+ */
+export function worth(t, fromCode = false) {
+  if (!t || /\s/.test(t)) return false
+  const ext = extOf(t)
+  if (ext) return DOC.has(ext) // `.mjs`, `.js`: code, not something the viewer shows
+  return fromCode || t.includes('/')
+}
+
+/** Every piece of text in a document that would be worth trying to resolve. */
+export function candidates(text) {
+  // Fenced blocks never become links — the renderer does not touch them — so there is no
+  // point even asking what is inside them.
+  const clean = String(text ?? '').replace(/^\s*(```+|~~~+)[\s\S]*?^\s*\1\s*$/gm, '')
+  const out = new Set()
+  for (const m of clean.matchAll(tokenRe())) {
+    const t = trim(m[0])
+    if (worth(t, true)) out.add(t)
+  }
+  return [...out]
+}
+
+/**
+ * What `t` points at, read from inside `doc`. Returns:
+ *
+ * - `{ path }` — a file the viewer already has in its listing;
+ * - `{ dir }` — a directory the viewer can list;
+ * - `{ ask }` — not in the listing, but it might exist anyway: these are the paths to have the
+ *   server check. It is the case of the PDFs inside `out/`, which the listing skips but which a
+ *   document names on purpose;
+ * - `null` — it is not a reference, or it is ambiguous and there is no way to choose.
+ */
+export function resolve(t, doc, ix, fromCode = false) {
+  if (!worth(t, fromCode)) return null
+
+  const folder = !extOf(t)
+  const rooted = t.includes('/') || t.startsWith('.')
+
+  // With the path written out there is nothing to guess: it is read relative to the document.
+  // Without one, we climb — the directory you are reading in, then the one above, to the top.
+  const tries = []
+  if (rooted) {
+    const abs = resolveRel(doc, t)
+    if (abs) tries.push(abs)
+    // And then from the repository root: `interviews/` written inside `interviews/README.md`
+    // means that directory, not `interviews/interviews`. Somebody writing a path with slashes
+    // in it usually writes the whole thing, not one relative to where they are.
+    const bare = t.replace(/^(\.\.?\/)+/, '').replace(/\/$/, '')
+    if (bare && !tries.includes(bare)) tries.push(bare)
+  } else {
+    for (let d = dirOf(doc); ; d = dirOf(d)) {
+      tries.push(d ? `${d}/${t}` : t)
+      if (!d) break
+    }
+  }
+
+  for (const p of tries) {
+    if (hidden(p)) continue
+    const real = ix.byPath.get(p.toLowerCase())
+    if (real) return { path: real }
+    const dir = folder && ix.dirs.get(p.toLowerCase().replace(/\/$/, ''))
+    if (dir) return { dir }
+  }
+
+  // Not in the listing. If the bare name exists in exactly one place, that is the one; if
+  // there are several and climbing found nothing either, no link is better than sending you to
+  // the wrong README.
+  if (!rooted && !folder) {
+    const same = (ix.byName.get(t.toLowerCase()) || []).filter((p) => !hidden(p))
+    if (same.length === 1) return { path: same[0] }
+    if (same.length > 1) return null
+  }
+
+  // That leaves the server's road: a directory the listing skips is not a file that does not
+  // exist. The PDFs inside `out/` are there, and a document that names them knows it.
+  const ask = tries.filter((p) => !hidden(p) && DOC.has(extOf(p)))
+  return ask.length ? { ask } : null
+}

package/web/title.js

@@ -0,0 +1,26 @@
+/**
+ * The title rule, one for everybody: the browser uses it as you type and the server uses it
+ * when it names the session. What you see in the field is exactly the name the session gets.
+ *
+ * Every word takes a capital on its first letter and keeps the rest EXACTLY as you wrote it —
+ * so "Fix API" stays "Fix-API", while "fix api" becomes "Fix-Api". Spaces become dashes.
+ *
+ *   claude code      -> Claude-Code
+ *   Fix-API          -> Fix-API
+ *   fix api          -> Fix-Api
+ *   this and that    -> This-And-That
+ *   Export CSV       -> Export-CSV
+ */
+export const MAX = 60
+
+export function titleCase(raw) {
+  return (raw || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // accents go: this name ends up in a terminal
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+/, '') // a trailing dash stays: it is what lets you type the word after a space
+    .split('-')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join('-')
+    .slice(0, MAX)
+}

package/web/units.js

@@ -0,0 +1,33 @@
+// ── Numbers as people read them ───────────────────────────────────────────────
+// The measurements are written in one place, like the title rule in title.js: both pages use
+// them, and one of them does so at a point where the shape of the number decides when to
+// redraw.
+
+const MB = 1048576
+const GB = 1073741824
+
+/**
+ * What a session weighs, rounded in steps: tens of MB below a gigabyte, tenths of a GB above.
+ *
+ * The rounding is not decoration. It is the rounded number — the one you read on the card —
+ * that goes into the signature of the refresh round: that way the board only redraws when the
+ * figure on screen really changes, instead of on every sample, throwing away the pointer and
+ * the buttons that appear under it.
+ */
+export function weight(bytes) {
+  const mb = bytes / MB
+  if (mb >= 1000) return `${(Math.round(mb / 100) / 10).toFixed(1)} GB`
+  const step = Math.round(mb / 10) * 10
+  return `${step || Math.round(mb)} MB`
+}
+
+/** A file's exact size: there is nothing to round in steps here. */
+export function bytes(n) {
+  if (n < 1024) return `${n} B`
+  if (n < MB) return `${Math.round(n / 1024)} KB`
+  if (n < GB) return `${(n / MB).toFixed(1)} MB`
+  return `${(n / GB).toFixed(1)} GB`
+}
+
+/** Round gigabytes, for the machine's own numbers. */
+export const gb = (n) => `${(n / GB).toFixed(1)} GB`

package/web/view.js

@@ -0,0 +1,248 @@
+// ── The view ──────────────────────────────────────────────────────────
+// The board does not scroll: it moves. `#board` is the whole content, pushed underneath the
+// fixed window of `#viewport` by a single transform. No bars and nothing to drag: you bring the
+// pointer near an edge and the board slides that way — the closer you are, the faster it goes —
+// and it stops dead as soon as there is nothing left on that side.
+//
+
+const $ = (s) => document.querySelector(s)
+
+const EDGE = 96 // the sensitive band along each edge, in px
+const SPEED = 1200 // px per second right at the edge; inside the band it accelerates
+const STEPS = [0.3, 0.4, 0.5, 0.65, 0.8, 1, 1.25, 1.5, 2]
+
+let vp, board, edges, level
+
+// x and y are how far the board has already slid away, in screen px.
+let view = { x: 0, y: 0, z: 1 }
+
+// Measurements kept aside: reading them on every frame would cost a layout recalculation exactly
+// while we are writing the transform. They are retaken only when the content or the window really
+// change, which is to say in refit().
+let box = { left: 0, top: 0, right: 0, bottom: 0, w: 0, h: 0 }
+let contentW = 0
+let contentH = 0
+
+let px = 0
+let py = 0
+let inside = false // the pointer is inside the view (and not over the zoom controls)
+let held = false // a button is down: the board stands still, the click has to land
+let frame = 0 // the requestAnimationFrame handle, 0 = stopped
+let last = 0
+
+// ── Limits and drawing ────────────────────────────────────────────────
+const maxX = () => contentW * view.z - box.w
+const maxY = () => contentH * view.z - box.h
+
+/**
+ * Keeps the view inside the board, and decides what to do with the space left over when the
+ * board is smaller than the window.
+ *
+ * The two axes are not treated the same, and that is the point. Sideways, a board narrower than
+ * the window is centred: with nothing anchoring the columns left or right, centred reads as
+ * deliberate. Downwards it is pinned to the top instead, because the columns hang from the top —
+ * they are different heights and they all start at the same line. Centring that vertically
+ * splits the leftover space above and below, and the gap above pushes every column away from the
+ * bar: it looks like a margin somebody forgot to remove, on exactly the screens where the board
+ * happens to fit.
+ */
+function clamp() {
+  const mx = maxX()
+  const my = maxY()
+  view.x = mx > 0 ? Math.min(Math.max(view.x, 0), mx) : mx / 2
+  view.y = my > 0 ? Math.min(Math.max(view.y, 0), my) : 0
+}
+
+function apply() {
+  board.style.transform = `translate(${-view.x}px, ${-view.y}px) scale(${view.z})`
+  const mx = maxX()
+  const my = maxY()
+  edges.classList.toggle('can-l', view.x > 1)
+  edges.classList.toggle('can-r', view.x < mx - 1)
+  edges.classList.toggle('can-t', view.y > 1)
+  edges.classList.toggle('can-b', view.y < my - 1)
+  level.textContent = `${Math.round(view.z * 100)}%`
+  save()
+}
+
+function measure() {
+  const r = vp.getBoundingClientRect()
+  box = { left: r.left, top: r.top, right: r.right, bottom: r.bottom, w: r.width, h: r.height }
+  // offsetWidth/offsetHeight are the layout measurements: the transform does not touch them.
+  contentW = board.offsetWidth
+  contentH = board.offsetHeight
+}
+
+// Writing on every frame would be sixty writes a second for nothing: where you are is noted
+// when you stop.
+let saveTimer
+function save() {
+  clearTimeout(saveTimer)
+  saveTimer = setTimeout(() => localStorage.setItem('k0-view', JSON.stringify(view)), 400)
+}
+
+function load() {
+  try {
+    const v = JSON.parse(localStorage.getItem('k0-view') || '{}')
+    for (const k of ['x', 'y', 'z']) if (Number.isFinite(v[k])) view[k] = v[k]
+    view.z = Math.min(STEPS[STEPS.length - 1], Math.max(STEPS[0], view.z))
+  } catch {
+    /* an old view that cannot be read: start again from the top left corner */
+  }
+}
+
+// ── Edge scrolling ────────────────────────────────────────────────────
+/**
+ * How much and which way to move, right now. The ramp is quadratic: entering the band it starts
+ * slowly, right at the edge it goes at full speed. Diagonals and corners come out by themselves,
+ * because there neither component is zero.
+ */
+function velocity() {
+  if (held || !inside || document.querySelector('dialog[open]')) return [0, 0]
+  const ramp = (d) => {
+    const t = 1 - d / EDGE
+    return t > 0 ? t * t : 0
+  }
+  return [
+    (ramp(box.right - px) - ramp(px - box.left)) * SPEED,
+    (ramp(box.bottom - py) - ramp(py - box.top)) * SPEED,
+  ]
+}
+
+function step(t) {
+  const [vx, vy] = velocity()
+  if (!vx && !vy) return (frame = 0)
+  if (!last) {
+    // First frame: how much time has passed is not known yet, so it only looks.
+    last = t
+    frame = requestAnimationFrame(step)
+    return
+  }
+  const dt = Math.min((t - last) / 1000, 0.05) // a frozen frame must not become a jump
+  last = t
+  if (dt > 0) {
+    const x0 = view.x
+    const y0 = view.y
+    view.x += vx * dt
+    view.y += vy * dt
+    clamp()
+    if (view.x === x0 && view.y === y0) return (frame = 0) // a wall: this side is finished
+    apply()
+  }
+  frame = requestAnimationFrame(step)
+}
+
+/** The loop only runs while it is needed: with the board still, nothing is in motion. */
+function wake() {
+  if (frame) return
+  last = 0
+  frame = requestAnimationFrame(step)
+}
+
+// ── Zoom ──────────────────────────────────────────────────────────────
+/** Changes scale while holding still the point of the board under (sx, sy). */
+function zoomTo(z, sx, sy) {
+  z = Math.min(STEPS[STEPS.length - 1], Math.max(STEPS[0], z))
+  const cx = (view.x + sx) / view.z
+  const cy = (view.y + sy) / view.z
+  view.z = z
+  view.x = cx * z - sx
+  view.y = cy * z - sy
+  clamp()
+  apply()
+}
+
+/** With + and − it jumps one step, holding the centre of the view still. */
+function nudge(dir) {
+  const i = STEPS.findIndex((s) => Math.abs(s - view.z) < 1e-6)
+  const next =
+    i >= 0
+      ? STEPS[Math.min(STEPS.length - 1, Math.max(0, i + dir))]
+      : dir > 0
+        ? (STEPS.find((s) => s > view.z) ?? STEPS[STEPS.length - 1])
+        : ([...STEPS].reverse().find((s) => s < view.z) ?? STEPS[0])
+  zoomTo(next, box.w / 2, box.h / 2)
+}
+
+/** Shrinks just enough to fit the whole board in. */
+function fit() {
+  if (!contentW || !contentH) return
+  zoomTo(Math.min(1, box.w / contentW, box.h / contentH), box.w / 2, box.h / 2)
+}
+
+// ── Wiring ────────────────────────────────────────────────────────────
+/** The content changed: remeasure, come back inside the limits, and redraw. */
+export function refit() {
+  if (!vp) return
+  measure()
+  clamp()
+  apply()
+  wake() // the board has grown: there may now be somewhere to go on this side
+}
+
+export function initView() {
+  vp = $('#viewport')
+  board = $('#board')
+  edges = $('#edges')
+  level = $('#z-level')
+
+  load()
+  measure()
+  clamp()
+  apply()
+
+  document.addEventListener('pointermove', (e) => {
+    px = e.clientX
+    py = e.clientY
+    inside =
+      px >= box.left &&
+      px <= box.right &&
+      py >= box.top &&
+      py <= box.bottom &&
+      !(e.target instanceof Element && e.target.closest('#zoom'))
+    wake()
+  })
+  // Outside the page, or with a button held, the board stands still: that way a click near the
+  // edge lands instead of chasing a card that is running away. A pointer that has left the window
+  // stops reporting, and without this the last report would stand — "I am at the edge" — and the
+  // board would scroll forever on its own.
+  document.documentElement.addEventListener('pointerleave', () => (inside = false))
+  document.addEventListener('pointerdown', () => (held = true))
+  document.addEventListener('pointerup', () => {
+    held = false
+    wake()
+  })
+  document.addEventListener('pointercancel', () => (held = false))
+  addEventListener('blur', () => {
+    inside = false
+    held = false
+  })
+
+  // Two fingers on the trackpad move the view; a pinch (which arrives as a wheel event with ctrl
+  // held) zooms under the pointer.
+  vp.addEventListener(
+    'wheel',
+    (e) => {
+      e.preventDefault()
+      const k = e.deltaMode === 1 ? 16 : 1 // some mice count lines, not pixels
+      if (e.ctrlKey) {
+        zoomTo(view.z * Math.exp((-e.deltaY * k) / 240), e.clientX - box.left, e.clientY - box.top)
+      } else {
+        view.x += e.deltaX * k
+        view.y += e.deltaY * k
+        clamp()
+        apply()
+      }
+    },
+    { passive: false }
+  )
+
+  $('#z-out').onclick = () => nudge(-1)
+  $('#z-in').onclick = () => nudge(1)
+  $('#z-level').onclick = () => zoomTo(1, box.w / 2, box.h / 2)
+  $('#z-fit').onclick = () => fit()
+
+  addEventListener('resize', refit)
+  // Caveat is a web font: once it has loaded, the columns change size.
+  document.fonts?.ready.then(refit)
+}