pi-weave 0.1.5 → 0.1.7

package/README.md

@@ -13,21 +13,15 @@
 
 **An agent-native knowledge workspace for your life and your code.**
 
-pi-weave is a [pi](https://github.com/earendil-works/pi)
-extension with two faces that are secretly one:
+pi-weave is a [pi](https://github.com/earendil-works/pi) extension with two faces that are secretly one:
 
-1. **A smart notepad with AI skills.** A persistent vault of knowledge —
-   decisions, ideas, people, meetings — stored as plain Markdown notes with
-   front matter under `~/.okf/notes/`. Your agent reads and writes it *with*
-   you; everything is editable by hand in any editor.
+1. **A smart notepad with AI skills.** A persistent vault of knowledge — decisions, ideas, people, meetings — stored as plain Markdown notes
+   with front matter under `~/.okf/notes/`. Your agent reads and writes it *with* you; everything is editable by hand in any editor.
 
-2. **A repository exploration engine.** A derived, git-aware knowledge index
-   of the repo you're in, living at `<repo>/.okf/` — structure, languages,
-   packages, modules, entry points, and staleness state. Rebuildable,
-   disposable, never the source of truth.
+2. **A repository exploration engine.** A derived, git-aware knowledge index of the repo you're in, living at `<repo>/.okf/` — structure,
+   languages, packages, modules, entry points, and staleness state. Rebuildable, disposable, never the source of truth.
 
-And one rule across both: **everything is equally usable by humans and
-agents.** No opaque databases. No lock-in formats.
+And one rule across both: **everything is equally usable by humans and agents.** No opaque databases. No lock-in formats.
 
 ```
 🧵 vault:12 · my-project:ok      ← pi's status line when weave is active
@@ -43,47 +37,37 @@ pi install /path/to/pi-weave       # local path
 
 Or for development: `pi -e ./src/pi/index.ts`.
 
-The package is [published on npm](https://www.npmjs.com/package/pi-weave);
-releases are cut from `main` and auto-published with provenance attestation
-([Publish workflow](.github/workflows/publish.yml)).
+The package is [published on npm](https://www.npmjs.com/package/pi-weave); releases are cut from `main` and auto-published with provenance
+attestation ([Publish workflow](.github/workflows/publish.yml)).
 
 ## What you get
 
 | Surface | Name | Purpose |
 |---|---|---|
-| Tool | `weave_note` | list / get / add / append / search vault notes |
+| Tool | `weave_note` | list / get / add / append / finalize / search vault notes |
 | Tool | `weave_repo` | status / scan / overview of the `.okf` repo index |
 | Command | `/weave` | workspace dashboard (vault + repository) |
 | Command | `/weave-scan` | build/refresh the repository index (light) |
 | Command | `/weave-scan deep` | light index + model-summarized sidecars (opt-in, incremental) |
-| Command | `/weave-view` | open the local graph viewer in your browser |
-| Command | `/weave-view tui` | explore the same graph in-terminal (keyboard) |
+| Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` run |
+| Command | `/weave-view` | explore the local knowledge graph in-terminal (keyboard) |
 | Skill | `weave-notepad` | how the agent should take good notes |
 | Skill | `weave-explore` | how the agent should explore repositories |
 
-**`/weave-view`** starts a loopback-only server (`127.0.0.1`, random port)
-and opens an interactive graph of your knowledge space: vault notes with
-trust provenance (solid = human, dashed = agent, dimmed = generated),
-wiki-link edges between notes, and the repository's structure anchored to
-git state. It reads disk live on every refresh — never a stale cache.
-Zoom/scroll, drag to pan, click nodes to expand; notes open in a rendered
-markdown side panel.
-
-**`/weave-view tui`** explores the same knowledge graph in the terminal:
-an expandable containment tree (Explore), a 1-hop neighborhood (Focus), a
-selected-node detail view with note/`.okf` bodies, and a staleness + link
-health surface — all keyboard-driven and read-only. Same data as the
-browser viewer (the `GraphModel` assembled from vault + repo index); a
-pure, harness-free view-model (`src/pi/viewer/tui/model.ts`) backs the
-`WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
-
-On session start, pi-weave detects the repository you're in, checks whether
-`.okf` exists and is fresh, and says so in the status line.
-
-**`/weave-scan deep`** is the opt-in, incremental deep pass: it refreshes the
-light index and then writes a short model summary per file to
-`.okf/repository/summaries/`, skipping files whose content hash is unchanged
-since their last summary. It costs tokens, so it never runs implicitly.
+**`/weave-view`** explores the knowledge graph in the terminal: an expandable containment tree (Explore), a 1-hop neighborhood
+(Focus), a selected-node detail view with note/`.okf` bodies, and a staleness + link health surface — all keyboard-driven and read-only.
+It reads disk live (never a stale cache) over the `GraphModel` assembled from the vault + repository index; a pure, harness-free view-model
+(`src/pi/viewer/tui/model.ts`) backs the `WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
+
+> The earlier in-browser graph viewer (`/weave-view` in a browser) has been retired and is being rebuilt on pixi.js; until then
+> `/weave-view` opens the in-terminal explorer.
+
+On session start, pi-weave detects the repository you're in, checks whether `.okf` exists and is fresh, and says so in the status footer — a
+filled `●` marks weave as active (a deep scan spins it while running).
+
+**`/weave-scan deep`** is the opt-in, incremental deep pass: it refreshes the light index and then writes a short model summary per file to
+`.okf/repository/summaries/`, skipping files whose content hash is unchanged since their last summary. It costs tokens, so it never runs
+implicitly — and it runs in the background, so `/weave-scan-cancel` can stop it mid-flight.
 
 ## The formats (why everything is portable)
 
@@ -112,15 +96,13 @@ Repository index (`<repo>/.okf/`):
     └── structure.json  # languages, packages, modules, entry points
 ```
 
-The `.okf` index is **derived**: delete it, rescan, lose nothing. By default
-it's excluded from git locally (`.git/info/exclude`); committing it for team
-sharing is a deliberate opt-in.
+The `.okf` index is **derived**: delete it, rescan, lose nothing. By default it's excluded from git locally (`.git/info/exclude`);
+committing it for team sharing is a deliberate opt-in.
 
 ## For other agent harnesses
 
-The on-disk artifacts and `src/core` are harness-agnostic by design — Claude
-Code and opencode adapters are on the roadmap (docs/design.md §21), and the
-skills follow the [Agent Skills standard](https://agentskills.io/specification).
+The on-disk artifacts and `src/core` are harness-agnostic by design — Claude Code and opencode adapters are on the roadmap (docs/design.md
+§21), and the skills follow the [Agent Skills standard](https://agentskills.io/specification).
 
 ## Development
 
@@ -129,5 +111,4 @@ npm install
 npm run check     # typecheck + tests with coverage gate (≥95%)
 ```
 
-See [AGENTS.md](AGENTS.md) for contributor/agent rules and
-[docs/design.md](docs/design.md) for the full design.
+See [AGENTS.md](AGENTS.md) for contributor/agent rules and [docs/design.md](docs/design.md) for the full design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
   "type": "module",
   "sideEffects": false,
@@ -48,6 +48,8 @@
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "check": "npm run typecheck && npm run coverage",
+    "rewrap:md": "node scripts/rewrap-md.mjs",
+    "rewrap:md:check": "node scripts/rewrap-md.mjs --check",
     "prepublishOnly": "npm run check"
   },
   "peerDependencies": {

package/skills/weave-explore/SKILL.md

@@ -5,45 +5,34 @@ description: Explore a git repository through its pi-weave knowledge index (.okf
 
 # Weave Explore
 
-pi-weave keeps a **derived** knowledge index of the repository at
-`<repo>/.okf/`. Source code is the truth; the index is a rebuildable cache.
-Deleting `.okf` loses nothing — rescan to regenerate it.
+pi-weave keeps a **derived** knowledge index of the repository at `<repo>/.okf/`. Source code is the truth; the index is a rebuildable
+cache. Deleting `.okf` loses nothing — rescan to regenerate it.
 
 ## Tools
 
-In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see
-the assembled graph in the terminal, run `/weave-view tui` (Explore tree,
-Focus neighborhood, Health surface); `/weave-view` opens the browser viewer.
-In other harnesses, read the JSON documents under `.okf/` directly.
+In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see the assembled graph in the terminal, run `/weave-view tui` (Explore
+tree, Focus neighborhood, Health surface); `/weave-view` opens the browser viewer. In other harnesses, read the JSON documents under `.okf/`
+directly.
 
 ## Workflow
 
 1. **Check for an index**: `weave_repo` action=status.
-   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly
-     when the user asked to explore.
+   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly when the user asked to explore.
    - `stale` → scan again; the repository moved on.
    - `fresh` → read it: action=overview.
-2. **Start from the overview**: file counts, languages, packages, module
-   groupings, and likely entry points. This replaces dozens of `ls`/`find`
-   calls.
-3. **Descend progressively** (design §9): only open files in modules relevant
-   to the user's question. The index gives you the map; the code gives you
-   the terrain.
-4. **Read summaries before full files**: if the repo has been deep-scanned
-   (`.okf/repository/summaries/` exists), read the relevant sidecars first —
-   they tell you what a file does and its outward surface in 1–3 sentences,
-   so you can decide whether to open the full file at all.
-5. **Answer with structure**: name modules and packages by their indexed
-   paths so the user can jump straight to them.
+2. **Start from the overview**: file counts, languages, packages, module groupings, and likely entry points. This replaces dozens of
+   `ls`/`find` calls.
+3. **Descend progressively** (design §9): only open files in modules relevant to the user's question. The index gives you the map; the code
+   gives you the terrain.
+4. **Read summaries before full files**: if the repo has been deep-scanned (`.okf/repository/summaries/` exists), read the relevant sidecars
+   first — they tell you what a file does and its outward surface in 1–3 sentences, so you can decide whether to open the full file at all.
+5. **Answer with structure**: name modules and packages by their indexed paths so the user can jump straight to them.
 
 ## Deep summaries
 
-`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one
-sidecar per file, written by the session model. It is **opt-in and
-incremental**: it never runs implicitly, and it only re-summarizes files
-whose content hash changed since their last summary. If summaries are
-missing or stale, offer `/weave-scan deep` to create or refresh them before
-diving into full files.
+`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one sidecar per file, written by the session model. It is **opt-in
+and incremental**: it never runs implicitly, and it only re-summarizes files whose content hash changed since their last summary. If
+summaries are missing or stale, offer `/weave-scan deep` to create or refresh them before diving into full files.
 
 ## On-disk layout
 
@@ -59,6 +48,5 @@ diving into full files.
 
 ## Trust model
 
-Everything in `.okf` is machine-generated (`source: generated`). If the user
-corrects an interpretation, that correction belongs in the vault (see the
-`weave-notepad` skill) as human knowledge, not in the derived index.
+Everything in `.okf` is machine-generated (`source: generated`). If the user corrects an interpretation, that correction belongs in the
+vault (see the `weave-notepad` skill) as human knowledge, not in the derived index.

package/skills/weave-notepad/SKILL.md

@@ -5,21 +5,17 @@ description: "Take and retrieve durable notes in the pi-weave vault. Use when th
 
 # Weave Notepad
 
-The pi-weave vault is the user's long-term memory: plain Markdown notes with
-front matter under `~/.okf/notes/`. It is shared with the human — anything
-you write here, they can read and edit, and vice versa.
+The pi-weave vault is the user's long-term memory: plain Markdown notes with front matter under `~/.okf/notes/`. It is shared with the human
+— anything you write here, they can read and edit, and vice versa.
 
 ## Tools
 
-In pi, use the `weave_note` tool. In other harnesses (or when the tool is not
-available), operate on the files directly:
+In pi, use the `weave_note` tool. In other harnesses (or when the tool is not available), operate on the files directly:
 
 - **Notes** live at `~/.okf/notes/<slug>.md` (vault root overridable via `PI_WEAVE_VAULT`).
-- Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601),
-  `tags: [..]`, and `source: human | agent | generated`.
-- `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`.
-  `finalize` restructures the body *above* the `## Raw` tail and preserves
-  the tail verbatim.
+- Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601), `tags: [..]`, and `source: human | agent | generated`.
+- `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`. `finalize` restructures the body *above* the `## Raw` tail and
+  preserves the tail verbatim.
 
 ## Raw Tail Format
 
@@ -41,49 +37,56 @@ Every note maintains a verbatim, append-only raw section at the bottom separated
 
 ### How to capture and append raw input
 
-1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line. Verbatim user input preserved here. -->`.
+1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line.
+   Verbatim user input preserved here. -->`.
 2. **Code Blocks for Verbatim Input**: Always wrap verbatim user lines inside code blocks (triple backticks).
 3. **Date and Time on Appends**: When appending subsequent snippets, prepend each snippet with: `<!-- appended YYYY-MM-DD HH:MM -->`.
 4. **Finalization (`finalize`)**:
    - `finalize` replaces or structures content only above the `---` and `## Raw` section.
    - The `## Raw` block and all verbatim code blocks are never modified or removed.
 
+## Dictation mode (continuous compile)
+
+During live dictation / interview note-taking (see the skill description), Pi does **not** wait until the end to organize the note. Every
+interactive append is immediately compiled into the body:
+
+1. **Append the raw words verbatim** to the `## Raw` tail as usual (a dated `<!-- appended YYYY-MM-DD HH:MM -->` code block).
+2. **Then immediately finalize** (`weave_note` action=finalize): rewrite the body *above* the `## Raw` tail — front-loaded summary,
+   sections, decisions, questions, tasks, entities, links — so the compiled document reflects everything said so far.
+3. **Never rewrite or remove the `## Raw` tail.** It stays append-only and verbatim; only the body above it changes.
+
+The result is a continuously-updated compiled document that stays current throughout the session — not just a raw tail that gets organized
+once at the end.
+
 ## When to take a note
 
-Create a note **only when the user explicitly asks** for one to exist:
-"start a note on X", "add to the X note", "remember this", "jot that down".
-Never promote conversation into a note on your own initiative — capture is
-explicit by design.
+Create a note **only when the user explicitly asks** for one to exist: "start a note on X", "add to the X note", "remember this", "jot that
+down". Never promote conversation into a note on your own initiative — capture is explicit by design.
 
 ## When NOT to take a note
 
-- Anything derivable from the repository itself (that knowledge belongs to
-  the `.okf` index, not the vault).
+- Anything derivable from the repository itself (that knowledge belongs to the `.okf` index, not the vault).
 - Session-scratch information (in-progress task state).
 - Secrets, credentials, or anything the user hasn't confirmed is safe to persist.
 
 ## How to write a good note
 
-1. **Search first** (`weave_note` action=search): if a note exists, `append`
-   to it rather than creating a duplicate.
+1. **Search first** (`weave_note` action=search): if a note exists, `append` to it rather than creating a duplicate.
 2. Title: short noun phrase ("Auth boundary decision", not "Notes").
-3. **Scribble in, verbatim.** When the user is dictating, append their words
-   to the note as rough, verbatim scribbles — no silent rewording. Keep them
-   under the `## Raw` tail format at the end of the note.
-4. **Finalize on request.** When the user says "finalize this" / "clean this
-   up", restructure the body *above* the raw tail: front-loaded summary,
-   sections, entities, links. Use `weave_note` action=finalize (or edit the
-   file directly in other harnesses). Move nothing out of `## Raw` — it
-   is append-only and never rewritten.
-5. Tags: 1–4 lowercase tags; reuse existing tags when possible.
-6. Provenance: notes the user scribbled stay `source: human` (finalization is
-   editorial, not authorship) — pass `source: "human"` to `add` for
-   user-scribbled notes. Notes you draft from scratch are `source: agent`
-   (the default). Never overwrite a `source: human` note's meaning; append
-   with a dated "Agent addendum" section instead.
+3. **Scribble in, verbatim.** When the user is dictating, append their words to the note as rough, verbatim scribbles — no silent rewording.
+   Keep them under the `## Raw` tail format at the end of the note.
+4. **Compile continuously during dictation.** After *every* interactive append in dictation mode, immediately finalize the body *above* the
+   raw tail so the compiled doc stays current (see [Dictation mode](#dictation-mode-continuous-compile)). Outside dictation mode,
+   compilation stays on request.
+5. **Finalize on request.** When the user says "finalize this" / "clean this up", restructure the body *above* the raw tail: front-loaded
+   summary, sections, entities, links. Use `weave_note` action=finalize (or edit the file directly in other harnesses). Move nothing out of
+   `## Raw` — it is append-only and never rewritten.
+6. Tags: 1–4 lowercase tags; reuse existing tags when possible.
+7. Provenance: notes the user scribbled stay `source: human` (finalization is editorial, not authorship) — pass `source: "human"` to `add`
+   for user-scribbled notes. Notes you draft from scratch are `source: agent` (the default). Never overwrite a `source: human` note's
+   meaning; append with a dated "Agent addendum" section instead.
 
 ## Retrieving knowledge
 
-Use `weave_note` action=search with the user's key terms, then `get` the best
-hits. When a note and the repository index disagree, trust the repository for
-facts about code and flag the discrepancy — the note may be stale intent.
+Use `weave_note` action=search with the user's key terms, then `get` the best hits. When a note and the repository index disagree, trust the
+repository for facts about code and flag the discrepancy — the note may be stale intent.

package/src/pi/index.ts

@@ -12,8 +12,6 @@ import {
 import { registerNoteTool } from "./tools/noteTool";
 import { registerRepoTool } from "./tools/repoTool";
 import { deepScanRepository, formatDeepScanResult } from "./summarize";
-import { openInBrowser } from "./viewer/browser";
-import { startViewer, type ViewerServer } from "./viewer/server";
 import { runWeaveViewTui } from "./viewer/tui/run";
 
 /**
@@ -29,9 +27,9 @@ export default function piWeave(pi: ExtensionAPI): void {
   registerNoteTool(pi);
   registerRepoTool(pi);
 
-  // Session-scoped viewer: lazy start on first /weave-view, never from the
-  // factory (extension rules); idempotent stop on session_shutdown.
-  let viewer: ViewerServer | null = null;
+  // /weave-view is the in-terminal explorer (the old browser viewer was
+  // retired for a pixi.js rewrite); it holds no session resources, so there
+  // is no per-session lifecycle to tear down.
   let lastCtx: ExtensionContext | ExtensionCommandContext | null = null;
   let lastStatusText: string | undefined = undefined;
   let isActive = false;
@@ -60,9 +58,7 @@ export default function piWeave(pi: ExtensionAPI): void {
   }
 
   pi.on("session_shutdown", async () => {
-    const server = viewer;
-    viewer = null;
-    await server?.stop();
+    // The TUI explorer owns no session-scoped resources; nothing to stop.
   });
 
   pi.on("agent_start", async (_event, ctx) => {
@@ -101,20 +97,14 @@ export default function piWeave(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("weave-view", {
-    description: "Open the local knowledge-graph viewer in your browser (vault + repository); '/weave-view tui' explores in-terminal",
+    description: "Open the in-terminal knowledge-graph explorer (vault + repository); reads from disk live",
     handler: async (args, ctx) => {
       const arg = args.trim().toLowerCase();
-      if (arg === "tui") {
-        await runWeaveViewTui(ctx);
-        return;
-      }
-      if (arg !== "") {
+      if (arg !== "" && arg !== "tui") {
         ctx.ui.notify("usage: /weave-view [tui]", "warning");
         return;
       }
-      viewer ??= await startViewer({ cwd: ctx.cwd });
-      ctx.ui.notify(`pi-weave viewer: ${viewer.url} (reads from disk live; refresh the page any time)`, "info");
-      await openInBrowser(pi, ctx, viewer.url);
+      await runWeaveViewTui(ctx);
     },
   });
 

package/src/pi/viewer/tui/bodyStore.ts

@@ -0,0 +1,98 @@
+/**
+ * BodyStore — shared note/.okf body cache (weave-view-tui-v2 §6, §9.1).
+ *
+ * The v1 WeaveExplorer cached bodies in private maps. v2 lifts that cache into
+ * a per-session store so every pane (e.g. two Detail panes reading the same
+ * note) shares one fetch per node id. Behavior is identical to v1's
+ * per-explorer cache: a body load is kicked off once per id, in-flight loads
+ * are deduped, and a refresh busts the cache so the next read re-fetches.
+ *
+ * The store is harness-free (takes injected loaders + an optional
+ * onChange callback), so it is unit-tested with fake loaders exactly like
+ * v1's body tests.
+ */
+
+import type { ViewNote } from "../../../core/graph/current";
+
+/** The body loaders a BodyStore is bound to (bound to vault/cwd by run.ts). */
+export interface BodyLoaders {
+  loadNote: (slug: string) => Promise<ViewNote | null>;
+  loadOkf: (rel: string) => Promise<{ path: string; body: string } | null>;
+}
+
+export interface BodyStoreOptions {
+  loaders: BodyLoaders;
+  /** Invoked (no args) when an async load resolves so the owner can re-render. */
+  onChange?: () => void;
+}
+
+/**
+ * A cache+dedup keyed by node id. `get` never throws and never double-loads.
+ *
+ * - `null` body = the node exists but has no loadable body (or it loaded to
+ *   null); the pane renders nothing for it.
+ * - `undefined` = not yet requested (the pane shows a placeholder and asks the
+ *   store to load, mirroring v1's `bodyLinesFor`).
+ * - `isLoading(id)` = an in-flight request is outstanding (pane shows "loading").
+ */
+export class BodyStore {
+  private readonly loaders: BodyLoaders;
+  private readonly onChange: (() => void) | undefined;
+  private cache = new Map<string, string | null>();
+  private loading = new Set<string>();
+
+  constructor(opts: BodyStoreOptions) {
+    this.loaders = opts.loaders;
+    this.onChange = opts.onChange;
+  }
+
+  /** True when the id is mid-load. */
+  isLoading(id: string): boolean {
+    return this.loading.has(id);
+  }
+
+  /** Cached body for the id, or undefined when not yet requested. */
+  get(id: string): string | null | undefined {
+    return this.cache.get(id);
+  }
+
+  /** True once a body has been requested for the id (cached or failed). */
+  has(id: string): boolean {
+    return this.cache.has(id);
+  }
+
+  /**
+   * Kick off a load for `id` if not already requested/in-flight. Returns true
+   * when a load was started (so the caller can show a placeholder). The load
+   * uses `kind` (note/file) to pick the loader and `ref` (slug/rel path).
+   */
+  load(id: string, kind: "note" | "file", ref: string | undefined): boolean {
+    if (ref === undefined) return false;
+    if (this.cache.has(id) || this.loading.has(id)) return false;
+    this.loading.add(id);
+    if (kind === "note") {
+      void this.loaders
+        .loadNote(ref)
+        .then((note) => this.finish(id, note?.body ?? null))
+        .catch(() => this.finish(id, null));
+    } else {
+      void this.loaders
+        .loadOkf(ref)
+        .then((file) => this.finish(id, file?.body ?? null))
+        .catch(() => this.finish(id, null));
+    }
+    return true;
+  }
+
+  /** Drop all cached bodies and in-flight markers (the `r` refresh). */
+  clear(): void {
+    this.cache.clear();
+    this.loading.clear();
+  }
+
+  private finish(id: string, body: string | null): void {
+    this.cache.set(id, body);
+    this.loading.delete(id);
+    this.onChange?.();
+  }
+}

package/src/pi/viewer/tui/branding.ts

@@ -0,0 +1,154 @@
+/**
+ * branding.ts — weave-view TUI logo & wordmark tiers (weave-view-tui-v2 §5).
+ *
+ * Renders the brand as a small, casual in-bar mark. Three tiers, auto-selected
+ * once per session from terminal capability and cached:
+ *
+ *   1. "kitty"   — the real raster logo via pi-tui's `Image` component (a small
+ *                  ~2×2-cell favicon). The raw JPG is bundled and base64'd once.
+ *   2. "glyph"   — a tiny curated Unicode glyph derived from the logo silhouette.
+ *   3. "plain"   — `🧵` + wordmark, forced by PI_WEAVE_TUI_PLAIN.
+ *
+ * The line-art/unicode constants contain no ESC by construction (decision 1:
+ * the representation fallback is a curated constant, never generated at runtime).
+ */
+
+import { detectCapabilities, getCapabilities, Image, type Component } from "@earendil-works/pi-tui";
+import type { ThemeSlot } from "./theme";
+
+/** Logo render tier. */
+export type LogoTier = "kitty" | "glyph" | "plain";
+
+/** A tiny Unicode mark derived from the logo silhouette (decision 1 fallback). */
+export const MARK_GLYPH = "◈";
+/** Absolute last-resort mark (also the forced plain tier). */
+export const PLAIN_MARK = "🧵";
+/** The wordmark shown after the mark. */
+export const WORDMARK = "weave view";
+
+/** Env var that forces the plain tier. */
+export const PLAIN_ENV = "PI_WEAVE_TUI_PLAIN";
+
+/** MIME of the bundled raster logo asset (downscaled JPEG of the logo). */
+export const LOGO_MIME = "image/jpeg";
+
+/**
+ * Bundled downscaled raster copy of `docs/pi-weave-logo.jpg` (32×32, ~1.3 KB).
+ * Decision 1 (§15): ship a small raster copy and embed it via pi-tui's `Image`
+ * (Kitty graphics) as a small ~2×2-cell favicon in the header strip — a casual
+ * in-bar mark, not a hero splash. Stored base64 so the render path needs no
+ * fs/path resolution and the asset is trivially unit-testable.
+ */
+export const LOGO_B64 =
+  "/9j/4AAQSkZJRgABAQAASABIAAD/4QDORXhpZgAATU0AKgAAAAgABgESAAMAAAABAAEAAAEaAAUAAAABAAAAVgEbAAUAAAABAAAAXgEoAAMAAAABAAIAAAExAAIAAAAVAAAAZodpAAQAAAABAAAAfAAAAAAAAABIAAAAAQAAAEgAAAABUGl4ZWxtYXRvciBQcm8gMi4xLjMAAAAEkAQAAgAAABQAAACyoAEAAwAAAAEAAQAAoAIABAAAAAEAAAAgoAMABAAAAAEAAAAgAAAAADIwMjY6MDg6MjIgMTk6NTY6MjIA/+0AZFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAsHAFaAAMbJUccAgAAAgACHAI+AAgyMDI2MDgyMhwCPwALMTk1NjIyKzAwMDA4QklNBCUAAAAAABBB7D4+CxrdyaRylkhoEmIW/8AAEQgAIAAgAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAAAAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEHYXETIjKBCBRCkaGxwQkjM1LwFWJy0QoWJDThJfEXGBkaJicoKSo1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoKDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uLj5OXm5+jp6vLz9PX29/j5+v/bAEMAAgICAgICAwICAwUDAwMFBgUFBQUGCAYGBgYGCAoICAgICAgKCgoKCgoKCgwMDAwMDA4ODg4ODw8PDw8PDw8PD//bAEMBAgICBAQEBwQEBxALCQsQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEP/dAAQAAv/aAAwDAQACEQMRAD8A/E8Lk4rQsocXcD46SIf/AB4VDbpvYDua95+HfhtZtHn8QpBbXEdvKyM00iKW2RtKY4Vcjc+xGY45wAByQD62FwzqO17Luc0pWPC7yHNzM2Orsf1NUGXBxXu/xH8O/Y7Cy114baCG9m8oNBIrbCYlmCTKmdr7JEbHJwcH5gQPEZ02sR6UsThnTdr3XcIyuf/Q/GHT/JkcQzbQpO7Lccjtn3r0Dwv/AG1fMdH0e+e1e+kRTaEM4uZwTtBXhSRk7c8YOO/PlwJByK14dZvI7dbXcDEpJAKjv79ccetezQxfLHlZw1acn8L1PTPE+nanZpb2Wr6i99JBkw2gV4xbzSk8KuGA3BckgYKjGQMVzPjG70+ygh8LaXFZSQWshuGurdd8kkkqDKGY5YqgABUfKH3ECsW48U6vcWs1k02IbjbvUKBnb0AOMgdsA4xxXOE55oxGJ5lZDjRVk5atH//Z";
+
+/** Terminal capability surface branding probes. */
+export interface BrandCapabilities {
+  /** Kitty graphics protocol available. */
+  kitty: boolean;
+}
+
+/** Pure tier selection; exported for direct unit testing. */
+export function logoTierFor(caps: BrandCapabilities, forcePlain: boolean): LogoTier {
+  if (forcePlain) return "plain";
+  if (caps.kitty) return "kitty";
+  return "glyph";
+}
+
+/**
+ * Resolve the environment (PI_WEAVE_TUI_PLAIN) to a plain flag. Exported as a
+ * small pure function so the env read is testable in isolation.
+ */
+export function plainEnv(env: Record<string, string | undefined> = process.env): boolean {
+  const v = env[PLAIN_ENV];
+  return v !== undefined && v !== "" && v !== "0";
+}
+
+// Session-level probe cache (probed once, reused for the whole session §5.1).
+let cachedTier: LogoTier | null = null;
+let cachedCaps: BrandCapabilities | null = null;
+
+/**
+ * Return the session-cached capabilities (probed once). The probe runs at most
+ * once per process; subsequent calls reuse the cache. `getCaps` is injectable
+ * for tests (defaults to a live kitty probe). Never throws.
+ */
+export function probeGraphics(getCaps: () => BrandCapabilities): BrandCapabilities {
+  if (cachedCaps) return cachedCaps;
+  try {
+    cachedCaps = getCaps();
+  } catch {
+    cachedCaps = { kitty: false };
+  }
+  return cachedCaps;
+}
+
+/**
+ * Resolve the session logo tier, probing terminal capability once and caching
+ * for the process. `env` is injectable for tests.
+ */
+export function logoTier(env: Record<string, string | undefined> = process.env): LogoTier {
+  if (cachedTier) return cachedTier;
+  const caps = probeGraphics(() => getBrandCapabilities());
+  cachedTier = logoTierFor(caps, plainEnv(env));
+  return cachedTier;
+}
+
+/** Reset the session probe cache (test seam). */
+export function resetBrandCache(): void {
+  cachedTier = null;
+  cachedCaps = null;
+}
+
+/** A live kitty-capability probe backed by pi-tui's terminal capability query. */
+export function getBrandCapabilities(): BrandCapabilities {
+  return { kitty: detectCapabilities().images === "kitty" };
+}
+
+/**
+ * The mark rendered as a single header line (≤ width). This is the string the
+ * header strip / empty state embed. For the kitty tier the mark glyph is used
+ * in the text strip; the real raster is emitted via `logoImage()` when a kitty
+ * surface is available.
+ */
+export function renderMark(tier: LogoTier, theme: { fg: (slot: ThemeSlot, text: string) => string }, width: number): string {
+  let mark: string;
+  if (tier === "plain") {
+    mark = theme.fg("muted", PLAIN_MARK);
+  } else {
+    // kitty and glyph tiers share the curated glyph in the text strip.
+    mark = theme.fg("accent", MARK_GLYPH);
+  }
+  return mark.slice(0, Math.max(1, width));
+}
+
+/**
+ * A small pi-tui `Image` component for the kitty tier (decision 1 favicon).
+ * Takes the base64 JPG + mime; renders at ~2×2 cells. Returns a component that
+ * emits the Kitty sequence when the terminal supports it, else a text fallback.
+ */
+export function logoImage(
+  base64Data: string,
+  mimeType: string,
+  theme: { fg: (slot: ThemeSlot, text: string) => string },
+): Component {
+  return new Image(base64Data, mimeType, { fallbackColor: (t) => theme.fg("text", t) }, {
+    maxWidthCells: 2,
+    maxHeightCells: 2,
+  });
+}
+
+/**
+ * Build the bundled kitty raster logo `Image` (decision 1 favicon). Returns a
+ * component only when the terminal supports the Kitty graphics protocol;
+ * `null` otherwise so the caller keeps the one-line glyph header. The render
+ * path splices this component's lines onto their own row(s) — never inlined
+ * into a styled text line. The base64 asset is a compile-time constant, so the
+ * only fallback needed is the Kitty gate (no fs/path reads at runtime).
+ */
+export function bundledLogoImage(
+  theme: { fg: (slot: ThemeSlot, text: string) => string },
+): Component | null {
+  if (getCapabilities().images === "kitty") return logoImage(LOGO_B64, LOGO_MIME, theme);
+  return null;
+}