samagotchi 0.170.0 → 0.171.0

data/lib/samagotchi/web/public/ws_reader.js

@@ -0,0 +1,319 @@
+// The working set's reader (scene A of the working-set preview): what chi
+// has of one item, as its timeline, newest first (ws_timeline.js cards,
+// ws_cards.js templates): a file's reads as merged line slices over a strip
+// of the whole file, its edits as diffs, a memory's reads with their
+// overlay and, for a changed one, "Now · diff"; a slice chi no longer has
+// greyed. It replaces the stage (#center: the history and the composer,
+// kept under it, inert, so their scroll place stays) until "← Stage" or
+// Esc; the session's set stays beside it with the open item marked, ↑↓
+// step through it. On a phone it is full screen: ‹ Set back to the list's
+// sheet, ‹ › the other items.
+//
+// Ways in: the popover peek's "Open the timeline" (ws_peek.js), a tool
+// row's "timeline" (ws_way_in.js), the ref ▾ menu's "What chi has" on a
+// file in the set (refs.js REF_ACTIONS.file, its env's +whatChiHas+). All
+// the owner's: app.js makes this only for a viewer with working_set_items.
+//
+// The timeline comes from the item route (getWorkingSetItem); an answer for
+// an item no longer open, or another session, is dropped (latest.js). While
+// open, each new server snapshot asks again (the route builds from the
+// session's messages, which lag a running turn's events). Leaving the
+// session (another one, the start page) resets it: session_view.js
+// forgetSession calls reset(), so #center is never left inert under it.
+
+import { html, nothing, render } from "./vendor/lit-html.js";
+import { api } from "./data.js";
+import { createLatest } from "./latest.js";
+import { diffTemplate } from "./diff_view.js";
+import { createPeek } from "./ws_peek.js";
+import { setTimelineWayIn } from "./ws_way_in.js";
+import { cardTemplate } from "./ws_cards.js";
+import { bandBox, countsText, eventTag, fileStrip, itemPath, linesText, timelineCards } from "./ws_timeline.js";
+import { GLYPHS, leafText, opsText, steerId, steerLine, tokensText } from "./working_set.js";
+
+// The item route's answer for session +id+ (+now+: a memory's text now).
+export function getWorkingSetItem(id, kind, key, { now = false } = {}) {
+  return api(itemPath(id, kind, key, { now }));
+}
+
+const PHONE_MAX = 600;
+
+// The head's pill: what is true of the item as a whole.
+function itemPill(item, events) {
+  if (item.state === "stale") return { text: item.kind === "memory" ? "changed since chi read it" : "the file changed since chi saw it", warn: true };
+  if (item.state === "dropped") return { text: "dropped by you: chi no longer has it", warn: false };
+  if (item.state === "forgotten") return { text: "chi no longer has it", warn: false };
+  const edits = events.filter((e) => e.op === "edit" || e.op === "write").length;
+  return edits ? { text: `chi edited it ${edits}× · newest first`, warn: true } : null;
+}
+
+// What an item is called in the head: a file by its path in the session's
+// folder, a memory by its name.
+function itemName(item) {
+  if (item.kind === "file") return item.path || item.key;
+  if (item.kind === "url") return item.url || item.key;
+  return `${GLYPHS.memory} ${item.key}`;
+}
+
+// +centerEl+: what the reader covers (#center); +session()+, +state()+: the
+// open session's id and fields (its folder: the undrop line); +getItem+: the
+// item route (tests pass a stand-in); +sendLine(line)+: a steer line
+// (undrop; null: none).
+export function createWorkingSetPreview({ centerEl, session, state = () => ({}), getItem = getWorkingSetItem, sendLine = null,
+  doc = document, win = window }) {
+  let workingSet = null;
+  // The open item ({kind, key}), its answer, the memory's now, the tab.
+  let open = null;
+  let data = null;
+  let failed = false;
+  let tab = "has";
+  let openFor = null;
+  const latest = createLatest(() => `${session()}|${open ? `${open.kind}:${open.key}` : ""}`);
+  const peek = createPeek({ session, getItem: (id, kind, key) => getItem(id, kind, key), onChange: () => workingSet?.peekChanged() });
+
+  const el = doc.createElement("section");
+  el.className = "ws-reader";
+  el.id = "wsReader";
+  el.setAttribute("aria-label", "What chi has");
+  el.hidden = true;
+  centerEl?.appendChild(el);
+  const covered = () => [...(centerEl?.children || [])].filter((child) => child !== el);
+
+  const items = () => workingSet?.items() || [];
+  // The rows the set beside it draws (and ↑↓, ‹ › step over): not the muted.
+  const shown = () => items().filter((it) => !it.muted);
+  // Where focus was when it opened: it goes back there on close.
+  let returnTo = null;
+  const idOf = (it) => steerId(it);
+  // The open item as the set has it (its runs, state, tokens); a stand-in
+  // when the set doesn't hold it (yet).
+  const current = () => items().find((it) => it.kind === open?.kind && it.key === open?.key)
+    || (open ? { kind: open.kind, key: open.key, label: open.key, ops: [], state: "live", runs: [] } : null);
+
+  function load() {
+    const id = session();
+    if (!id || !open) return;
+    const fresh = latest.begin();
+    const { kind, key } = open;
+    Promise.resolve()
+      .then(() => getItem(id, kind, key, { now: kind === "memory" }))
+      .then((answer) => {
+        if (!fresh()) return;
+        data = answer;
+        failed = false;
+        draw();
+      })
+      .catch(() => {
+        if (!fresh()) return;
+        failed = true;
+        draw();
+      });
+  }
+
+  function stripTemplate(events) {
+    const strip = fileStrip(events);
+    if (!strip) return nothing;
+    const merged = strip.bands.filter((b) => !b.latest).sort((a, b) => a.first - b.first);
+    const ranges = merged.map((b) => `${b.first}–${b.last}`).join(", ");
+    const bands = strip.bands.map((band) => {
+      const box = bandBox(band, strip.length);
+      return html`<button type="button" class=${`wsr-band ${band.state}${band.latest ? " latest" : ""}`} data-wsr="band" data-first=${band.first} style=${`left:${box.left};width:${box.width}`} title=${`${linesText(band)}${band.state === "sent" ? "" : ` (${band.state})`}: go to its lines`}></button>`;
+    });
+    const chips = merged.map((band) => html`<button type="button" class=${`wsr-chip ${band.state}`} data-wsr="band" data-first=${band.first}>${band.first}–${band.last}</button>`);
+    return html`<div class="wsr-strip"><div class="wsr-strip-k"><span>1</span><span>read: ${ranges} of ${strip.length} lines known · tap a band to jump</span><span>${strip.length}</span></div><div class="wsr-bar" aria-label=${`read ${ranges} of ${strip.length} lines`}>${bands}</div><div class="wsr-chips">${chips}</div></div>`;
+  }
+
+  function memoryTemplate(item, events) {
+    const now = data?.now;
+    const changed = item.state === "stale" && now;
+    const lastRead = events.filter((e) => e.op === "memory_read").at(-1);
+    const memory = lastRead?.memory;
+    const banner = changed ? html`<div class="wsr-banner">Changed since chi's last read${lastRead ? ` (${eventTag(lastRead, item)})` : ""}: what chi has is not what the memory says now.</div>` : nothing;
+    const tabs = changed ? html`<div class="wsr-tabs" role="tablist"><button type="button" role="tab" aria-selected=${String(tab === "has")} class=${tab === "has" ? "on" : ""} data-wsr="tab" data-tab="has">What chi has</button><button type="button" role="tab" aria-selected=${String(tab === "now")} class=${tab === "now" ? "on" : ""} data-wsr="tab" data-tab="now">Now · diff</button></div>` : nothing;
+    const from = memory?.path ? html`<div class="wsr-from">${memory.scope} memory · from ${memory.path.replace(/[^/]*$/, "")}</div>` : nothing;
+    return { banner, tabs, from, nowBody: changed && tab === "now" ? (now.gone ? html`<div class="diff-note warn">the memory's file is gone</div>` : html`<article class="wsr-card now"><header class="wsr-card-h"><span class="wsr-card-t">what chi has → now</span></header>${diffTemplate(now.diff)}</article>`) : null };
+  }
+
+  function setTemplate(item) {
+    const rows = shown().map((it) => {
+      const on = it.kind === item.kind && it.key === item.key;
+      const state = it.state && it.state !== "live" ? ` ${it.state}` : "";
+      return html`<button type="button" class=${`ws-row wsr-item ${it.kind}${state}${on ? " on" : ""}`} data-wsr="item" data-ws-id=${idOf(it)} aria-current=${on ? "true" : "false"}><span class="k">${GLYPHS[it.kind] || ""}</span><span class="t">${leafText(it)}</span><span class="st">${opsText(it)}</span></button>`;
+    });
+    const files = items().filter((it) => it.kind === "file").length;
+    const memories = items().filter((it) => it.kind === "memory").length;
+    const pct = Number.isFinite(state().ctxPct) ? ` · ctx ${Math.round(state().ctxPct)} %` : "";
+    return html`<aside class="wsr-set" aria-label="Working set"><div class="wsr-set-h"><strong>working set</strong><span class="wsr-set-m">session</span></div><div class="wsr-set-n">${items().length} items${pct} · files · ${files} · memories · ${memories}</div><div class="wsr-set-rows">${rows}</div><div class="wsr-set-hint">↑↓ steps through the set · Esc back to the stage (same scroll place)</div></aside>`;
+  }
+
+  function draw() {
+    if (!open) return;
+    const item = current();
+    const events = data?.events || [];
+    const cards = timelineCards(events);
+    const tokens = tokensText(item.tokens);
+    const counts = countsText(events);
+    const pill = data ? itemPill(item, events) : null;
+    const memory = item.kind === "memory" ? memoryTemplate(item, events) : null;
+    const scope = item.kind === "memory" ? events.find((e) => e.memory)?.memory?.scope : null;
+    const meta = [scope ? `${scope} memory` : "", "timeline, newest first", counts, tokens ? `${tokens} tokens` : ""].filter(Boolean).join(" · ");
+    const phoneMeta = [scope ? `${scope} memory` : "", counts, tokens ? `${tokens} tokens` : ""].filter(Boolean).join(" · ");
+    const undrop = sendLine && (item.state === "dropped" || item.hasDrop) ? html`<button type="button" class="ws-act-b" data-wsr="undrop">undrop</button>` : nothing;
+    let body;
+    if (failed) body = html`<div class="wsr-note">Couldn't load what chi has of it.</div>`;
+    else if (!data) body = html`<div class="wsr-note">Loading…</div>`;
+    else if (!cards.length) body = html`<div class="wsr-note">Nothing of it in the conversation yet: a running turn's reads show at its next step.</div>`;
+    else if (memory?.nowBody) body = memory.nowBody;
+    else body = cards.map((card) => cardTemplate(card, { item, undrop }));
+    const list = shown();
+    const at = list.findIndex((it) => it.kind === item.kind && it.key === item.key);
+    const tpl = html`<div class="wsr-main">
+      <div class="wsr-head">
+        <button type="button" class="wsr-back" data-wsr="back"><span class="wsr-wide">← Stage</span><span class="wsr-narrow">‹ Set</span></button>
+        <span class="wsr-title"><span class="wsr-name" title=${item.key}>${itemName(item)}</span><span class="wsr-meta wsr-wide">${meta}</span><span class="wsr-meta wsr-narrow">${phoneMeta}</span></span>
+        ${pill ? html`<span class=${`wsr-head-pill${pill.warn ? " warn" : ""}`}>${pill.text}</span>` : nothing}
+        <span class="wsr-nav wsr-narrow"><button type="button" data-wsr="prev" aria-label="Previous item" ?disabled=${at <= 0}>‹</button><button type="button" data-wsr="next" aria-label="Next item" ?disabled=${at < 0 || at >= list.length - 1}>›</button></span>
+      </div>
+      ${memory ? memory.banner : nothing}${memory ? memory.tabs : nothing}
+      ${item.kind === "file" ? stripTemplate(events) : nothing}
+      <div class="wsr-body" tabindex="-1">${body}</div>
+      ${memory ? memory.from : nothing}
+      <div class="wsr-foot wsr-narrow">‹ › the next item · lines don't wrap, scroll sideways in the code</div>
+    </div>${setTemplate(item)}`;
+    render(tpl, el);
+  }
+
+  // Opens +target+ ({kind, key}): the stage stays under it, inert.
+  function openItem(target) {
+    if (!target?.kind || !target.key) return;
+    const again = open && open.kind === target.kind && open.key === target.key;
+    open = { kind: target.kind, key: target.key };
+    openFor = session();
+    if (!again) {
+      data = null;
+      failed = false;
+      tab = "has";
+    }
+    if (el.hidden) {
+      const active = doc.activeElement;
+      returnTo = active && active !== doc.body && !el.contains(active) ? active : null;
+      for (const child of covered()) child.inert = true;
+      el.hidden = false;
+      doc.body.classList.add("ws-reading");
+    }
+    draw();
+    el.querySelector(".wsr-body")?.scrollTo?.(0, 0);
+    el.querySelector(".wsr-back")?.focus({ preventScroll: true });
+    load();
+  }
+
+  // +refocus+: focus goes back where it was at the open (not for a jump,
+  // which scrolls to its row, nor a reset).
+  function close({ refocus = true } = {}) {
+    if (el.hidden) return;
+    open = null;
+    data = null;
+    latest.drop();
+    el.hidden = true;
+    for (const child of covered()) child.inert = false;
+    doc.body.classList.remove("ws-reading");
+    render(nothing, el);
+    const back = returnTo;
+    returnTo = null;
+    if (refocus && back?.isConnected && !back.closest?.("[inert]")) back.focus?.({ preventScroll: true });
+  }
+
+  // The item +step+ places from the open one in the set.
+  function stepItem(step) {
+    const list = shown();
+    const at = list.findIndex((it) => it.kind === open?.kind && it.key === open?.key);
+    const next = list[at + step];
+    if (next) openItem(next);
+  }
+
+  const phone = () => win.innerWidth < PHONE_MAX;
+
+  el.addEventListener("click", (e) => {
+    const act = e.target.closest("[data-wsr], [data-ws='jump']");
+    if (!act) return;
+    if (act.dataset.ws === "jump") {
+      const [turn, step, row] = String(act.dataset.at).split(".").map(Number);
+      close({ refocus: false });
+      workingSet?.jump({ turn, step, row });
+      return;
+    }
+    const what = act.dataset.wsr;
+    if (what === "back") {
+      close();
+      // After this click has passed the list's outside-click close.
+      if (phone()) setTimeout(() => workingSet?.openList(), 0);
+    } else if (what === "item") {
+      const found = items().find((it) => idOf(it) === act.dataset.wsId);
+      if (found) openItem(found);
+    } else if (what === "prev") stepItem(-1);
+    else if (what === "next") stepItem(1);
+    else if (what === "tab") {
+      tab = act.dataset.tab === "now" ? "now" : "has";
+      draw();
+    } else if (what === "band") {
+      const first = Number(act.dataset.first);
+      const card = [...el.querySelectorAll(".wsr-card.slice")].find((c) => c.querySelector(`.read-line[data-line="${first}"]`));
+      card?.scrollIntoView?.({ block: "start" });
+    } else if (what === "undrop" && sendLine) {
+      const item = current();
+      Promise.resolve(sendLine(steerLine("undrop", [item], state().dir))).catch(() => {});
+    }
+  });
+
+  doc.addEventListener("keydown", (e) => {
+    if (el.hidden || e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
+    if (e.target?.closest?.("input, textarea, [contenteditable]")) return;
+    // A popover over the reader takes its own Esc.
+    if (doc.querySelector(".ctx-popover:not([hidden])")) return;
+    if (e.key === "Escape") {
+      e.preventDefault();
+      close();
+    } else if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault();
+      stepItem(e.key === "ArrowDown" ? 1 : -1);
+    }
+  });
+
+  // A tool row's "timeline" (ws_way_in.js).
+  doc.addEventListener("click", (e) => {
+    const button = e.target.closest?.(".activity-ws[data-ws-kind]");
+    if (!button) return;
+    e.preventDefault();
+    openItem({ kind: button.dataset.wsKind, key: button.dataset.wsKey });
+  });
+
+  return {
+    peek,
+    // The working set's view (working_set_view.js), once made: the set,
+    // its jumps and its list; rows get their way in from now on.
+    attach(view) {
+      workingSet = view;
+      if (!view) return;
+      setTimelineWayIn(true);
+      // A new snapshot: asked again (a snapshot of another session: closed,
+      // though forgetSession's reset has done it already).
+      view.onServer(() => {
+        if (el.hidden) return;
+        if (session() !== openFor) close({ refocus: false });
+        else load();
+      });
+    },
+    open: openItem,
+    close,
+    isOpen: () => !el.hidden,
+    // The ref ▾ menu's "What chi has" (refs.js): a file ref whose path is
+    // an item of the set.
+    whatChiHas: {
+      has: (path) => items().some((it) => it.kind === "file" && it.key === path),
+      open: (path) => openItem({ kind: "file", key: path }),
+    },
+    // The session forgotten (another one, the start page: session_view.js
+    // forgetSession): closed, the stage no longer inert.
+    reset() { close({ refocus: false }); peek.close(); },
+  };
+}

data/lib/samagotchi/web/public/ws_timeline.js

@@ -0,0 +1,200 @@
+// What the model has of one working-set item, as the reader (ws_reader.js)
+// and the popover's peek (ws_peek.js) show it: the pure part. No DOM, so
+// `node --test` covers it. The server's timeline (GET …/working_set/item,
+// WorkingSet.timeline_of: docs/internals/working-set.md, Timeline) is every
+// run of the item in conversation order; here it becomes cards, newest
+// first:
+// - a slice: reads whose lines overlap or touch, merged (each line from the
+//   newest read holding it), its header listing the reads; reads merge only
+//   with reads in the same state (still sent, dropped, forgotten), so a
+//   slice the model no longer has is greyed whole, and only between the same
+//   edits or writes (an edit moves the lines after it);
+// - a partial read (a head/tail preview, a cut output), shown as it is;
+// - an edit or a write, its saved diff (diff_view.js);
+// - a memory read (its text, its overlay apart), a memory write, a fetch.
+// The file strip draws the merged ranges over the file's length (the
+// largest last line any read knows: a whole read's is the file's).
+//
+// An event's place on the page (its step tag, "go to the call") is the
+// item's row with its tool id (working_set.js runs); a legacy row has
+// none, so the server's global step names it.
+
+import { stepTag } from "./working_set.js";
+
+// A slice longer than this shows its first lines and a "show all" fold.
+export const SLICE_FOLD_LINES = 200;
+// The peek's lines of a read or a text.
+export const PEEK_LINES = 12;
+
+const STATES = ["sent", "dropped", "forgotten"];
+
+// An event's state: sent, dropped (the user's) or forgotten.
+export function eventState(event) {
+  if (event?.dropped) return "dropped";
+  if (event && event.sent === false) return "forgotten";
+  return "sent";
+}
+
+// The path of the item route for session +id+ (+now+: a memory's text now).
+export function itemPath(id, kind, key, { now = false } = {}) {
+  const query = new URLSearchParams({ kind, key });
+  if (now) query.set("now", "1");
+  return `/api/sessions/${encodeURIComponent(id)}/working_set/item?${query}`;
+}
+
+// A read's lines as numbered rows ([{n, text}]), its text split as the
+// file's (a last newline ends a line), at most up to its last line.
+export function readRows(event) {
+  const first = Number(event?.lines?.first) || 1;
+  const lines = String(event?.text ?? "").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const last = Number(event?.lines?.last);
+  const count = Number.isFinite(last) && last >= first ? Math.min(lines.length, last - first + 1) : lines.length;
+  return lines.slice(0, count).map((text, i) => ({ n: first + i, text }));
+}
+
+const mergeable = (event) => event.op === "read" && !event.lines?.partial && Number.isFinite(event.lines?.first) && Number.isFinite(event.lines?.last);
+
+// The reads of +events+ merged into slices: [{type: "slice", first, last,
+// state, reads, rows, newest}], +newest+ the place of its newest read.
+function slices(events) {
+  const out = [];
+  // An edit or a write starts a new version of the file: its lines move, so
+  // only reads between the same edits merge (line numbers are one file's).
+  let version = 0;
+  const versions = events.map((event) => {
+    if (event.op === "edit" || event.op === "write") version += 1;
+    return version;
+  });
+  for (let v = 0; v <= version; v += 1) for (const state of STATES) {
+    const reads = events.map((event, place) => ({ event, place }))
+      .filter(({ event, place }) => versions[place] === v && mergeable(event) && eventState(event) === state)
+      .sort((a, b) => a.event.lines.first - b.event.lines.first || a.place - b.place);
+    let open = null;
+    for (const read of reads) {
+      const { first, last } = read.event.lines;
+      if (open && first <= open.last + 1) {
+        open.last = Math.max(open.last, last);
+        open.reads.push(read);
+      } else {
+        open = { type: "slice", first, last, state, reads: [read] };
+        out.push(open);
+      }
+    }
+  }
+  return out.map((slice) => {
+    // Each line from the newest read that holds it.
+    const lines = new Map();
+    for (const { event } of [...slice.reads].sort((a, b) => a.place - b.place)) {
+      for (const row of readRows(event)) lines.set(row.n, row.text);
+    }
+    const rows = [...lines.keys()].sort((a, b) => a - b).map((n) => ({ n, text: lines.get(n) }));
+    const reads = slice.reads.sort((a, b) => b.place - a.place).map(({ event }) => event);
+    return { ...slice, reads, rows, newest: Math.max(...slice.reads.map((r) => r.place)) };
+  });
+}
+
+const TYPES = { edit: "edit", write: "edit", memory_read: "memory", memory_write: "written", fetch: "fetch" };
+
+// The timeline's cards, newest first: [{type, newest, ...}] — slices
+// (above), and {type: "partial" | "edit" | "memory" | "written" | "fetch",
+// event, state}. The newest card is +latest+.
+export function timelineCards(events = []) {
+  const list = Array.isArray(events) ? events : [];
+  const cards = slices(list);
+  list.forEach((event, place) => {
+    if (event.op === "read" && !mergeable(event)) cards.push({ type: "partial", event, state: eventState(event), newest: place });
+    else if (TYPES[event.op]) cards.push({ type: TYPES[event.op], event, state: eventState(event), newest: place });
+  });
+  cards.sort((a, b) => b.newest - a.newest);
+  if (cards.length) cards[0] = { ...cards[0], latest: true };
+  return cards;
+}
+
+// The file strip: the merged ranges over the file's length (+length+: the
+// largest last line known), the newest read's range +latest+.
+// @return {length, bands: [{first, last, state, latest?}]} or null without one
+export function fileStrip(events = []) {
+  const reads = (events || []).filter(mergeable);
+  if (!reads.length) return null;
+  const length = Math.max(...reads.map((e) => e.lines.last));
+  const bands = slices(events).map(({ first, last, state }) => ({ first, last, state }));
+  const newest = reads.at(-1);
+  bands.push({ first: newest.lines.first, last: newest.lines.last, state: eventState(newest), latest: true });
+  return { length, bands };
+}
+
+// A band's place on the strip as percentages ({left, width}).
+export function bandBox(band, length) {
+  const total = Math.max(1, Number(length) || 1);
+  const left = ((band.first - 1) / total) * 100;
+  const width = Math.max(0.5, ((band.last - band.first + 1) / total) * 100);
+  return { left: `${left.toFixed(2)}%`, width: `${Math.min(width, 100 - left).toFixed(2)}%` };
+}
+
+// "3 reads, 1 edit" (the peek's link and the reader's head).
+export function countsText(events = []) {
+  const reads = events.filter((e) => e.op === "read" || e.op === "memory_read" || e.op === "fetch").length;
+  const edits = events.filter((e) => e.op === "edit" || e.op === "write" || e.op === "memory_write").length;
+  const word = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+  return [reads ? word(reads, "read") : "", edits ? word(edits, "edit") : ""].filter(Boolean).join(", ");
+}
+
+// The place of +event+ on the page: its row's at, from the item's runs
+// (working_set.js), or null (a legacy row, a row not drawn).
+export function placeOf(event, item) {
+  const run = (item?.runs || []).find((r) => r.id === event?.tool_id);
+  return run ? run.at : null;
+}
+
+// An event's step tag: the row's "t3·s14", else the server's "step 14".
+export function eventTag(event, item) {
+  const at = placeOf(event, item);
+  if (at) return stepTag({ at }, { session: true });
+  return Number.isFinite(event?.step) ? `step ${event.step}` : "";
+}
+
+// A slice's or a card's steps for its header ("t3·s13, t3·s162").
+export function tagsText(events, item) {
+  return events.map((event) => eventTag(event, item)).filter(Boolean).join(", ");
+}
+
+// A read's lines in words: "lines 204–265", "line 3", "whole file".
+export function linesText(lines) {
+  if (!lines) return "";
+  if (lines.partial) return lines.whole ? "a preview of the file" : `from line ${lines.first}, cut`;
+  return lines.first === lines.last ? `line ${lines.first}` : `lines ${lines.first}–${lines.last}`;
+}
+
+const NO_LONGER = { dropped: "dropped by you", forgotten: "forgotten" };
+
+// Why chi no longer has a card's text, or "" while it does.
+export function goneText(state) {
+  return NO_LONGER[state] || "";
+}
+
+// What the peek shows of an item: the latest edit's diff when it has one,
+// else the newest read's (or text's) first lines; +after+ the newest event
+// after the one shown (a read after the edit).
+// @return {event, kind: "diff" | "lines" | "text", rows?, after} or null
+export function peekOf(events = []) {
+  const list = Array.isArray(events) ? events : [];
+  if (!list.length) return null;
+  const editAt = list.findLastIndex((e) => (e.op === "edit" || e.op === "write") && e.diff);
+  if (editAt >= 0) {
+    const after = list.slice(editAt + 1).at(-1) || null;
+    return { event: list[editAt], kind: "diff", after };
+  }
+  // An edit without a diff (a no-op) shows nothing: the newest other run.
+  const event = list.findLast((e) => e.op !== "edit" && e.op !== "write") || list.at(-1);
+  if (event.op === "read") return { event, kind: "lines", rows: readRows(event).slice(0, PEEK_LINES), after: null };
+  const rows = String(event.text ?? "").split("\n").slice(0, PEEK_LINES).map((text, i) => ({ n: i + 1, text }));
+  return { event, kind: "text", rows, after: null };
+}
+
+// What an event is, in a header's words ("edit", "read 236–250", "memory read").
+export function eventWords(event) {
+  if (!event) return "";
+  if (event.op === "read") return `read ${linesText(event.lines).replace(/^lines? /, "")}`.trim();
+  return { edit: "edit", write: "write", memory_read: "memory read", memory_write: "memory write", fetch: "fetch" }[event.op] || event.op;
+}

data/lib/samagotchi/web/public/ws_way_in.js

@@ -0,0 +1,25 @@
+// A tool row's way into the working set's reader (ws_reader.js): a small
+// "timeline" button on an ok read, edit, write, memory_read or memory_write
+// row (the item it touched: working_set.js rowEntries), which the reader's
+// delegated click opens. Off until the page turns it on (app.js, for an
+// owner with the working set): a participant's rows never get it (the
+// null-control idiom: not drawn, not wired). turn_html.js draws it.
+
+import { html, nothing } from "./vendor/lit-html.js";
+import { rowEntries } from "./working_set.js";
+
+const TOOLS = new Set(["read", "edit", "write", "memory_read", "memory_write"]);
+let on = false;
+
+// The page has a reader: rows drawn from now on carry the button.
+export function setTimelineWayIn(value) {
+  on = !!value;
+}
+
+// The button for +row+ (activity.js's row model), or nothing.
+export function wayInTemplate(row) {
+  if (!on || !TOOLS.has(row?.tool)) return nothing;
+  const entry = rowEntries(row)[0];
+  if (!entry) return nothing;
+  return html`<button type="button" class="activity-ws" data-ws-kind=${entry.kind} data-ws-key=${entry.key} title="What chi has of it: open its timeline">timeline</button>`;
+}

data/lib/samagotchi/web/session_control.rb

@@ -272,45 +272,64 @@ module Samagotchi
       # POST /api/sessions/:id/images: the raw image as the body (a paste or
       # a drop), ?name= for its file name. Stored like any other image
       # (converted, downscaled); answers the ref the turn then names.
+      # A participant's upload is theirs (ParticipantImages).
       def handle_image_upload(req, id)
         session_dir = image_session_dir(id)
         return session_not_found(id) unless session_dir
+        return participant_image_upload(req, id, session_dir) unless principal(req).owner?
 
-        length = req.content_length.to_i
-        if length > MAX_IMAGE_UPLOAD_BYTES
-          return error_response(413, "too_large", "an image may be up to #{MAX_IMAGE_UPLOAD_BYTES / 1024 / 1024} MB")
-        end
-
-        bytes = request_body(req, MAX_IMAGE_UPLOAD_BYTES + 1).to_s.b
-        if bytes.bytesize > MAX_IMAGE_UPLOAD_BYTES
-          return error_response(413, "too_large", "an image may be up to #{MAX_IMAGE_UPLOAD_BYTES / 1024 / 1024} MB")
-        end
+        bytes = image_upload_bytes(req)
+        return error_response(413, "too_large", image_too_large_detail) unless bytes
 
-        name = File.basename(req.params["name"].to_s)[0, 120]
-        ref = ImageStore.ingest(session_dir, bytes: bytes, name: name.empty? ? "image" : name, source: "user")
+        ref = ImageStore.ingest(session_dir, bytes: bytes, name: upload_name(req), source: "user")
         json_response(201, ref)
       rescue ImageStore::Error => e
         error_response(422, "bad_image", e.message)
       end
 
+      # An upload's body, or nil when it is over MAX_IMAGE_UPLOAD_BYTES (by
+      # its Content-Length or what came).
+      def image_upload_bytes(req)
+        return nil if req.content_length.to_i > MAX_IMAGE_UPLOAD_BYTES
+
+        bytes = request_body(req, MAX_IMAGE_UPLOAD_BYTES + 1).to_s.b
+        bytes.bytesize > MAX_IMAGE_UPLOAD_BYTES ? nil : bytes
+      end
+
+      def image_too_large_detail = "an image may be up to #{MAX_IMAGE_UPLOAD_BYTES / 1024 / 1024} MB"
+
+      # An upload's ?name=, a base name without control characters; "image"
+      # without one.
+      def upload_name(req)
+        name = File.basename(req.params["name"].to_s).gsub(/[[:cntrl:]]/, "")[0, 120]
+        name.empty? ? "image" : name
+      end
+
       # GET /api/sessions/:id/images/<hash>.<ext>: a stored image (only
-      # raster types; never svg), for the page's thumbnails.
-      def handle_image(_req, id, name)
+      # raster types; never svg), for the page's thumbnails. A participant
+      # reads only an image they uploaded (ParticipantImages), never
+      # cached; any other is the 404 an unknown file gets.
+      def handle_image(req, id, name)
         session_dir = image_session_dir(id)
         return not_found(path: "images/#{name}") unless session_dir && IMAGE_NAME_RE.match?(name.to_s)
 
+        participant = !principal(req).owner?
+        return not_found(path: "images/#{name}") if participant && !participant_owns_image?(req, session_dir, name)
+
         path = File.join(session_dir, ImageStore::DIR, name)
         return not_found(path: "images/#{name}") unless File.file?(path) && !File.symlink?(path)
 
         body = File.binread(path)
         [200, { "Content-Type" => IMAGE_TYPES.fetch(File.extname(name).delete(".")), "Content-Length" => body.bytesize.to_s,
-                "X-Content-Type-Options" => "nosniff", "Cache-Control" => "private, max-age=86400" }, [body]]
+                "X-Content-Type-Options" => "nosniff", "Cache-Control" => participant ? "no-store" : "private, max-age=86400" },
+         [body]]
       end
 
       # The Bridge decides the reason (Bridge::CANCEL_REASONS; anything
       # else is manual) and the reply echoes its choice. No reason: user.
       def handle_cancel(req, id)
         @session_class.load(id, state_dir: default_state_dir)
+        return participant_cancel(req, id) unless principal(req).owner?
 
         parsed = parse_json(request_body(req))
         reason = (parsed["reason"] if parsed.is_a?(Hash)).to_s.strip
@@ -318,6 +337,12 @@ module Samagotchi
 
         turn_id = (parsed["turn_id"] if parsed.is_a?(Hash)).to_s.strip
         request = ->(client) { turn_id.empty? ? client.cancel(reason: reason) : client.cancel(reason: reason, turn_id: turn_id) }
+        relay_cancel(id, request)
+      end
+
+      # The cancel's relay to the worker and its answers (the owner's and a
+      # participant's, ParticipantAccess#participant_cancel).
+      def relay_cancel(id, request)
         relay(id, bridge_client(id), request, what: "the turn was not cancelled", cant: "cancel turns") do |reply|
           case reply.status
           when 202

data/lib/samagotchi/web/session_create.rb

@@ -300,7 +300,7 @@ module Samagotchi
       # default) is known not to take images; nil when it does or is
       # unknown (the worker decides when the turn runs).
       def vision_refused(name, typed)
-        refusal = SendCommand.vision_refusal(name, SendCommand.vision_answer(name, typed: typed))
+        refusal = SendCommand.vision_refusal_for(name, typed: typed)
         refusal && error_response(422, "no_vision", refusal)
       end