Architecture ralph: volatility-based decomposition loop

README.md

@@ -196,20 +196,27 @@ pnpm monorepo:
 | `packages/common/`                   | [oRPC](https://orpc.dev/) contract + [Zod](https://zod.dev/) schemas + cell descriptors                                                                               |
 | `packages/surface/`                  | Reactive state framework — typed `Cell<T>`, `Collection<K,T>`, `Stream<I,T>`, `Event<I,T>` over oRPC streams; SolidJS hooks (`useCell`, `useCollection`, `useStream`, `useEvent`)               |
 | `packages/solid-pierre/`             | Solid-native wrappers around [`@pierre/trees`](https://www.npmjs.com/package/@pierre/trees) and [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs); encapsulates Pierre's imperative mount/render lifecycle behind `<FileTree>` and `<CodeView>` with required `onError` props. `<CodeView>` (Pierre's 1.2.x advanced-mode viewport) hosts files and/or diffs in one virtualized scroll — windowed-rendering is unconditional, so single-file callers ride the same path as future multi-file ones |
+| `packages/solid-xterm/`              | Solid-native pieces of xterm.js lifecycle. `createXtermWebgl` encapsulates the WebglAddon dance + Chrome's per-tab GPU context budget (via explicit `WEBGL_lose_context.loseContext()` before `addon.dispose()`); `attachXtermStyleSync` reactively syncs `term.options.theme/fontSize`; `createScrollLock` freezes incoming writes when the user scrolls up and flushes on return-to-bottom. Three encapsulated axes, one consumer (`client/src/terminal/Terminal.tsx`) — the same single-in-tree-consumer bar Surface and `solid-pierre` cleared |
+| `packages/canvas-layout/`            | Pure 2D layout for a tiled-workspace canvas. `arrangeRepoIslands` packs same-bucket tiles into square-ish clusters and packs the clusters across the canvas; `repackBucket` re-lays one bucket on tile-create; `findFreeTilePosition` cascade-places a new tile at a viewport-relative free spot. No SolidJS, no DOM, no Kolu domain types — every function is a deterministic projection from `Rect[]` to `Rect[]`. Single consumer (`client/src/canvas/`) |
+| `packages/solid-canvas-viewport/`    | Solid-native pan/zoom 2D canvas viewport. Wheel-toward-cursor zoom, click/middle/shift-drag pan, animated `centerOnRect` with `prefers-reduced-motion`, snap-to-grid. Decomposed by volatility: gesture input (`gestures.ts`), transform math (`transforms.ts` + `animatedPan.ts`), CSS output (`coordinates.ts` — `tileTransformCSS`). `useCanvasViewport()` orchestrates the three behind one `CanvasViewport` interface. Single consumer (`client/src/canvas/`) |
+| `packages/solid-recorder/`           | Solid-native browser tab + mic (+ optional webcam) recording. `useRecorder()` owns the idle→setup→recording→paused state machine, elapsed clock, device enumeration, and the WebM duration patch. `mic` / `webcam` are singleton domain state. `LevelMeter` + `WebcamOverlay` are the framework-supplied visual pieces. Notification surface (`onError` / `onSuccess` / `onWarning`) is injectable via `configureRecorderNotifications` — Kolu wires `solid-sonner` through it at app init. Single consumer (`client/src/recorder/`) |
+| `packages/solid-anchored-popover/`   | Minimal SolidJS popover-positioning primitive. `useAnchoredPopover({ triggerRef, open, onDismiss, anchor })` returns `{ panelRef, panelStyle }` and owns viewport-clamped positioning + outside-click + Escape dismiss. Six in-tree Kolu consumers (option menu, settings popover, record popover, mode-chip picker, activity-window chip, PR-unavailable tooltip) — the highest-reuse primitive Kolu had |
+| `packages/browser-clipboard/`        | Clipboard write that survives non-secure contexts. `navigator.clipboard` is exposed only in `https://…` / `localhost` / `127.0.0.1`; plain `http://` to a LAN address gets `navigator.clipboard === undefined`. `writeTextToClipboard(text)` tries the modern API and falls back to `document.execCommand("copy")` against a synthetic off-screen `<textarea>` ([caniuse 100/100](https://caniuse.com/mdn-api_document_execcommand_copy)). Separate `./xterm` entry point exports `SafeClipboardProvider` implementing xterm.js's `IClipboardProvider` so OSC 52 writes survive plain HTTP |
+| `packages/file-line-ref/`            | Source-reference parsing in `path:line[-end]` shape (VS Code's `:e file:N`, Vim, GitHub URL fragments, Linear). `parseLineRefs(text)` scans embedded references, `formatLineRef` renders, `resolveLineRefPath` resolves a parsed `path` against a worktree's file list considering absolute / cwd-relative / basename-only inputs |
 | `packages/artifact-sdk/`             | Self-contained comments-on-files toolkit. Three exports: `./core` (pure W3C TextQuoteSelector functions used by both runtimes), `./client` (parent-side iframe ↔ parent bridge + core re-exports), `./server` (one-line `mountArtifactSdk(app, ...)` that wires the SDK bundle route and an HTML-decoration middleware — esbuild bundles the in-iframe script at server startup, hash-keyed for cache busting). The host server never imports HTML rewriting logic |
 | `packages/server/`                   | [Hono](https://hono.dev/) + `kolu-pty` for terminal lifecycle                                                                                                          |
 | `packages/integrations/pty/`         | Generic PTY primitives — [node-pty](https://github.com/microsoft/node-pty) + [@xterm/headless](https://www.npmjs.com/package/@xterm/headless) wrapped behind a `PtyHandle` with OSC-driven cwd/title/preexec callbacks; only kolu-* dep is `kolu-shared` (Logger type) |
 | `packages/client/`                   | [SolidJS](https://www.solidjs.com/) + [xterm.js](https://xtermjs.org/) + [Tailwind CSS v4](https://tailwindcss.com/)                                                  |
 | `packages/integrations/claude-code/` | Claude Code detection — JSONL transcript tailing + Claude Agent SDK; exports a `claudeCodeProvider` `AgentProvider`                                                   |
-| `packages/integrations/anyagent/`    | Agent-agnostic shared contract (`AgentProvider` interface, `agentInfoEqual`), types (Logger, TaskProgress), and agent CLI parsing                                     |
+| `packages/integrations/anyagent/`    | `@kolu/anyagent` — agent-agnostic shared contract (`AgentProvider` interface, `agentInfoEqual`), types (Logger, TaskProgress), and agent CLI parsing                  |
 | `packages/integrations/codex/`       | Codex detection — reads the highest-numbered `~/.codex/state_<N>.sqlite` for thread metadata and tails the matched rollout JSONL for state; exports a `codexProvider` |
 | `packages/integrations/opencode/`    | OpenCode detection — reads OpenCode's SQLite database via Node's built-in `node:sqlite`; exports an `opencodeProvider` `AgentProvider`                                |
 | `packages/integrations/git/`         | Pure git operations — `simple-git` wrapper: repo resolution, worktree lifecycle, diff review, path security; schemas re-exported by `kolu-common`                     |
 | `packages/integrations/github/`      | GitHub PR schemas + pure helpers (`deriveCheckStatus`, `classifyGhError`, `prResultEqual`); server wraps with `gh pr view` spawn via `KOLU_GH_BIN`                    |
-| `packages/integrations/io/`          | Filesystem & I/O primitives — refcounted shared `fs.watch` keyed by directory (`createDirFilenameWatcher`); zero `kolu-*` deps so any package can adopt without coupling |
+| `packages/integrations/io/`          | `@kolu/dir-watch` — refcounted shared `fs.watch` keyed by directory (`createDirFilenameWatcher`). Parent-dir target survives editor temp+rename atomicity; refcount singleton per resolved dir; idempotent unsubscribe with debounce-timer teardown. Zero `kolu-*` deps |
 | `packages/transcript-core/`          | Vendor-neutral transcript IR (`Transcript`, `TranscriptEvent`, typed `ToolInput` union) + structural transforms; per-agent loaders normalize into this shape          |
 | `packages/transcript-html/`          | Static-export renderer — `marked` for prose, [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs) SSR for shiki-tokenized code/diffs, [Preact](https://preactjs.com/) JSX for chrome; emits one self-contained `.html` |
-| `packages/terminal-themes/`          | Terminal color scheme catalog + perceptual-distance picker — themes checked-in as JSON                                                                                |
+| `packages/terminal-themes/`          | `@kolu/terminal-themes` — terminal color scheme catalog + perceptual-distance picker. Themes parsed from [iTerm2-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes) (Ghostty format) and ship checked-in as `themes.json`. `pickTheme` minimizes perceptual background distance against peers so multi-terminal tiles read as visually distinct |
 | `packages/memorable-names/`          | ADJ-NOUN random name generator — word lists checked-in as JSON                                                                                                        |
 
 ### Communication

default.nix

@@ -21,7 +21,14 @@ let
       ./tsconfig.base.json
       ./packages/surface
       ./packages/surface-nix-host
+      ./packages/browser-clipboard
+      ./packages/canvas-layout
+      ./packages/file-line-ref
+      ./packages/solid-anchored-popover
+      ./packages/solid-canvas-viewport
       ./packages/solid-pierre
+      ./packages/solid-recorder
+      ./packages/solid-xterm
       ./packages/common
       ./packages/integrations
       ./packages/nonempty