@vibefield/rosetta-room 0.0.0-stage → 0.1.0

package/dist/components/worktree/WorktreeColumn.js

@@ -0,0 +1,170 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Column ③ — the project's repository: its files, what git has not recorded
+// yet, and what it has.
+//
+// The design record draws these as two columns, a worktree beside a git
+// panel, each opening from a different head. They are one column here,
+// because they are three views of ONE object: this project's checkout. Two
+// columns made the reader hold that identity in their head — the same folder
+// named twice, in two heads, with two toggles — and cost 280px to say it. A
+// switch says it in a row the column already had.
+//
+// It is still a guest (H-3), and now the only one, so the record's original
+// single-subject rule applies again: below a 1360px frame it closes rather
+// than squeeze the transcript.
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useRoom } from "../../room-context.js";
+import { FileViewerDialog } from "../file-viewer/index.js";
+import { ConfirmDialog, EmptyState, SegmentedControl } from "../ui/index.js";
+import { changeShapeOf, CommitViewer, createGitFileSource, diffHandle, GitChanges, GitHistory, useGitRead, } from "../git/index.js";
+import { useGitFacts, useWorktreeConnection } from "./worktree-host.js";
+import { createWorktreeFileSource, handleFor, isOpenable } from "./worktree-file-source.js";
+import { WorktreeFileTree } from "./WorktreeFileTree.js";
+import { WorktreeHeader } from "./WorktreeHeader.js";
+import { WorktreeList } from "./WorktreeList.js";
+const TABS = [
+    { value: "files", label: "Files" },
+    { value: "changes", label: "Changes" },
+    { value: "history", label: "History" },
+];
+const readBranch = (client) => client.branch();
+const readStatus = (client) => client.status();
+const readLog = (client) => client.log();
+export function WorktreeColumn({ projectRoot, tint, homeDirectory, sessionPaths, currentTimestamp, onReceipt, requestError, onRetry, folders = null, }) {
+    const elsewhere = folders?.shown?.elsewhere;
+    const lifecycle = useWorktreeConnection();
+    const live = lifecycle.status === "ready" ? lifecycle.connection : null;
+    const engine = live?.engine ?? null;
+    // The engine follows the selection with a lag (kill, re-fork, walk), so the
+    // head names what the column is actually showing, never what was asked for.
+    const shownRoot = lifecycle.status === "ready"
+        ? lifecycle.connection.root
+        : lifecycle.status === "idle"
+            ? projectRoot
+            : lifecycle.root;
+    const facts = useGitFacts(live?.root ?? null, live?.generation ?? null);
+    const connection = live?.git ?? null;
+    const client = connection?.client ?? null;
+    const [tab, setTab] = useState("files");
+    // Bumped after a write so the next read is immediate rather than waiting
+    // out the poll — a stage that takes four seconds to show reads as a stage
+    // that did not happen.
+    const [revision, setRevision] = useState(0);
+    const branch = useGitRead(connection, readBranch, revision).value;
+    const status = useGitRead(connection, readStatus, revision).value;
+    const log = useGitRead(connection, readLog, revision).value;
+    const entries = status?.entries ?? [];
+    const commits = log?.commits ?? [];
+    const unpushed = useMemo(() => commits.some((commit) => commit.pushed === null)
+        ? null
+        : commits.filter((commit) => commit.pushed === false).length, [commits]);
+    const host = useRoom().host;
+    const hasShell = host?.worktree !== undefined;
+    const listBrowsers = useMemo(() => host?.browsers?.bind(host), [host]);
+    const openInBrowser = useMemo(() => (host === null ? null : (name, bytes, browserId) => host.openInBrowser(name, bytes, browserId)), [host]);
+    const stale = projectRoot !== null && shownRoot !== null && shownRoot !== projectRoot;
+    const hasSiblingWorktrees = facts !== null && facts.worktrees.length > 1;
+    const lifecycleError = lifecycle.status === "error" && lifecycle.root === projectRoot
+        ? lifecycle.message
+        : requestError;
+    const [open, setOpen] = useState(null);
+    const [selection, setSelection] = useState(null);
+    const [openCommit, setOpenCommit] = useState(null);
+    const [commitFiles, setCommitFiles] = useState(null);
+    const [pendingDiscard, setPendingDiscard] = useState(null);
+    // One source per engine and one per client: the read hook treats a new
+    // source as a new request, and a project switch invalidates every id and
+    // every path the old ones issued.
+    const fileSource = useMemo(() => (engine === null ? null : createWorktreeFileSource(engine)), [engine]);
+    const gitSource = useMemo(() => (client === null ? null : createGitFileSource(client)), [client]);
+    useEffect(() => {
+        setOpen(null);
+        setSelection(null);
+        setOpenCommit(null);
+    }, [fileSource, gitSource]);
+    const act = useCallback((label, paths, run) => {
+        void run(paths)
+            .then(() => {
+            onReceipt(`${label} ${paths.length} ${paths.length === 1 ? "file" : "files"}`);
+            setRevision((n) => n + 1);
+        })
+            .catch((error) => {
+            onReceipt(error instanceof Error ? error.message : `could not ${label.toLowerCase()}`);
+            setRevision((n) => n + 1);
+        });
+    }, [onReceipt]);
+    const showDiff = (path, staged) => {
+        if (connection === null)
+            return;
+        setSelection({ path, staged });
+        setOpen({
+            handle: diffHandle({ path, staged }, { root: connection.root, label: path }),
+            diff: true,
+        });
+    };
+    const showCommit = (commit) => {
+        setOpenCommit(commit);
+        setCommitFiles(null);
+        setSelection(null);
+        if (client === null)
+            return;
+        void client
+            .commitFiles(commit.sha)
+            .then((answer) => {
+            if (answer.error !== null) {
+                onReceipt(answer.error);
+                setCommitFiles([]);
+                return;
+            }
+            setCommitFiles(answer.files);
+        })
+            .catch((error) => {
+            onReceipt(error instanceof Error ? error.message : "could not read that commit");
+            setCommitFiles([]);
+        });
+    };
+    const count = tab === "history"
+        ? commits.length
+        : tab === "changes"
+            ? entries.length
+            : // The Files tab has no honest count: we know what the tree is
+                // showing, not what the repository holds.
+                null;
+    const source = open?.diff === true ? gitSource : fileSource;
+    return (_jsxs("div", { className: "ah-col ah-col--rail", children: [_jsx(WorktreeHeader, { root: shownRoot, tint: tint, homeDirectory: homeDirectory, facts: facts, branch: branch, tab: tab, count: count, changeShape: changeShapeOf(entries), unpushed: unpushed, folders: folders }), _jsx("div", { className: "ah-listbar", children: _jsx(SegmentedControl, { className: "ah-gitseg", accessibleLabel: "What this column shows", value: tab, options: TABS.map((option) => ({ value: option.value, label: option.label })), onValueChange: (next) => {
+                        setTab(next);
+                        setSelection(null);
+                    } }) }), elsewhere !== undefined && elsewhere !== null ? (_jsx("div", { className: "ah-elsewhere", children: elsewhere })) : !hasShell ? (_jsx(EmptyState, { title: "No repository here", description: "This column needs the desktop shell \u2014 a browser tab has no worktree to read." })) : projectRoot === null ? (_jsx(EmptyState, { title: "No project selected", description: "Pick a project to browse its worktree." })) : lifecycleError !== null ? (_jsx(EmptyState, { title: "Worktree unavailable", description: lifecycleError, children: _jsx("button", { type: "button", onClick: onRetry, style: {
+                        border: "1px solid var(--vf-hairline-strong)",
+                        borderRadius: 6,
+                        padding: "4px 9px",
+                        color: "var(--vf-text-secondary)",
+                        background: "var(--vf-fill)",
+                        cursor: "pointer",
+                    }, children: "Try again" }) })) : tab === "files" ? (engine === null || fileSource === null ? (_jsx(EmptyState, { title: "Opening the worktree", description: "The engine is walking the project root." })) : (_jsxs("div", { className: "ah-railbody", "data-split": hasSiblingWorktrees || undefined, children: [_jsx(WorktreeFileTree, { engine: engine, stale: stale, onReceipt: onReceipt, openEntryId: open?.diff === false && typeof open.handle.ref === "number" ? open.handle.ref : null, onOpen: (entry) => {
+                            // A folder toggles rather than opens; mille only reports rows
+                            // with no children, which an empty directory also is.
+                            if (isOpenable(entry))
+                                setOpen({ handle: handleFor(engine, entry), diff: false });
+                        } }), hasSiblingWorktrees && (_jsx(WorktreeList, { facts: facts, openRoot: shownRoot, homeDirectory: homeDirectory }))] }))) : connection === null ? (_jsx(EmptyState, { title: "Reading the repository", description: "Asking git for its status." })) : tab === "changes" ? (_jsx(GitChanges, { entries: entries, sessionPaths: sessionPaths, selection: selection, onSelect: showDiff, onStage: client === null ? null : (paths) => act("Staged", paths, client.stage), onUnstage: client === null ? null : (paths) => act("Unstaged", paths, client.unstage), onDiscard: client === null ? null : setPendingDiscard })) : (_jsx(GitHistory, { commits: commits, selectedSha: openCommit, onSelect: showCommit, currentTimestamp: currentTimestamp })), openCommit !== null && (_jsx(CommitViewer, { commit: openCommit, files: commitFiles, client: client, sessionPaths: sessionPaths, currentTimestamp: currentTimestamp, onReceipt: onReceipt, onClose: () => {
+                    setOpenCommit(null);
+                    setCommitFiles(null);
+                } })), _jsx(ConfirmDialog, { question: pendingDiscard === null
+                    ? null
+                    : {
+                        title: pendingDiscard.length === 1
+                            ? "Discard this file's changes?"
+                            : `Discard changes to ${pendingDiscard.length} files?`,
+                        body: (_jsxs(_Fragment, { children: [_jsx("p", { children: "This throws the work away. It is not staged and it is not committed, so git has no copy of it and neither does this room." }), _jsxs("ul", { className: "ah-confirm__list", children: [pendingDiscard.slice(0, 8).map((path) => (_jsx("li", { children: path }, path))), pendingDiscard.length > 8 && (_jsxs("li", { "data-more": true, children: ["and ", pendingDiscard.length - 8, " more"] }))] })] })),
+                        confirm: "Discard",
+                        destructive: true,
+                    }, onCancel: () => setPendingDiscard(null), onConfirm: () => {
+                    if (pendingDiscard !== null && client !== null) {
+                        act("Discarded", pendingDiscard, client.discard);
+                    }
+                    setPendingDiscard(null);
+                } }), source !== null && (_jsx(FileViewerDialog, { handle: open?.handle ?? null, source: source, tint: tint, homeDirectory: homeDirectory, onClose: () => setOpen(null), onReceipt: onReceipt, listBrowsers: listBrowsers, openInBrowser: open?.diff === true ? null : openInBrowser, 
+                // The Files tab opens a FILE; the other two open a CHANGE. The
+                // registry reads kinds off a name, and a name cannot say which.
+                asDiff: open?.diff === true }))] }));
+}

package/dist/components/worktree/WorktreeFileTree.d.ts

@@ -0,0 +1,19 @@
+import type { Entry } from "@vibecook/mille";
+import type { WorktreeEngine } from "./types.js";
+export interface WorktreeFileTreeProps {
+    readonly engine: WorktreeEngine;
+    /** The engine is still walking a root the room has moved on from, so the
+     * tree is showing something true but stale. */
+    readonly stale: boolean;
+    /** A file the reader asked to see. Double-click or Enter, the way every
+     * file tree has worked for thirty years — a single click still just
+     * selects, because a row that throws a modal on every click is a row you
+     * learn not to touch. */
+    readonly onOpen: (entry: Entry) => void;
+    /** The file the viewer currently has open, so the row wears the active
+     * fill. The design record left this binding open (§10 delta 4) because a
+     * reader with no open FILE had nothing to bind it to; now there is one. */
+    readonly openEntryId: number | null;
+    readonly onReceipt: (message: string) => void;
+}
+export declare function WorktreeFileTree({ engine, stale, onOpen, openEntryId, onReceipt, }: WorktreeFileTreeProps): import("react").JSX.Element;

package/dist/components/worktree/WorktreeFileTree.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Mille's shipped tree, with Rosetta's read-only commands: inspect a file,
+// copy its path, or reveal it in the desktop file manager.
+import { useMemo, useRef } from "react";
+import { FileTree, FileTreeProvider } from "@vibecook/mille-ui";
+import { vibefieldIconTheme } from "@vibecook/mille-ui/icons/vibefield";
+import { useRoom } from "../../room-context.js";
+import { createWorktreeFileCommands } from "./worktree-file-commands.js";
+/** Mille's create/rename shortcuts also have direct engine fallbacks. Keep
+ * those out of this read-only tree, while letting its own copy binding and
+ * navigation run normally. Portaled menus and text inputs own their keys. */
+function guardTreeKeys(event) {
+    const target = event.target;
+    if (!(target instanceof HTMLElement) || !target.closest('[role="tree"]'))
+        return;
+    if (target.closest('input, textarea, [contenteditable]:not([contenteditable="false"])')) {
+        event.stopPropagation();
+        return;
+    }
+    const key = event.key.toLowerCase();
+    if (key === "f2" || key === "delete" || key === "backspace" ||
+        ((event.ctrlKey || event.metaKey) && !event.altKey && ["x", "v", "n"].includes(key))) {
+        event.preventDefault();
+        event.stopPropagation();
+    }
+}
+/** mille types `FileTreeProvider.fx` as the in-process engine, but the
+ * embedding guide's own architecture puts the walker in a utility process and
+ * the renderer on a port. The port client mirrors that surface — the one
+ * place the room states it, rather than casting at every call site. */
+function asTreeEngine(engine) {
+    return engine.fx;
+}
+export function WorktreeFileTree({ engine, stale, onOpen, openEntryId, onReceipt, }) {
+    const host = useRoom().host;
+    const actions = host?.worktree ?? null;
+    const platform = host?.platform ?? null;
+    const environment = useRef({ actions, platform, stale, onReceipt });
+    environment.current = { actions, platform, stale, onReceipt };
+    const { commands, onSelectionChange, onFocusedIdChange } = useMemo(() => createWorktreeFileCommands(engine, () => environment.current), [engine]);
+    return (_jsx("div", { 
+        // `ah-rail*` is the design record's name for this column; room.css is
+        // a port of the proto and keeps its vocabulary.
+        className: "ah-railtree", "data-mille-theme": "vibefield", "data-stale": stale ? "" : undefined, onKeyDownCapture: guardTreeKeys, 
+        // macOS's native Edit > Copy can arrive as a copy event instead of a
+        // keydown. Route it through the very same selection-aware command.
+        onCopy: (event) => {
+            const target = event.target;
+            if (!(target instanceof HTMLElement) || !target.closest('[role="tree"]') ||
+                target.closest('input, textarea, [contenteditable]:not([contenteditable="false"])'))
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            void commands.dispatch("file.copyAbsolutePath");
+        }, children: _jsx(FileTreeProvider, { fx: asTreeEngine(engine), commands: commands, children: _jsx(FileTree, { ariaLabel: "Project worktree", iconTheme: vibefieldIconTheme, disableDragDrop: true, onSelectionChange: onSelectionChange, onFocusedIdChange: onFocusedIdChange, onOpen: (entry) => onOpen(entry), 
+                // Marks the row without revealing it: `autoRevealActiveEntry`
+                // defaults to false, and the reader who just clicked a row does not
+                // need the tree to scroll it back under their cursor.
+                activeEntry: openEntryId, style: { height: "100%" } }) }, engine.generation) }));
+}

package/dist/components/worktree/WorktreeHeader.d.ts

@@ -0,0 +1,32 @@
+import type { GitFacts } from "../../ports.js";
+import type { BranchFacts } from "../git/index.js";
+import type { RepoTab } from "./types.js";
+import type { RoomFolder, RoomMenu } from "../../host-inputs.js";
+export interface WorktreeHeaderProps {
+    /** The root the tree is actually showing, or null before one opens. */
+    readonly root: string | null;
+    readonly tint: string | null;
+    readonly homeDirectory: string | null;
+    /** Branch and dirty count from the shell, for the Files tab's caption. */
+    readonly facts: GitFacts | null;
+    /** Branch and upstream from the engine, for History's. */
+    readonly branch: BranchFacts | null;
+    readonly tab: RepoTab;
+    /** What the current tab is listing, or null for a tab with no honest count. */
+    readonly count: number | null;
+    readonly changeShape: string;
+    readonly unpushed: number | null;
+    /** R6: the host's folders; the name becomes their dropdown, its mark in front. */
+    readonly folders?: {
+        readonly menu: RoomMenu;
+        readonly shown: RoomFolder | null;
+    } | null | undefined;
+}
+/** `branch · n dirty` — and nothing at all without a branch to hang it on.
+ * The dirty count is the change set's size, not the number of letters the
+ * tree happens to be drawing: a file inside a collapsed folder is still
+ * dirty, and reporting fewer than git would is reporting the interface. */
+export declare function formatGitFacts(facts: GitFacts | null): string | null;
+/** `3 unpushed`, or the honest silence of a branch with no upstream. */
+export declare function formatSync(branch: BranchFacts | null, unpushed: number | null): string;
+export declare function WorktreeHeader({ root, tint, homeDirectory, facts, branch, tab, count, changeShape, unpushed, folders, }: WorktreeHeaderProps): import("react").JSX.Element;

package/dist/components/worktree/WorktreeHeader.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The column is named by the folder it is showing, because that is the thing
+// — "Worktree" was a category, and the head names objects. A path is an id,
+// so it sets in mono.
+//
+// A commit no longer appears here: it opens over the room in its own
+// surface, where a file list and its diff fit side by side, so the head
+// never has to become something other than this column's own object.
+//
+// One column, three tabs, and the head names what THAT tab is a view of —
+// which is a different object per tab, and the design record already draws
+// it that way across the two columns this one merges: its rail head names
+// the folder, its git head names the branch. Files is a view of a checkout,
+// so it takes the path; changes and history are views of a ref, so they take
+// the branch. Inside a commit the object is the commit.
+//
+// It is also what fits. A 280px head holding a path, a count and a
+// three-term caption gave the path four characters, and a head that cannot
+// say its object's name is not naming it.
+//
+// The caption is what git would say about that tab's set, and the badge
+// counts what the tab is listing — which is why Files has none: we know how
+// many files the tree is SHOWING, not how many the repository has, and a
+// badge counting the interface is not a fact about the thing.
+import { ColumnHeading } from "../ui/index.js";
+import { tildePath } from "../../lib/format.js";
+import { HostMenuButton } from "../HostMenu.js";
+const CARET = (_jsx("svg", { viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "m4.5 6.5 3.5 3.5 3.5-3.5" }) }));
+/** `branch · n dirty` — and nothing at all without a branch to hang it on.
+ * The dirty count is the change set's size, not the number of letters the
+ * tree happens to be drawing: a file inside a collapsed folder is still
+ * dirty, and reporting fewer than git would is reporting the interface. */
+export function formatGitFacts(facts) {
+    if (facts === null || facts.branch === null)
+        return null;
+    if (facts.dirty === null)
+        return facts.branch;
+    return `${facts.branch} · ${facts.dirty} dirty`;
+}
+/** `3 unpushed`, or the honest silence of a branch with no upstream. */
+export function formatSync(branch, unpushed) {
+    if (branch === null)
+        return "";
+    // Not "0 unpushed": with no upstream, nothing here knows.
+    if (branch.upstream === null)
+        return "no upstream";
+    const parts = [];
+    if (unpushed !== null && unpushed > 0)
+        parts.push(`${unpushed} unpushed`);
+    if (branch.behind !== null && branch.behind > 0)
+        parts.push(`${branch.behind} behind`);
+    return parts.length > 0 ? parts.join(" · ") : "up to date";
+}
+export function WorktreeHeader({ root, tint, homeDirectory, facts, branch, tab, count, changeShape, unpushed, folders = null, }) {
+    const shown = folders?.shown ?? null;
+    const caption = shown?.caption !== undefined
+        ? shown.caption
+        : tab === "history"
+            ? formatSync(branch, unpushed)
+            : tab === "changes"
+                ? changeShape
+                : (formatGitFacts(facts) ?? "");
+    const onFiles = tab === "files";
+    const path = root === null ? "—" : tildePath(root, homeDirectory);
+    // A detached HEAD has no branch name; the checkout it is in is the honest
+    // fallback, and it is the same object either way.
+    const ref = branch?.name ?? facts?.branch ?? path;
+    if (folders !== null) {
+        // The head is the folder list: the shown folder's mark and name, one button.
+        const folderPath = shown === null ? path : tildePath(shown.path, homeDirectory);
+        const name = onFiles ? folderPath : ref;
+        return (_jsxs("header", { children: [_jsxs(HostMenuButton, { menu: folders.menu, className: "ah-folderpick", label: `Folder: ${shown?.path ?? root ?? "none"}`, title: shown?.path ?? root ?? undefined, align: "start", children: [_jsx("i", { style: tint !== null ? { "--tint": tint } : undefined }), shown?.mark !== undefined && shown.mark !== null && _jsx("span", { className: "ah-folderpick__mark", children: shown.mark }), _jsx("strong", { className: "ah-idname", children: name }), count !== null && _jsx("span", { className: "ah-bubble", children: count }), CARET] }), caption !== "" && _jsx("span", { className: "ah-caption tnum", children: caption })] }));
+    }
+    return (_jsxs("header", { children: [_jsx(ColumnHeading, { name: onFiles ? path : ref, tint: tint, mono: true, count: count, countTitle: count === null
+                    ? undefined
+                    : `${count} ${tab === "history" ? "commits" : "changed files"}`, 
+                // Files abbreviates to `~`, so the tooltip keeps the whole path; a
+                // branch on the other two is already whole, and its tooltip says
+                // which checkout it is a branch OF.
+                title: onFiles ? root : (root ?? undefined) }), caption !== "" && _jsx("span", { className: "ah-caption tnum", children: caption })] }));
+}

package/dist/components/worktree/WorktreeList.d.ts

@@ -0,0 +1,8 @@
+import type { GitFacts } from "../../ports.js";
+export interface WorktreeListProps {
+    readonly facts: GitFacts;
+    /** The root the tree is showing, which earns the dirty count. */
+    readonly openRoot: string | null;
+    readonly homeDirectory: string | null;
+}
+export declare function WorktreeList({ facts, openRoot, homeDirectory }: WorktreeListProps): import("react").JSX.Element;

package/dist/components/worktree/WorktreeList.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { tildePath } from "../../lib/format.js";
+export function WorktreeList({ facts, openRoot, homeDirectory }) {
+    // `ah-rail*` is the design record's name for this column; room.css is a
+    // port of the proto and keeps its vocabulary.
+    return (_jsxs("div", { className: "ah-railfoot", children: [_jsx("div", { className: "ah-railsplit", children: _jsx("span", { className: "ah-eyebrow", children: "Worktrees" }) }), _jsx("div", { className: "ah-railfoot__list", role: "region", "aria-label": "Worktrees", tabIndex: 0, children: facts.worktrees.map((worktree) => {
+                    // The count belongs to the checkout the shell actually read, and
+                    // git reports it for one worktree at a time.
+                    const dirty = worktree.path === openRoot ? facts.dirty : null;
+                    return (_jsxs("div", { className: "ah-worktree", title: worktree.path, children: [_jsx("span", { children: worktree.branch ?? tildePath(worktree.path, homeDirectory) }), dirty !== null && (_jsx("code", { "data-dirty": dirty > 0 ? "" : undefined, className: "tnum", children: dirty > 0 ? `${dirty} dirty` : "clean" }))] }, worktree.path));
+                }) })] }));
+}

package/dist/components/worktree/index.d.ts

@@ -0,0 +1,12 @@
+export type { RepoTab, WorktreeEngine } from "./types.js";
+export { useWorktreeGuest } from "./use-worktree-guest.js";
+export type { WorktreeGuest } from "./use-worktree-guest.js";
+export { WorktreeColumn } from "./WorktreeColumn.js";
+export type { WorktreeColumnProps } from "./WorktreeColumn.js";
+export { formatGitFacts, formatSync, WorktreeHeader } from "./WorktreeHeader.js";
+export type { WorktreeHeaderProps } from "./WorktreeHeader.js";
+export { createWorktreeFileSource, handleFor, isOpenable } from "./worktree-file-source.js";
+export { WorktreeFileTree } from "./WorktreeFileTree.js";
+export type { WorktreeFileTreeProps } from "./WorktreeFileTree.js";
+export { WorktreeList } from "./WorktreeList.js";
+export type { WorktreeListProps } from "./WorktreeList.js";

package/dist/components/worktree/index.js

@@ -0,0 +1,7 @@
+// Column ③ — the project's repository: files, changes, history.
+export { useWorktreeGuest } from "./use-worktree-guest.js";
+export { WorktreeColumn } from "./WorktreeColumn.js";
+export { formatGitFacts, formatSync, WorktreeHeader } from "./WorktreeHeader.js";
+export { createWorktreeFileSource, handleFor, isOpenable } from "./worktree-file-source.js";
+export { WorktreeFileTree } from "./WorktreeFileTree.js";
+export { WorktreeList } from "./WorktreeList.js";

package/dist/components/worktree/types.d.ts

@@ -0,0 +1,17 @@
+import type { PortFileExplorer } from "@vibecook/mille/port";
+/** The three views this column offers of one project: the worktree as it
+ * stands, what git has not recorded yet, and what it has. */
+export type RepoTab = "files" | "changes" | "history";
+/** A live connection to one mille engine, and the root it is walking.
+ *
+ * The root travels WITH the connection rather than beside it: the engine
+ * follows a project switch with a lag (kill, re-fork, walk), and the column
+ * must be able to name what the tree is actually showing at any moment, not
+ * what was last asked for. */
+export interface WorktreeEngine {
+    readonly fx: PortFileExplorer;
+    readonly root: string;
+    /** Utility-process generation. Entry ids are scoped to this identity. */
+    readonly generation: number;
+    dispose(): void;
+}

package/dist/components/worktree/types.js

@@ -0,0 +1,3 @@
+// What column ③ adds around mille's own types. The git shapes belong to the
+// host's worktree port that answers them — see `HostPort` in `ports.ts`.
+export {};

package/dist/components/worktree/use-worktree-guest.d.ts

@@ -0,0 +1,21 @@
+export interface WorktreeGuest {
+    /** Whether a worktree can be shown at all: a host without a worktree
+     * engine (a browser tab) has nothing to walk one with, so the toggle has
+     * nothing to offer. */
+    readonly available: boolean;
+    /** Whether the column is currently open. */
+    readonly visible: boolean;
+    /** A shell-level refusal before a process generation could start. */
+    readonly error: string | null;
+    /** Open a closed column, close an open one. */
+    toggle(): void;
+    /** Explicitly start a fresh generation, even for the same root. */
+    retry(): void;
+}
+/**
+ * Whether column ③ is open, and the act of flipping it — plus the standing
+ * instruction to the host to keep an engine on `projectRoot` while it is.
+ * `roomWidth` is the room's own measured width, not the window's: a host may
+ * seat the room in less than its window. Null until measured.
+ */
+export declare function useWorktreeGuest(projectRoot: string | null, roomWidth: number | null): WorktreeGuest;

package/dist/components/worktree/use-worktree-guest.js

@@ -0,0 +1,92 @@
+// H-3, in one place: the worktree column is a GUEST, and the measure is not.
+// Below a frame the room cannot seat everyone in, the guest closes itself
+// rather than squeeze the transcript — reading is the job, and when something
+// has to give it is not the thing the room exists for.
+//
+// The column's whole lifecycle lives here because the two halves are one
+// decision: what the room shows, and what the engine is therefore asked to
+// walk. Keeping them together is what stops the shell from forking a walker
+// for a column nobody can see.
+import { useEffect, useRef, useState } from "react";
+import { useRoom } from "../../room-context.js";
+/** Below this room width the guest closes itself (design record H-3). 260 + 300 + 280
+ * of columns leaves the transcript its full measure down to ~1100px once the
+ * guest is out of the way, so the guest is what pays. */
+const GUEST_MIN_FRAME_WIDTH = 1360;
+/**
+ * Whether column ③ is open, and the act of flipping it — plus the standing
+ * instruction to the host to keep an engine on `projectRoot` while it is.
+ * `roomWidth` is the room's own measured width, not the window's: a host may
+ * seat the room in less than its window. Null until measured.
+ */
+export function useWorktreeGuest(projectRoot, roomWidth) {
+    const engine = useRoom().host?.worktree ?? null;
+    const available = engine !== null;
+    const [wanted, setWanted] = useState(true);
+    // An explicit choice outranks the automatic close: once the reader has
+    // pressed the toggle, the width heuristic stops speaking for them.
+    const [chosen, setChosen] = useState(false);
+    const [retryRevision, setRetryRevision] = useState(0);
+    const [failure, setFailure] = useState(null);
+    const openedRoot = useRef(null);
+    const requestId = useRef(0);
+    const frameWide = roomWidth !== null && roomWidth >= GUEST_MIN_FRAME_WIDTH;
+    // A wide room keeps the guest's empty state visible before a project is
+    // chosen. A missing root suppresses the engine, not the column explaining it.
+    const visible = available && wanted && (chosen || frameWide);
+    const toggle = () => {
+        // Flips what is SHOWN, not what was last wanted — the first press on an
+        // already-auto-closed column must never do nothing.
+        if (visible) {
+            setWanted(false);
+            return;
+        }
+        setWanted(true);
+        setChosen(true);
+    };
+    const retry = () => {
+        openedRoot.current = null;
+        setFailure(null);
+        setRetryRevision((revision) => revision + 1);
+    };
+    // Point the engine at the selected project's root. Killing and re-forking
+    // the walker is the shell's concern, so this only speaks when the root
+    // actually changes — a re-render is not news.
+    useEffect(() => {
+        if (!visible || projectRoot === null)
+            return;
+        if (openedRoot.current === projectRoot)
+            return;
+        if (engine === null)
+            return;
+        const id = (requestId.current += 1);
+        openedRoot.current = projectRoot;
+        setFailure(null);
+        void engine
+            .open(projectRoot)
+            .then((result) => {
+            if (requestId.current !== id)
+                return;
+            if (result.ok)
+                return;
+            openedRoot.current = null;
+            setFailure({ root: projectRoot, message: result.error });
+        })
+            .catch((reason) => {
+            if (requestId.current !== id)
+                return;
+            openedRoot.current = null;
+            setFailure({
+                root: projectRoot,
+                message: reason instanceof Error ? reason.message : "Could not open the worktree.",
+            });
+        });
+    }, [visible, projectRoot, retryRevision, engine]);
+    return {
+        available,
+        visible,
+        error: failure?.root === projectRoot ? failure.message : null,
+        toggle,
+        retry,
+    };
+}

package/dist/components/worktree/worktree-file-commands.d.ts

@@ -0,0 +1,19 @@
+import type { EntryId } from "@vibecook/mille";
+import type { WorktreeHostPort } from "../../ports.js";
+import type { WorktreeEngine } from "./types.js";
+interface FileActionEnvironment {
+    /** The host's worktree engine, which performs the acts; null without one. */
+    readonly actions: Pick<WorktreeHostPort, "fileAction"> | null;
+    /** The desktop's platform, for the name of its file manager. */
+    readonly platform: string | null;
+    readonly stale: boolean;
+    readonly onReceipt: (message: string) => void;
+}
+/** One registry per engine generation. Menu commands receive Mille's live
+ * context; keyboard commands get the same selection through its observers. */
+export declare function createWorktreeFileCommands(engine: WorktreeEngine, environment: () => FileActionEnvironment): {
+    commands: import("@vibecook/mille-ui/commands").CommandRegistry;
+    onSelectionChange: (ids: ReadonlySet<EntryId>) => void;
+    onFocusedIdChange: (id: EntryId | null) => void;
+};
+export {};