@vibefield/rosetta-room 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# @vibefield/rosetta-room
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+rosetta's History room as a package: the projects, sessions and worktree
+columns, the summary panels and charts, and the transcript with its folds,
+behind injected ports. The room dials nothing. A host hands it a catalog, a
+way to open one session's body, an asset source and, on a desktop, a host
+port; each host writes its own adapters. rosetta's own app
+(`clients/app/renderer/src/host`) is the reference host.
+
+```sh
+npm install @vibefield/rosetta-room react@19 react-dom@19
+```
+
+```tsx
+import { HistoryRoom } from "@vibefield/rosetta-room";
+import "@vibefield/rosetta-room/styles/room.css"; // after the host's --vf-* tokens
+
+<HistoryRoom catalog={catalog} sessions={sessions} assets={assets} host={host} />;
+```
+
+`@vibefield/rosetta-room/fixtures` renders the room with no daemon at all:
+`<HistoryRoom {...createDemoPorts()} />` (six projects, eleven sessions, a year
+of figures, two transcripts with images and web lines, all relative to now).
+
+## The ports (`src/ports.ts`)
+
+| Port | What the room asks | rosetta's app answers with |
+|---|---|---|
+| `CatalogPort` | `subscribeMeta` (runtimes, projects, every session row, live: one snapshot then mutations) · `status` → `CatalogStatus` · `projectStats(projectId, window)` → `ProjectStats` (per-day heat and per-session facts) · `usage` · `dayUsage` · `search(CatalogSearch)` · optional `onConnectionChange`, `unavailable` (the host's own words for why the index cannot answer), `boost` and `projectStatsBatch` (every listed project's figures in one ask; present, the room asks it once per refresh instead of `projectStats` per project) | its client's REST and `/ws/meta` (`catalogOver`) |
+| `SessionPort` | `open(sessionId)` → a `SessionClient` bound to that session (its live subscription, child threads and team members each open their own; entries, report work, commands, plans, file targets, stored members), or a promise of one; `close(sessionId)` | the one client for every session; close is nothing |
+| `AssetSource` | `imageAssetUrl(asset, variant)` → a URL, null, or a promise of either · `attachmentAssetUrl(asset)` → the attachment's address, for identity and can-open only | the daemon's own URLs |
+| `HostPort` (optional) | `homeDir` · `platform` · `openInBrowser(name, bytes, browserId?)` · optional `browsers()` · `favicon(site)` · optional `worktree: { open, gitFacts, fileAction, ports }` | the Electron bridge (`hostPortOver`) |
+
+- **The room opens a session at most once at a time and follows every `open`
+  with exactly one `close`**, when nothing in it reads that session any more.
+  A host that mints a credential per open mints one per session the reader is
+  looking at.
+- **A `RosettaClient` is a `SessionClient`** (checked at compile time). A host
+  whose daemon wants a per-session credential hands a client that carries it.
+- **An `<img src>` cannot carry a credential.** A host whose daemon wants one
+  fetches the bytes through a session's client and answers an object URL — a
+  promise while it fetches — and bounds and revokes what it made. The room asks
+  on every mount and every retry, so an evicted URL is asked for again, never
+  reused, and a source must not keep a failure. A null answer draws the
+  image's "could not load" face with Retry.
+- **`boost` is optional** because a grant never opens a write: only a host
+  holding the daemon's bearer offers it. Without it the index keeps its order.
+- **`browsers()`** returns installed browser ids, names and icon URLs. HTML
+  and SVG viewers show one launch icon per browser, refreshing when opened or
+  the window regains focus. The host owns executable discovery and launch;
+  the room sends back only an id and the exact displayed bytes. Hosts without
+  discovery retain their existing default-browser action.
+- **Without a host** the room states what a browser tab is: no worktree guest,
+  a globe for every site icon, no "open in browser". With a host but no
+  `worktree`, the guest stays closed.
+- **`worktree.ports`** is the engine's event stream: a generation starting or
+  failing, then its two transferred `MessagePort`s (tree and git). A host
+  replays what arrived before the room listened; the room is the sole
+  consumer.
+
+## What a host decides (`HistoryRoomProps`)
+
+Its host inputs (below), and: `surface` (`"paper"`, the default, paints the room's own ground and plate;
+`"host"` paints neither and turns the paper fades into frost over whatever the
+host paints) · `portalContainer` (where the dialogs and the search sheet
+portal; their sizes are percentages of what holds them) · `edgeInset`,
+`scrollFoot`, `floatingFoot` · `onSelect` (the selected session's id, native id,
+folder and the host's key when it gave one, on mount and on every change) · `storagePrefix` and `storage` ·
+`initialSummaryTab` · `unavailable` and `consent` (the host's words and its
+consent screen) · `emptyPrompt` (the empty transcript's sentence in the host's
+words; absent, the room's own, below) · `search` (the room's own strip and
+sheet, with the host owning the open state; absent, neither is drawn). The ref
+handle offers `openAt({ sessionId, timelineId? })` and `stepMatch(delta)`.
+
+**The search keys are the host's (RO-14).** The room binds no key of its own.
+The host's window opens the sheet and walks the matches: rosetta's app binds
+⌘K (Ctrl K off a Mac) and `/` to the sheet, and ⌘G and ⌘⇧G to the matches. So
+the host binds, and the room prints only the keys the host says it binds:
+
+| The host passes | The launcher prints | The empty transcript says |
+|---|---|---|
+| `search`, no `shortcut` | the room's own label, ⌘K (Ctrl K off a Mac) | "Pick a session — or press ⌘K to search, which is the front door." |
+| `search.shortcut: { label }` | `label`, as given | the same sentence with `label` |
+| `search.shortcut: null` (it binds no key) | no legend | "Pick a session." |
+| no `search` | no launcher | "Pick a session." |
+| `emptyPrompt`, beside any row above | as that row says | the host's sentence |
+
+`emptyPrompt` is a prop of the room, not of `search`, so a host that draws no
+room search (VibeField, whose search is its own Peek) can still name its own
+key there. A host that passes `search` binds ⌘G and ⌘⇧G (Ctrl G and Ctrl Shift
+G off a Mac) to the handle's `stepMatch(1)` and `stepMatch(-1)`, because the
+match stepper the sheet leaves in the transcript's head names those keys.
+
+## What a host may add (`RoomHostInputs`)
+
+Beyond its ports, a host may hand the room its own colours, marks, sections,
+acts, folders and filters (`src/host-inputs.ts`). The room DRAWS them in its
+own vocabulary and never interprets them: a host key rides back out
+untouched, a host mark is drawn where it is put, a host act is pressed. Every
+one is optional, and with none of them the room is exactly what rosetta's app
+shows — the reference host passes none. Ids are the room's own
+(`ProjectRow.id`, `SessionRow.id`), as the host's catalog handed them in.
+The callbacks are called while the room renders, so a host keeps them cheap.
+
+- **`projectTint(projectId)`** — the project's colour, any CSS colour. Absent,
+  or null for a project: the room's own dealt tint, which is then the only
+  one the room stores.
+- **`projectRow(projectId)`** → `{ marks?, line?, live? }` — a ledger row's
+  decorations: marks drawn at the start of its path line, a second line
+  under the path, and a live count (above zero, the time slot says "n live"
+  in the live ink). None is interactive: the row is one button.
+- **`projectSections`** (①) and **`sessionSections(projectId)`** (②) →
+  `RoomSection[]` — the list in sections, drawn in the order given. A section
+  names its rows (`ids`, in the host's order, or `order: "room"` for the
+  room's), or names none and takes every row no other section names, in the
+  room's order (② with its day heads). A row named twice is drawn in the
+  first; when every section names its rows, the rest are not drawn, which is
+  how a host filters. `title` draws a head in the list's own break; `fold`
+  draws a foot section as one line (its words, its count, its act, such as
+  "Show older") that opens in place, and opens by itself when it holds the
+  selected row. ②'s head counts what its sections draw.
+- **`sessionRow(session)`** → `{ hostKey?, id?, idTitle?, act?, reason? }` — a
+  session row's id slot drawn by the host (its mark and the folder, in the
+  id's face), its act (`RoomAct`: Resume, Jump to) or the reason where the
+  act would be, before the row's time; and the host's own key, which rides
+  the selection back out as `RoomSelection.hostKey`, untouched. A row with an
+  act is a box under one covering button (the selection, named as the row
+  always was) with the act above it, because a button cannot hold another;
+  pressing the act (or opening its rows) leaves the selection.
+- **`projectActs(projectId, { folder })`** → `RoomAct[]` — ②'s head acts,
+  drawn as the head's own icon buttons after the room's (one may be
+  `primary`, on the go fill); `folder` is the folder ③ shows, by the host's
+  key (`folders`, below). **`projectCard(projectId)`** — a card under ②'s
+  head, above its list. **`sessionActs(session)`** → `{ acts?, reason? }` —
+  ④'s head, for the session it names: acts as pills before the activity act,
+  or the reason as a caption after the range.
+- An act with a `menu` (`RoomMenu`: groups of rows, each with a mark, words,
+  a second line, an aside, a check, a step in) opens the room's popover rows
+  from it. They are drawn above the columns, in the room's root, anchored to
+  their control, flipped above it when there is more room there, and held
+  inside the room's box (no column clips them). Opened by a key they land on
+  the checked row, which wears the ring; opened by a pointer they take focus
+  with no ring until a key walks them. The arrow keys walk them, a choice or a
+  press outside or Escape closes them; past `filterAfter` rows a filter heads
+  them. They listen only while open (and to the window's resize and scroll,
+  to stay on their control).
+- **`folders(projectId)`** → `RoomFolders` — ③'s head becomes a dropdown of
+  the host's folders, by group, each keyed by the host (two machines spell a
+  path alike, so the check goes by key, never by path), with its mark in
+  front of the name. ③ shows the reader's pick while the session stays, else
+  the folder `of(session)` names for the selected session, else `initial`
+  (the usual place), else the folder at the room's own root — and tells the
+  host which through `onShow(key)`; `projectActs` hears it as `folder`. A
+  folder with `elsewhere` is never opened: ③ draws the host's honest state
+  in its place. `caption` replaces git's caption while it is shown.
+  `WorktreeList` is untouched. A folder's `act` (H4: "Not part of this
+  project") sits beside its row in the list, pressed, never a menu; → from
+  the row reaches it, ← comes back, and the list closes after it.
+- **`projectRow(projectId).act`** (H4) — an act at a ledger row's end,
+  before its time (pin, hide), or its rows. The row becomes the same box as
+  a session row with an act: one covering button (the selection), the act
+  above it.
+- **`projectRename(projectId)`** → `{ onRename(name), label? }` (H4) — ②'s
+  head name is the control: pressed, it becomes a field holding the name.
+  Enter commits the trimmed, changed, non-empty name; Escape or leaving the
+  field cancels. A rejected `onRename` keeps the field open and says why
+  under it ("Could not rename — <the error's words>"). The head names the
+  project as the host's catalog last said, until it says otherwise.
+- **`projectFilters`** (①) and **`sessionFilters(projectId)`** (②) →
+  `RoomFilter[]` — chips drawn as buttons in the room's chip pill, leading
+  the list's bar (① before the rank switch; ② gets a bar only when a project
+  has chips), each opening its `RoomMenu`. The host filters, through the
+  list's sections, and says what is chosen with the chip's words, `set` and
+  a checked row. The room's own search sheet keeps its native selects.
+- **`repositoryUrl(projectId)`** — the address ②'s repository act opens.
+  Undefined: the room's own reading of `git_repo`; null: no act.
+
+## The reader (`TranscriptReader`)
+
+One session's transcript, read-only, at a line: what a host shows before it
+opens the room there (VibeField's Peek). It takes the room's ports and an
+address, and draws the room's own document with nothing around it.
+
+```tsx
+<TranscriptReader {...ports} at={{ sessionId, timelineId, query }} />
+```
+
+- **It lands at `timelineId` and keeps the line marked**, and marks the words
+  of `query` in the prose (each word, or a phrase in quotes as one). The
+  address is read by value: a new session or line lands again, a re-render
+  with the same one does not.
+- **It is read-only.** No head band and no acts — no session-work launchers,
+  no day menu, no "Latest" pill, no dialog (a long message shows in full) —
+  no thread navigation, no key bound, and nothing written back to a room. A
+  delegated thread is read inside its root, as the room opens it.
+- **It asks only what reading needs:** one `subscribeMeta` while mounted, and
+  one `open`/`close` of the session it shows. No status, figures or search.
+- **The mark's look is the host's.** Three tokens on any element around the
+  reader: `--ah-match` (the wash under a matched word), `--ah-match-weight`,
+  and `--ah-match-line` (the matched line's edge, a prompt panel's ring).
+  Unset, they are the room's own neutral match — the sheet's
+  `--vf-fill-hover` wash at 500, a `--vf-text-tertiary` edge — and never the
+  select hue the room's landing ring wears for a moment.
+
+## What the package never does
+
+- **No fetch and no socket.** Every byte arrives through a port.
+- **No storage outside the prefix.** Four names — `search.recent`,
+  `tintSeq.v1`, `siteIcons.v1`, `transcript.fold.v2` — under `storagePrefix`
+  (default `ah.`) in the host's `storage` (default `localStorage`; `null` keeps
+  nothing).
+- **No window globals.** It reads and writes no custom property of `window`
+  and installs no message or key listener on the host's behalf. It reads
+  `matchMedia` and `devicePixelRatio`, listens to `focus` and
+  `visibilitychange` to refresh its clock, listens while one of its own
+  popovers is open, and re-measures its minimap on `resize`. External links
+  leave through the browser's own `target="_blank"` and `window.open`, which
+  the host's shell governs.
+- **No page styles.** Every rule is scoped to the room's root (`.ah-frame`)
+  and to the layers it portals (`.ah-layer`), at the specificity it had; the
+  page's resets and a global reduced-motion floor are the host's.
+
+## Styles and tokens
+
+The room reads the VibeField design kit's `--vf-*` tokens (the host defines
+them) and brings its own: `--ah-*` (`--ah-plate`, `--ah-scroll-foot`,
+`--ah-floating-foot`, `--ah-inset-*`, and the reader's match look
+`--ah-match`, `--ah-match-weight`, `--ah-match-line`, read with neutral
+fallbacks so a host sets them on any element around the room), `--tr-*`, and
+the project tint band `--tint-l`/`--tint-c`. What a host adds is styled in
+`styles/host-inputs.css`, whose every rule matches only an element drawn for
+a host input. The root carries `data-ah-surface`, and
+`data-ah-overlay` while one of its dialogs or the sheet is open, so a host can
+stop its own chrome (a drag region, say) under it.
+
+## Building against it
+
+The npm package ships ESM JavaScript, TypeScript declarations, and its stylesheets.
+Its three exports are the room, fixtures, and `styles/room.css`. React and React DOM
+are peers at `>=19 <20`; the host supplies one copy of each. Mille and Mille UI are
+registry dependencies, so installing Rosetta needs no sibling checkout.
+
+For development, run `npm ci` at the repository root, then `npm run build:packages`.
+`npm run typecheck -w @vibefield/rosetta-room` checks the room under `strict`,
+`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, and `verbatimModuleSyntax`.
+The workspace app aliases the room's source for live development and deduplicates
+React. `npm run check:packages` verifies the packed exports, declarations, and CSS
+in an independent consumer before release.

package/dist/HistoryRoom.d.ts

@@ -0,0 +1,98 @@
+import type { ReactNode } from "react";
+import type { RoomPorts } from "./ports.js";
+import type { RoomHostInputs } from "./host-inputs.js";
+import type { KeyValueStore } from "./lib/room-storage.js";
+import type { SummaryTab } from "./room-context.js";
+import type { SearchShortcut } from "./components/search/index.js";
+/** The room's own search: the strip's launcher and the sheet it opens. A host
+ * that offers search its own way (VibeField's Peek) leaves this out, and the
+ * room then draws neither. */
+export interface HistoryRoomSearch {
+    /** Whether the sheet is open. The host owns it, so its own keys can open it. */
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    /** The query the room opens with (rosetta's app reads `?q=`). */
+    readonly initialQuery?: string | undefined;
+    /** Drawn at the strip's end, after the launcher. */
+    readonly accessory?: ReactNode;
+    /** The key the host binds to open the sheet, as the room prints it (the
+     * room binds none itself — `open` is the host's). Absent: the room's own
+     * label for ⌘K (Ctrl K off a Mac), the key rosetta's app binds. A label:
+     * that label, printed as given. null: the host binds no key, so the
+     * launcher prints no legend and the empty transcript names none. */
+    readonly shortcut?: SearchShortcut;
+}
+export interface HistoryRoomProps extends RoomPorts, RoomHostInputs {
+    /** Who paints beneath the room. `paper` (the default): the room paints its
+     * own ground and plate, as rosetta's app shows it. `host`: the host paints
+     * its own surface beneath; the room paints neither, and its fades become
+     * frost over whatever the host painted. */
+    readonly surface?: "paper" | "host" | undefined;
+    /** Where the room's dialogs and its sheet are portalled (the host's frame,
+     * so its overlays anchor there); the document's body when absent. */
+    readonly portalContainer?: HTMLElement | null | undefined;
+    /** Every name the room keeps in storage goes under this prefix: recent
+     * searches, dealt project tints, the site-icon setting, the fold. Default
+     * `ah.`, which is where rosetta's app has always kept them. */
+    readonly storagePrefix?: string | undefined;
+    /** The store those names live in: the browser's localStorage when absent;
+     * null keeps nothing across runs. */
+    readonly storage?: KeyValueStore | null | undefined;
+    readonly search?: HistoryRoomSearch | undefined;
+    /** The chart the project panel opens on. */
+    readonly initialSummaryTab?: SummaryTab | undefined;
+    /** The host's words under "rosettad is not answering" when the catalog
+     * itself has none — rosetta's app says where it looked and how to start one. */
+    readonly unavailable?: ReactNode;
+    /** What the room shows while the index waits for consent to read anything.
+     * Absent: the room says it is waiting. */
+    readonly consent?: ReactNode;
+    /** The empty transcript's sentence, in the host's words (a host whose own
+     * search has its own key names it here). Absent: the room's own sentence,
+     * which names a key only when the launcher prints one — "Pick a session."
+     * with no `search` or with `search.shortcut` null. */
+    readonly emptyPrompt?: ReactNode;
+    /** The selected session, or null — on mount and on every change. */
+    readonly onSelect?: ((selection: RoomSelection | null) => void) | undefined;
+    /** Edges kept clear inside the room's frame for the host's chrome. */
+    readonly edgeInset?: RoomInset | undefined;
+    /** Scrollable space after every list's last row (`--ah-scroll-foot`), and
+     * where floating controls rest (`--ah-floating-foot`): CSS lengths. */
+    readonly scrollFoot?: string | undefined;
+    readonly floatingFoot?: string | undefined;
+}
+/** The session the reader has selected, as a host acts on it (Resume). */
+export interface RoomSelection {
+    readonly sessionId: string;
+    /** The agent's own id for the conversation: what a host resumes by. */
+    readonly nativeSessionId: string;
+    /** Where the session ran; null when the index does not know. */
+    readonly folder: string | null;
+    /** The host's own key for the session (`RoomSessionRow.hostKey`), passed
+     * through untouched. Absent when the host gives none. */
+    readonly hostKey?: string | undefined;
+}
+/** A place in the record: a session, and optionally one of its messages. */
+export interface RoomTarget {
+    readonly sessionId: string;
+    readonly timelineId?: string | null | undefined;
+}
+/** The room's edges kept clear for the host's own chrome, in pixels. */
+export type RoomInset = number | {
+    readonly top?: number | undefined;
+    readonly right?: number | undefined;
+    readonly bottom?: number | undefined;
+    readonly left?: number | undefined;
+};
+/** What a host may ask of a mounted room. */
+export interface HistoryRoomHandle {
+    /** Walk the landed session's search matches. False when there is nothing to
+     * walk, so the host's key can fall through. */
+    stepMatch(delta: 1 | -1): boolean;
+    /** Open a session — its thread, in its project — and land on one of its
+     * messages when given. A session the index has not delivered yet is opened
+     * when it arrives; one it does not have is said so in a receipt. */
+    openAt(target: RoomTarget): void;
+}
+/** The room. A host hands it its ports; everything inside reads them from context. */
+export declare const HistoryRoom: import("react").ForwardRefExoticComponent<HistoryRoomProps & import("react").RefAttributes<HistoryRoomHandle>>;