pi-weave 0.3.8 → 0.3.10

package/src/web/client/trail/trail.model.ts

@@ -0,0 +1,195 @@
+/**
+ * The recall trail, decided (issue #78).
+ *
+ * `GET /api/trail` lists the notes the agent searched, read and wrote. This
+ * module turns that list into the two things the workspace draws:
+ *
+ *  - {@link trailMarks}: which nodes glow right now, how, and how strongly.
+ *    The glow fades over {@link TRAIL_FADE_MS}; a replayed turn relights its
+ *    steps one after another from the moment it was clicked.
+ *  - {@link trailTurns}: the "This turn" strip — each turn's steps in order,
+ *    worded as `searched "auth" → read Auth migration → appended Auth migration`.
+ *
+ * Pure, DOM-free and clock-free (every function takes `now`), like the other
+ * `*.model.ts` files, so the whole feature is covered by unit tests.
+ */
+
+import type { GraphPayload, TrailPayload, WireTrailEvent, WireTrailKind } from "../../shared/wire";
+
+/** How long a glow takes to fade out completely. */
+export const TRAIL_FADE_MS = 60_000;
+
+/** How often the fade repaints while something is glowing. */
+export const TRAIL_TICK_MS = 1_000;
+
+/** In a replay, the gap between one step lighting and the next. */
+export const REPLAY_STEP_MS = 700;
+
+/** How many turns the strip lists. */
+export const TRAIL_TURNS_SHOWN = 5;
+
+/** One glowing node. `strength` runs 1 (just happened) → 0 (faded). */
+export interface TrailMark {
+  kind: WireTrailKind;
+  strength: number;
+}
+
+/** A replay in progress: which turn, and when it was clicked. */
+export interface TrailReplay {
+  turn: number;
+  startedAt: number;
+}
+
+/** A write outranks a read, which outranks a search hit. */
+const RANK: Readonly<Record<WireTrailKind, number>> = { searched: 0, read: 1, wrote: 2 };
+
+const NO_MARKS: ReadonlyMap<string, TrailMark> = new Map();
+
+/** When each event lights, or `null` if it is not part of what is shown. */
+function lightTimes(trail: TrailPayload, replay: TrailReplay | null): Array<{ event: WireTrailEvent; at: number }> {
+  if (replay === null) return trail.events.map((event) => ({ event, at: Date.parse(event.at) }));
+  return trail.events
+    .filter((event) => event.turn === replay.turn)
+    .map((event, index) => ({ event, at: replay.startedAt + index * REPLAY_STEP_MS }));
+}
+
+/**
+ * Node id → glow. A node touched several ways in one turn shows the strongest
+ * kind (wrote > read > searched) at the freshest strength; a later turn's
+ * touch replaces an earlier turn's, so a note read now is not still shown as
+ * written a turn ago.
+ *
+ * Live, an event stamped slightly in the future (clock skew) glows at full
+ * strength; in a replay a step whose moment has not come yet stays dark.
+ */
+export function trailMarks(trail: TrailPayload | null, now: number, replay: TrailReplay | null = null): ReadonlyMap<string, TrailMark> {
+  if (trail === null) return NO_MARKS;
+  const marks = new Map<string, TrailMark>();
+  const turnOf = new Map<string, number>();
+  for (const { event, at } of lightTimes(trail, replay)) {
+    const age = now - at;
+    if (replay !== null && age < 0) continue;
+    const strength = Math.min(1, 1 - age / TRAIL_FADE_MS);
+    if (!(strength > 0)) continue;
+    for (const slug of event.slugs) {
+      const id = `note:${slug}`;
+      // A newer turn's touch replaces an older turn's; within a turn the strongest kind wins.
+      const existing = turnOf.get(id) === event.turn ? marks.get(id) : undefined;
+      const kind = existing === undefined || RANK[event.kind] > RANK[existing.kind] ? event.kind : existing.kind;
+      marks.set(id, { kind, strength: Math.max(strength, existing?.strength ?? 0) });
+      turnOf.set(id, event.turn);
+    }
+  }
+  return marks.size === 0 ? NO_MARKS : marks;
+}
+
+/** Whether anything is still glowing or still to light — i.e. whether the fade clock should run. */
+export function trailLive(trail: TrailPayload | null, now: number, replay: TrailReplay | null = null): boolean {
+  if (trail === null) return false;
+  return lightTimes(trail, replay).some(({ at }) => now - at < TRAIL_FADE_MS);
+}
+
+/** One note named in a step, ready to be a link. */
+export interface TrailNoteView {
+  id: string;
+  label: string;
+}
+
+/** One step of a turn. */
+export interface TrailStepView {
+  key: string;
+  kind: WireTrailKind;
+  /** `searched "auth"`, `read`, `appended`, … */
+  verb: string;
+  /** The notes to link. Empty for a search, which names its hit count in `detail` instead. */
+  notes: TrailNoteView[];
+  detail: string | null;
+}
+
+/** One turn in the strip, newest first. */
+export interface TrailTurnView {
+  turn: number;
+  /** Local `HH:MM` of the turn's first step. */
+  time: string;
+  steps: TrailStepView[];
+  /** Distinct notes read or written. */
+  used: number;
+}
+
+const WROTE_VERB: Readonly<Record<string, string>> = {
+  add: "created",
+  append: "appended",
+  finalize: "finalized",
+  links: "fixed links in",
+};
+
+function stepView(event: WireTrailEvent, labels: ReadonlyMap<string, string>): TrailStepView {
+  const notes = event.slugs.map((slug) => ({ id: `note:${slug}`, label: labels.get(`note:${slug}`) ?? slug }));
+  if (event.kind === "searched") {
+    const hits = event.slugs.length;
+    return {
+      key: `${event.seq}:s`,
+      kind: "searched",
+      verb: event.query === undefined ? "searched" : `searched "${event.query}"`,
+      notes: [],
+      detail: hits === 0 ? "no hits" : `${hits} hit${hits === 1 ? "" : "s"}`,
+    };
+  }
+  return {
+    key: `${event.seq}:${event.kind}`,
+    kind: event.kind,
+    verb: event.kind === "read" ? "read" : WROTE_VERB[event.action] ?? "wrote",
+    notes,
+    detail: null,
+  };
+}
+
+function clock(iso: string, seconds = false): string {
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return "";
+  const parts = [at.getHours(), at.getMinutes(), ...(seconds ? [at.getSeconds()] : [])];
+  return parts.map((part) => String(part).padStart(2, "0")).join(":");
+}
+
+/**
+ * The strip: the newest {@link TRAIL_TURNS_SHOWN} turns, each with its steps in order.
+ *
+ * When the harness has started a turn that has not touched a note yet (Pi's
+ * `agent_start` moves `trail.turn` ahead of the newest event), that empty
+ * turn leads the list, so the previous turn is never presented as current.
+ */
+export function trailTurns(trail: TrailPayload | null, graph: GraphPayload | null): TrailTurnView[] {
+  if (trail === null || trail.events.length === 0) return [];
+  const labels = new Map<string, string>((graph?.model.nodes ?? []).map((node) => [node.id, node.label]));
+  const byTurn = new Map<number, WireTrailEvent[]>();
+  for (const event of trail.events) {
+    const events = byTurn.get(event.turn);
+    if (events === undefined) byTurn.set(event.turn, [event]);
+    else events.push(event);
+  }
+  const turns = [...byTurn.entries()].sort(([a], [b]) => b - a);
+  // Turns in the same minute would get identical chips, so those show seconds.
+  const minutes = turns.map(([, events]) => clock(events[0]!.at));
+  const views = turns.map(([turn, events], index) => {
+    const used = new Set(events.filter((event) => event.kind !== "searched").flatMap((event) => event.slugs));
+    const shared = minutes.filter((minute) => minute === minutes[index]).length > 1;
+    return { turn, time: clock(events[0]!.at, shared), steps: events.map((event) => stepView(event, labels)), used: used.size };
+  });
+  if (trail.turn > views[0]!.turn) views.unshift({ turn: trail.turn, time: "", steps: [], used: 0 });
+  return views.slice(0, TRAIL_TURNS_SHOWN);
+}
+
+/** The strip's heading for a turn: the latest is "This turn", older ones are their time. */
+/** What the strip says for a turn with no steps yet. */
+export const TRAIL_EMPTY_TURN = "Nothing recalled yet.";
+
+export function turnHeading(view: TrailTurnView, latest: boolean): string {
+  return latest ? "This turn" : view.time === "" ? `Turn ${view.turn}` : view.time;
+}
+
+/** The tree row's class for a glow, or `""`. Strength is bucketed so the class list stays small. */
+export function trailRowClass(mark: TrailMark | undefined): string {
+  if (mark === undefined) return "";
+  const level = mark.strength > 0.66 ? 3 : mark.strength > 0.33 ? 2 : 1;
+  return ` weave-row-trail weave-row-trail-${mark.kind} weave-row-trail-${level}`;
+}

package/src/web/client/trail/trail.ts

@@ -0,0 +1,45 @@
+/** Polling `GET /api/trail`, alongside (not inside) the graph poll in `../workspace.ts`. */
+
+import type { TrailPayload } from "../../shared/wire";
+import type { FetchLike } from "../api";
+import { fetchTrail } from "../api";
+import { POLL_MS } from "../workspace";
+
+export interface TrailPollOptions {
+  fetch: FetchLike;
+  onTrail: (trail: TrailPayload) => void;
+  repeat?: (fn: () => void, ms: number) => () => void;
+}
+
+/**
+ * Poll the trail every {@link POLL_MS}, revalidating on its stamp, and report
+ * only fresh payloads. A failed poll keeps what was there: the trail is an
+ * extra, and a blip must not blank it. Returns `stop`.
+ */
+export function startTrailPoll(opts: TrailPollOptions): () => void {
+  let previous: TrailPayload | null = null;
+  let stopped = false;
+  let polling = false;
+  const poll = async (): Promise<void> => {
+    if (stopped || polling) return;
+    polling = true;
+    try {
+      const result = await fetchTrail(opts.fetch, previous);
+      if (stopped || !result.ok || result.cached) return;
+      previous = result.data;
+      opts.onTrail(result.data);
+    } finally {
+      polling = false;
+    }
+  };
+  const repeat = opts.repeat ?? ((fn, ms) => {
+    const timer = setInterval(fn, ms);
+    return () => clearInterval(timer);
+  });
+  const cancel = repeat(() => void poll(), POLL_MS);
+  void poll();
+  return () => {
+    stopped = true;
+    cancel();
+  };
+}

package/src/web/client/tree/Tree.tsx

@@ -1,5 +1,7 @@
 /** The vault and repository tree column. */
 
+import type { TrailMark } from "../trail/trail.model";
+import { trailRowClass } from "../trail/trail.model";
 import { NOTE_DRAG_TYPE } from "../shell/shell.model";
 import { useLayoutEffect, useRef, useState } from "preact/hooks";
 import { createFolder, deleteFolder, deleteNote, moveNote, renameFolder, renameNote } from "../api";
@@ -46,6 +48,8 @@ export interface TreeProps {
   graph: GraphPayload | null;
   selectedId: string | null;
   recentIds: ReadonlySet<string>;
+  /** Recall-trail glows by row id (`trail/trail.model.ts`). */
+  trail?: ReadonlyMap<string, TrailMark>;
   onSelect: (id: string, newTab?: boolean, keepSidebar?: boolean) => void;
   /**
    * Ask before a mutation that would invalidate an open draft. `false` means
@@ -76,13 +80,13 @@ export function Icon({ name, class: className }: { name: IconName; class?: strin
   );
 }
 
-function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMenu, onDrop }: { view: ReturnType<typeof rowViews>[number]; recentIds: ReadonlySet<string>; edit: string | null; onEdit: (value: string) => void; onRename: (value: string | null) => void; onSelect: (newTab: boolean) => void; onToggle: () => void; onMenu: (x: number, y: number) => void; onDrop: (id: string) => void }) {
+function Row({ view, recentIds, trail, edit, onEdit, onRename, onSelect, onToggle, onMenu, onDrop }: { view: ReturnType<typeof rowViews>[number]; recentIds: ReadonlySet<string>; trail: TrailMark | undefined; edit: string | null; onEdit: (value: string) => void; onRename: (value: string | null) => void; onSelect: (newTab: boolean) => void; onToggle: () => void; onMenu: (x: number, y: number) => void; onDrop: (id: string) => void }) {
   const folder = dropFolder(view.id);
   return (
     <li
       id={view.domId}
       data-row-id={view.id}
-      class={`weave-row weave-row-${view.kind}${view.selected ? " weave-row-on" : ""}${recentIds.has(view.id) ? " weave-row-new" : ""}`}
+      class={`weave-row weave-row-${view.kind}${view.selected ? " weave-row-on" : ""}${recentIds.has(view.id) ? " weave-row-new" : ""}${trailRowClass(trail)}`}
       role="treeitem"
       aria-level={view.level}
       aria-posinset={view.posinset}
@@ -297,7 +301,7 @@ export function Tree(props: TreeProps) {
             setMenu({ id: "vault", label: "Vault", x: event.clientX, y: event.clientY });
           }}
         >
-          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={commitEdit} onSelect={(newTab) => { props.onSelect(view.id, newTab); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) { const target = mutableTreeRow(dragged); if (target !== null && !props.onMutate(affectedNoteSlugs(props.graph, target))) return; void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); } }} />)}
+          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} trail={props.trail?.get(view.id)} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={commitEdit} onSelect={(newTab) => { props.onSelect(view.id, newTab); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) { const target = mutableTreeRow(dragged); if (target !== null && !props.onMutate(affectedNoteSlugs(props.graph, target))) return; void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); } }} />)}
         </ul>
       ) : <p class="weave-tree-empty">{empty}</p>}
       <p class="weave-tree-count">{rowCountLabel(rows)}</p>

package/src/web/client/tree/tree.model.ts

@@ -49,11 +49,8 @@ export type TreeViewState = TreeState;
 /**
  * The provenance filter cycle: all → human → agent → generated → all.
  *
- * The same order as the TUI's `p` key (`src/pi/viewer/tui/theme.ts`), and
- * declared again here because the client tier may not import `src/pi` and the
- * order is not part of `src/core/view`. That is a real, if small, duplication
- * — so it is one array with a test asserting its contents, rather than an
- * `if/else` chain in two places. If a fourth provenance is ever added, the
+ * The order is not part of `src/core/view`, so it is one array with a test
+ * asserting its contents, rather than an `if/else` chain in two places. If a fourth provenance is ever added, the
  * honest fix is to promote this into `src/core/view` and take it through the
  * door; today it is four literals and a promotion would be ceremony.
  */

package/src/web/server/page.ts

@@ -243,7 +243,7 @@ export function renderPage(opts: RenderPageOptions): RenderedPage {
     "</head>",
     "<body>",
     `<div id="app" data-cwd="${escapeAttr(opts.bootstrap.cwd)}">`,
-    "<noscript>pi-weave needs JavaScript. Use <code>/weave-view tui</code> instead.</noscript>",
+    "<noscript>pi-weave needs JavaScript to show the workspace.</noscript>",
     "</div>",
     `<script type="application/json" id="${escapeAttr(BOOTSTRAP_ELEMENT_ID)}" nonce="${escapeAttr(nonce)}">`,
     jsonScriptBody(opts.bootstrap),

package/src/web/server/routes.ts

@@ -6,6 +6,7 @@
  * | GET    | `/`                      | the HTML shell, with its per-response nonce  |
  * | GET    | `/app.js`                | the committed bundle, `Cache-Control: no-store` |
  * | GET    | `/api/graph`             | {@link GraphPayload}, ETag'd on `stamp`      |
+ * | GET    | `/api/trail`             | {@link TrailPayload}, ETag'd on `stamp`      |
  * | GET    | `/api/note/:slug`        | {@link NotePayload}                          |
  * | POST   | `/api/note/:slug`        | save a note's Markdown body                  |
  * | POST   | `/api/notes`            | create an empty human-authored vault note    |
@@ -15,6 +16,9 @@
  * | POST   | `/api/folder/:path`        | create a vault folder                      |
  * | POST   | `/api/folder/:path/rename` | rename a vault folder                      |
  * | DELETE | `/api/folder/:path`      | delete a vault folder                        |
+ * | GET    | `/api/history/:slug`     | {@link HistoryWirePayload}                   |
+ * | GET    | `/api/history-settings`  | {@link HistorySettingsPayload}               |
+ * | POST   | `/api/history-settings`  | turn note history on or off                  |
  * | GET    | `/api/okf/:rel`          | {@link OkfFilePayload}                       |
  * | GET    | `/api/artifact/:rel`     | sandboxed HTML artifact                     |
  * | GET    | `/api/search?q=`         | {@link SearchPayload}                        |
@@ -49,22 +53,28 @@ import { createReadStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
 import { createVaultBackup } from "./backup";
 import { readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { WorkspaceSnapshot } from "../../core/cache/workspace";
 import { WorkspaceCache } from "../../core/cache/workspace";
 import { readOkfFileForView } from "../../core/graph/current";
 import type { GraphModel as CoreGraphModel } from "../../core/graph/model";
+import { encodeRevisions, historyEnabled, historyTrimmed, setHistoryEnabled } from "../../core/history";
 import { openNoteInEditor } from "../../core/openInEditor";
+import { recallTrail, type RecallTrail } from "../../core/trail";
 import type { Note } from "../../core/types";
 import type { VaultMutationResult } from "../../core/vault";
-import { addNote, createFolder, deleteFolder, deleteNote, getNote, moveNote, renameFolder, renameNote, resolveHtmlPath, searchNotes, setNoteBody } from "../../core/vault";
+import { addNote, createFolder, deleteFolder, deleteNote, getNote, moveNote, renameFolder, readNoteHistory, renameNote, resolveHtmlPath, searchNotes, setNoteBody } from "../../core/vault";
 import { deriveTagIndex, type TaggedNote } from "../../core/view/links";
 import type {
   GraphPayload,
+  HistoryWirePayload,
+  HistorySettingsPayload,
   NotePayload,
   OkfFilePayload,
   OpenResult,
   SearchPayload,
+  TrailPayload,
   ViewNote,
 } from "../shared/wire";
 import { WIRE_MODEL_OMITTED_KEYS } from "../shared/wire";
@@ -85,6 +95,8 @@ export interface RouteDeps {
   /** Test seam for `POST /api/open`; defaults to the real editor shell-out. */
   openNote?: ((slug: string) => Promise<boolean>) | undefined;
   workspaceState: WorkspaceStateStore;
+  /** The recall trail to serve. Defaults to the process-wide one the tools write. */
+  trail?: RecallTrail | undefined;
 }
 
 const JSON_TYPE = "application/json; charset=utf-8";
@@ -383,6 +395,7 @@ async function route(
   if (method === "GET" && path === "/") return sendShell(deps, res);
   if (method === "GET" && path === "/app.js") return sendBundle(deps, res);
   if (method === "GET" && path === "/api/graph") return sendGraph(deps, req, res);
+  if (method === "GET" && path === "/api/trail") return sendTrail(deps, req, res);
   if (method === "GET" && path === "/api/backup") {
     const backup = await createVaultBackup(deps.vaultRoot);
     try {
@@ -413,6 +426,8 @@ async function route(
     const handled = await routeNote(deps, method, path.slice("/api/note/".length), req, res);
     if (handled) return;
   }
+  if (method === "GET" && path.startsWith("/api/history/")) return sendHistory(deps, path.slice("/api/history/".length), res);
+  if (path === "/api/history-settings" && (method === "GET" || method === "POST")) return historySettings(deps, method, req, res);
   if (method === "GET" && path.startsWith("/api/okf/")) {
     return sendOkf(deps, path.slice("/api/okf/".length), res);
   }
@@ -558,6 +573,29 @@ async function sendGraph(deps: RouteDeps, req: IncomingMessage, res: ServerRespo
   res.end(body);
 }
 
+/**
+ * `GET /api/trail`. The trail is process-wide, so it is filtered to this
+ * server's vault; the stamp is the buffer's own, which moves on every record.
+ */
+function sendTrail(deps: RouteDeps, req: IncomingMessage, res: ServerResponse): void {
+  const snapshot = (deps.trail ?? recallTrail).snapshot();
+  const etag = `"${snapshot.stamp}"`;
+  const conditional = req.headers["if-none-match"];
+  if (matchesEtag(etag, typeof conditional === "string" ? conditional : undefined)) {
+    res.writeHead(304, { ...baseHeaders(), etag, "cache-control": "no-cache" });
+    res.end();
+    return;
+  }
+  const payload: TrailPayload = {
+    stamp: snapshot.stamp,
+    turn: snapshot.turn,
+    events: snapshot.events
+      .filter((event) => resolvePath(event.vault) === resolvePath(deps.vaultRoot))
+      .map(({ vault: _vault, ...event }) => event),
+  };
+  sendJson(res, 200, payload, { etag, "cache-control": "no-cache" });
+}
+
 /**
  * `If-None-Match` matching, weak-comparison style.
  *
@@ -615,11 +653,17 @@ async function routeNote(
       sendJson(res, 400, { error: "expected JSON object" });
       return true;
     }
-    const fields = body as { body?: unknown; name?: unknown; folder?: unknown };
+    const fields = body as { body?: unknown; raw?: unknown; name?: unknown; folder?: unknown };
     // The payload decides, not the suffix: slugs nest, so `archive/rename` is
     // a real note and only `{name}`/`{folder}` mean the action.
     if (typeof fields.body === "string") {
-      sendMutation(res, await setNoteBody(deps.vaultRoot, target, fields.body));
+      // `raw: true` is the editor saying the person changed their own Raw
+      // words; without it the on-disk tail is kept, whatever the body says.
+      if (fields.raw !== undefined && typeof fields.raw !== "boolean") {
+        sendJson(res, 400, { error: "expected raw: boolean" });
+        return true;
+      }
+      sendMutation(res, await setNoteBody(deps.vaultRoot, target, fields.body, new Date(), "human", fields.raw === true ? "replace" : "keep"));
       return true;
     }
     if (action === null) {
@@ -700,6 +744,42 @@ function notePayload(note: Note): NotePayload {
   return { note: view };
 }
 
+/**
+ * Every saved revision of a note. The note's current body is passed in so an
+ * edit made outside pi-weave since the last write shows as the final step.
+ */
+async function sendHistory(deps: RouteDeps, slug: string, res: ServerResponse): Promise<void> {
+  const revisions = await readNoteHistory(deps.vaultRoot, slug);
+  if (revisions === null) {
+    sendJson(res, 404, { error: "no such note" });
+    return;
+  }
+  // Deltas, as on disk: full bodies for every revision would grow with the
+  // square of the note's length.
+  const trimmed = await historyTrimmed(deps.vaultRoot, slug);
+  const payload: HistoryWirePayload = {
+    slug,
+    enabled: await historyEnabled(deps.vaultRoot),
+    trimmed,
+    revisions: encodeRevisions(revisions, trimmed),
+  };
+  sendJson(res, 200, payload, { "cache-control": "no-store" });
+}
+
+async function historySettings(deps: RouteDeps, method: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (method === "POST") {
+    const body = await readJsonBody(req);
+    const enabled = typeof body === "object" && body !== null ? (body as { enabled?: unknown }).enabled : undefined;
+    if (typeof enabled !== "boolean") {
+      sendJson(res, 400, { error: "expected { enabled: boolean }" });
+      return;
+    }
+    await setHistoryEnabled(deps.vaultRoot, enabled);
+  }
+  const payload: HistorySettingsPayload = { enabled: await historyEnabled(deps.vaultRoot) };
+  sendJson(res, 200, payload, { "cache-control": "no-store" });
+}
+
 async function sendOkf(deps: RouteDeps, rel: string, res: ServerResponse): Promise<void> {
   // Anchored under `<cwd>/.okf` by `readOkfFileForView`, which resolves and
   // then re-checks the prefix — the only correct order.

package/src/web/shared/logo.ts

@@ -4,7 +4,7 @@
  * The web viewer is a single committed bundle behind a strict CSP
  * (img-src 'self' data:), so the brand mark is an inlined 48×48 PNG —
  * the transparent-background spider derived from docs/pi-weave-logo.png —
- * rather than a new static route. Same pattern as the TUI's branding.ts.
+ * rather than a new static route.
  */
 export const LOGO_MARK_MIME = "image/png";
 /** 48×48 transparent PNG, base64 — crisp at 2× for the 18px header mark. */

package/src/web/shared/themes.ts

@@ -3,7 +3,7 @@
  * `light` and `dark` keep existing saved choices compatible.
  */
 const latte = {
-  bg: "#eff1f5", panel: "#e6e9ef", page: "#dce0e8", raise: "#ccd0da",
+  bg: "#eff1f5", panel: "#e6e9ef", page: "#ffffff", raise: "#ccd0da",
   fg: "#4c4f69", dim: "#56586a", faint: "#606274", line: "#ccd0da", "line-strong": "#bcc0cc",
   accent: "#7113ec", ok: "#28641b", warn: "#7c4f10", bad: "#b20d30",
 };

package/src/web/shared/view.ts

@@ -61,10 +61,9 @@
  * ## Why this is a small list
  *
  * Deliberately not `export * from "../../core/view"`. The barrel pulls in
- * `health.ts` (a TUI surface) and `links.ts`'s tag index (derived server-side
- * into `GraphPayload.tags`), neither of which any browser column consumes
- * today — and each one it pulled in would be a module the purity guard then
- * has to defend forever.
+ * `links.ts`'s tag index (derived server-side into `GraphPayload.tags`),
+ * which no browser column consumes today — and each module it pulled in
+ * would be one the purity guard then has to defend forever.
  *
  * So this is an allowlist, on the same principle as the `npm` column in
  * `tests/web/tiers.test.ts`: the surface the columns actually use, and nothing
@@ -131,6 +130,13 @@ export type { TreeRow, TreeState } from "../../core/view/tree";
  */
 export { formatTreeMeta, relTime } from "../../core/view/time";
 
+/**
+ * The note editor holds only the head of a body; the `## Raw` tail is shown
+ * read-only beneath it and rejoined on save. The vault splits with the same
+ * function, so the editor can never hide text the server would overwrite.
+ */
+export { joinRawOpening, joinRawTail, splitRawOpening, splitRawTail } from "../../core/view/rawTail";
+
 // --- context rail (§1.2, P2) --------------------------------------------------
 
 /** Links, backlinks and the ordered meta block for the selected node. */

package/src/web/shared/wire.ts

@@ -40,7 +40,7 @@
  * contract.
  */
 
-import type { WireGraphModel, WireNoteSearchHit, WireNoteSource, WireViewNote } from "./graph";
+import type { WireGraphModel, WireNoteSearchHit, WireViewNote } from "./graph";
 import type { Point } from "./metrics";
 
 /**
@@ -140,10 +140,83 @@ export interface GraphPayload {
 }
 
 /** `GET /api/note/:slug`. */
+/** How the agent touched a note — see `src/core/trail.ts`. */
+export type WireTrailKind = "searched" | "read" | "wrote";
+
+/** One recall-trail step. `at` is ISO; `slugs` may be empty for a search with no hits. */
+export interface WireTrailEvent {
+  seq: number;
+  turn: number;
+  at: string;
+  kind: WireTrailKind;
+  action: string;
+  slugs: string[];
+  query?: string;
+}
+
+/**
+ * `GET /api/trail` — the notes the agent searched, read and wrote this
+ * session, oldest first, filtered to this workspace's vault. ETag'd on
+ * `stamp`, like the graph, so polling it is a `304` while the agent is idle.
+ */
+export interface TrailPayload {
+  stamp: string;
+  turn: number;
+  events: WireTrailEvent[];
+}
+
 export interface NotePayload {
   note: ViewNote;
 }
 
+/** One saved revision of a note, body included. */
+export interface HistoryRevision {
+  /** ISO-8601 time of the change. */
+  at: string;
+  /** Who made it: `outside` is any editor other than pi-weave. */
+  by: "human" | "agent" | "outside" | "system";
+  /** What kind of change: create, edit, append, raw, finalize, generate, repair, outside, baseline. */
+  op: string;
+  body: string;
+}
+
+/** A history payload as the client works with it: every body rebuilt. */
+export interface HistoryPayload {
+  slug: string;
+  /** Whether new revisions are being recorded. */
+  enabled: boolean;
+  /** Older revisions were dropped to keep the note's history file small. */
+  trimmed: boolean;
+  revisions: HistoryRevision[];
+}
+
+/**
+ * One revision on the wire: a full body, or a delta against the one before
+ * (keep `keep[0]` characters from the start and `keep[1]` from the end, and
+ * put `text` between them). The first revision is always full.
+ */
+export interface HistoryWireRevision {
+  at: string;
+  by: HistoryRevision["by"];
+  op: string;
+  full?: string;
+  keep?: [number, number];
+  text?: string;
+}
+
+/** `GET /api/history/:slug`. Oldest first; the last revision is the note as it is now. */
+export interface HistoryWirePayload {
+  slug: string;
+  enabled: boolean;
+  trimmed: boolean;
+  revisions: HistoryWireRevision[];
+}
+
+/** `GET` and `POST /api/history-settings`. */
+export interface HistorySettingsPayload {
+  enabled: boolean;
+}
+
 /** `GET /api/okf/:rel`. */
 export interface OkfFilePayload {
   /** The requested path, relative to `<cwd>/.okf`. Echoed, never resolved. */

package/src/web/shared/workspace.ts

@@ -27,6 +27,11 @@ export interface WorkspaceLayout {
   readonly ratio: number;
   readonly treeVisible: boolean;
   readonly contextVisible: boolean;
+  /**
+   * Context as a docked column (true) or a card floating over the page's
+   * right margin (false, the default since the refresh).
+   */
+  readonly contextPinned: boolean;
   readonly treeWidth: number;
   readonly contextWidth: number;
   readonly contextGraphHeight: number;
@@ -50,6 +55,7 @@ export function initialLayout(): WorkspaceLayout {
     ratio: 0.5,
     treeVisible: true,
     contextVisible: true,
+    contextPinned: false,
     treeWidth: 240,
     contextWidth: 240,
     contextGraphHeight: 260,
@@ -246,11 +252,13 @@ function boundedId(value: unknown, prefix?: "pane" | "tab"): value is string {
 }
 
 export function parseWorkspaceLayout(value: unknown): WorkspaceLayout | null {
-  if (!record(value) || !exactKeys(value, ["version", "panes", "activePane", "split", "ratio", "treeVisible", "contextVisible", "treeWidth", "contextWidth", "theme", ...["preferences", "contextGraphHeight", "contextTagsHeight"].filter(key => Object.hasOwn(value, key))])) return null;
+  if (!record(value) || !exactKeys(value, ["version", "panes", "activePane", "split", "ratio", "treeVisible", "contextVisible", "treeWidth", "contextWidth", "theme", ...["preferences", "contextGraphHeight", "contextTagsHeight", "contextPinned"].filter(key => Object.hasOwn(value, key))])) return null;
   if (value["version"] !== 1 || !Array.isArray(value["panes"]) || value["panes"].length < 1 || value["panes"].length > 2 || !boundedId(value["activePane"], "pane")) return null;
   if (value["split"] !== "right" && value["split"] !== "down") return null;
   if (typeof value["ratio"] !== "number" || !Number.isFinite(value["ratio"]) || value["ratio"] < 0.1 || value["ratio"] > 0.9) return null;
   if (typeof value["treeVisible"] !== "boolean" || typeof value["contextVisible"] !== "boolean") return null;
+  const contextPinned = Object.hasOwn(value, "contextPinned") ? value["contextPinned"] : false;
+  if (typeof contextPinned !== "boolean") return null;
   if (typeof value["treeWidth"] !== "number" || !Number.isFinite(value["treeWidth"]) || value["treeWidth"] < 120 || value["treeWidth"] > 800) return null;
   if (typeof value["contextWidth"] !== "number" || !Number.isFinite(value["contextWidth"]) || value["contextWidth"] < 120 || value["contextWidth"] > 800) return null;
   const contextGraphHeight = Object.hasOwn(value, "contextGraphHeight") ? value["contextGraphHeight"] : 260;
@@ -292,7 +300,7 @@ export function parseWorkspaceLayout(value: unknown): WorkspaceLayout | null {
     panes.push({ id: rawPane["id"], tabs, activeTab: rawPane["activeTab"], ...(typeof lastDocumentTab === "string" ? { lastDocumentTab } : {}) });
   }
   if (count > MAX_TABS || graphs > 1 || !panes.some((pane) => pane.id === value["activePane"])) return null;
-  return { version: 1, panes, activePane: value["activePane"], split: value["split"], ratio: value["ratio"], treeVisible: value["treeVisible"], contextVisible: value["contextVisible"], treeWidth: value["treeWidth"], contextWidth: value["contextWidth"], contextGraphHeight, contextTagsHeight, theme: value["theme"], preferences };
+  return { version: 1, panes, activePane: value["activePane"], split: value["split"], ratio: value["ratio"], treeVisible: value["treeVisible"], contextVisible: value["contextVisible"], contextPinned, treeWidth: value["treeWidth"], contextWidth: value["contextWidth"], contextGraphHeight, contextTagsHeight, theme: value["theme"], preferences };
 }
 
 /** Startup choice resets navigation only; appearance and sidebar preferences survive. */