@hanzo/build 0.2.0

package/lib/api/sessions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Runs, as the platform records them: one session per run.
+ *
+ *   GET  /v1/agent/sessions?kind=&project=&status=&limit=   newest first
+ *   GET  /v1/agent/sessions/{id}                            + the 50 most recent events
+ *   POST /v1/agent/sessions/{id}/message {message}           steer a running run
+ *   POST /v1/agent/sessions/{id}/stop    {message}           end it, work kept
+ *   GET  /v1/agent/sessions/stream?root={id}                 SSE: `session` and `event` frames
+ *
+ * The stream is best-effort by the platform's own statement: a subscriber that
+ * falls 256 frames behind is dropped. So `watch` reconnects, and every
+ * reconnect is reported, which is the caller's cue to re-read the detail.
+ */
+import { type Target } from './call.ts';
+export type Status = 'running' | 'paused' | 'done' | 'error' | 'stopped' | string;
+export interface Session {
+    id: string;
+    title: string;
+    status: Status;
+    agent: string;
+    actor: string;
+    repo: string;
+    project: string;
+    target: string;
+    /** What sort of run: 'coding' for a coding run. */
+    kind: string;
+    /** The branch the run started from, or ''. */
+    base: string;
+    /** The branch the run pushes to — the only one it may write. */
+    branch: string;
+    /** 'sandbox', or the id of the org's machine it runs on. */
+    environment: string;
+    /** The pull request the run proposed, or ''. */
+    pr: string;
+    events: number;
+    createdAt: string;
+    updatedAt: string;
+    endedAt: string;
+}
+export interface Event {
+    id: string;
+    sessionId: string;
+    seq: number;
+    kind: string;
+    actor: string;
+    payload: unknown;
+    createdAt: string;
+}
+export interface Detail extends Session {
+    recent: Event[];
+}
+export declare function session(raw: unknown): Session;
+export declare function event(raw: unknown): Event;
+export interface ListQuery {
+    kind?: string;
+    project?: string;
+    status?: string;
+    limit?: number;
+}
+export declare function list(t: Target, q?: ListQuery): Promise<Session[]>;
+export declare function get(t: Target, id: string): Promise<Detail>;
+export declare function message(t: Target, id: string, text: string): Promise<void>;
+export declare function stop(t: Target, id: string, why?: string): Promise<void>;
+export interface Watch {
+    session?: (s: Session) => void;
+    event?: (e: Event) => void;
+    /** Each (re)connect. The first is 0; a later one means frames may have been missed. */
+    open?: (attempt: number) => void;
+}
+/**
+ * Follow one run's tree until `signal` aborts. Reconnects with a capped backoff;
+ * a refusal (401/403) ends it, because retrying a no is not recovery.
+ */
+export declare function watch(t: Target, root: string, on: Watch, signal: AbortSignal): Promise<void>;

package/lib/api/sessions.js

@@ -0,0 +1,120 @@
+/**
+ * Runs, as the platform records them: one session per run.
+ *
+ *   GET  /v1/agent/sessions?kind=&project=&status=&limit=   newest first
+ *   GET  /v1/agent/sessions/{id}                            + the 50 most recent events
+ *   POST /v1/agent/sessions/{id}/message {message}           steer a running run
+ *   POST /v1/agent/sessions/{id}/stop    {message}           end it, work kept
+ *   GET  /v1/agent/sessions/stream?root={id}                 SSE: `session` and `event` frames
+ *
+ * The stream is best-effort by the platform's own statement: a subscriber that
+ * falls 256 frames behind is dropped. So `watch` reconnects, and every
+ * reconnect is reported, which is the caller's cue to re-read the detail.
+ */
+import { call, headers, query, Refusal, seg } from './call.js';
+import { read } from './sse.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const obj = (v) => v && typeof v === 'object' ? v : {};
+export function session(raw) {
+    const s = obj(raw);
+    return {
+        id: str(s.id),
+        title: str(s.title),
+        status: str(s.status),
+        agent: str(s.agent),
+        actor: str(s.actor),
+        repo: str(s.repo),
+        project: str(s.project),
+        target: str(s.target),
+        kind: str(s.kind),
+        base: str(s.base),
+        branch: str(s.branch),
+        environment: str(s.environment),
+        pr: str(s.pr),
+        events: num(s.events),
+        createdAt: str(s.createdAt),
+        updatedAt: str(s.updatedAt),
+        endedAt: str(s.endedAt),
+    };
+}
+export function event(raw) {
+    const e = obj(raw);
+    return {
+        id: str(e.id),
+        sessionId: str(e.sessionId),
+        seq: num(e.seq),
+        kind: str(e.kind),
+        actor: str(e.actor),
+        payload: e.payload,
+        createdAt: str(e.createdAt),
+    };
+}
+export async function list(t, q = {}) {
+    const raw = obj(await call(t, 'GET', `/v1/agent/sessions${query({ ...q })}`));
+    return (Array.isArray(raw.sessions) ? raw.sessions : []).map(session).filter((s) => s.id);
+}
+export async function get(t, id) {
+    const raw = obj(await call(t, 'GET', `/v1/agent/sessions/${seg(id)}`));
+    return {
+        ...session(raw),
+        recent: (Array.isArray(raw.recentEvents) ? raw.recentEvents : []).map(event),
+    };
+}
+export async function message(t, id, text) {
+    const m = text.trim();
+    if (!m)
+        throw new Refusal(400, 'Say something to the run');
+    await call(t, 'POST', `/v1/agent/sessions/${seg(id)}/message`, { message: m });
+}
+export async function stop(t, id, why = 'Stopped from the builder') {
+    await call(t, 'POST', `/v1/agent/sessions/${seg(id)}/stop`, { message: why });
+}
+/**
+ * Follow one run's tree until `signal` aborts. Reconnects with a capped backoff;
+ * a refusal (401/403) ends it, because retrying a no is not recovery.
+ */
+export async function watch(t, root, on, signal) {
+    let opened = 0;
+    let fails = 0;
+    while (!signal.aborted) {
+        try {
+            const res = await fetch(`${t.api}/v1/agent/sessions/stream${query({ root })}`, {
+                headers: headers(t, { Accept: 'text/event-stream' }),
+                cache: 'no-store',
+                signal,
+            });
+            if (res.status === 401 || res.status === 403)
+                throw new Refusal(res.status, 'This account cannot follow this run');
+            if (!res.ok || !res.body)
+                throw new Error(`stream answered ${res.status}`);
+            on.open?.(opened++);
+            fails = 0;
+            await read(res.body, (f) => {
+                let data;
+                try {
+                    data = JSON.parse(f.data);
+                }
+                catch {
+                    return;
+                }
+                if (f.event === 'session')
+                    on.session?.(session(data));
+                else if (f.event === 'event')
+                    on.event?.(event(data));
+            }, signal);
+        }
+        catch (e) {
+            if (e instanceof Refusal)
+                throw e;
+            if (signal.aborted)
+                return;
+            fails += 1;
+        }
+        const wait = Math.min(15000, 1000 * 2 ** Math.min(fails, 4));
+        await new Promise((done) => {
+            const t = setTimeout(done, wait);
+            signal.addEventListener('abort', () => (clearTimeout(t), done()), { once: true });
+        });
+    }
+}

package/lib/api/sse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server-Sent Events, read off a fetch body.
+ *
+ * `EventSource` cannot send an Authorization header, and the session stream
+ * refuses a request without a principal, so the stream is read as a plain
+ * response body and parsed here. The parser is pure: bytes in, frames and the
+ * unfinished tail out, so it is tested without a network.
+ *
+ * Per the spec a frame ends at a blank line; `event:` names it (default
+ * `message`), `data:` lines join with a newline, and a line starting `:` is a
+ * comment — the platform's 25-second `: ping` keep-alive.
+ */
+export interface Frame {
+    event: string;
+    data: string;
+    id: string;
+}
+/** Split `buffer` into complete frames and the tail that has not ended yet. */
+export declare function parse(buffer: string): {
+    frames: Frame[];
+    rest: string;
+};
+/** Read `body` to its end, calling `on` for each frame. */
+export declare function read(body: ReadableStream<Uint8Array>, on: (f: Frame) => void, signal?: AbortSignal): Promise<void>;

package/lib/api/sse.js

@@ -0,0 +1,68 @@
+/**
+ * Server-Sent Events, read off a fetch body.
+ *
+ * `EventSource` cannot send an Authorization header, and the session stream
+ * refuses a request without a principal, so the stream is read as a plain
+ * response body and parsed here. The parser is pure: bytes in, frames and the
+ * unfinished tail out, so it is tested without a network.
+ *
+ * Per the spec a frame ends at a blank line; `event:` names it (default
+ * `message`), `data:` lines join with a newline, and a line starting `:` is a
+ * comment — the platform's 25-second `: ping` keep-alive.
+ */
+/** Split `buffer` into complete frames and the tail that has not ended yet. */
+export function parse(buffer) {
+    const text = buffer.replace(/\r\n?/g, '\n');
+    const frames = [];
+    let start = 0;
+    for (;;) {
+        const end = text.indexOf('\n\n', start);
+        if (end === -1)
+            break;
+        const block = text.slice(start, end);
+        start = end + 2;
+        let event = 'message';
+        let id = '';
+        const data = [];
+        for (const line of block.split('\n')) {
+            if (!line || line.startsWith(':'))
+                continue;
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            let value = colon === -1 ? '' : line.slice(colon + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1);
+            if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                data.push(value);
+            else if (field === 'id')
+                id = value;
+        }
+        if (data.length)
+            frames.push({ event, data: data.join('\n'), id });
+    }
+    return { frames, rest: text.slice(start) };
+}
+/** Read `body` to its end, calling `on` for each frame. */
+export async function read(body, on, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let rest = '';
+    const stop = () => void reader.cancel().catch(() => { });
+    signal?.addEventListener('abort', stop, { once: true });
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            const out = parse(rest + decoder.decode(value, { stream: true }));
+            rest = out.rest;
+            for (const f of out.frames)
+                on(f);
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', stop);
+    }
+}

package/lib/api/turn.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a run's events SAY, as text a person reads.
+ *
+ * A curated projection, never a dump: an event carries the machinery a run
+ * happened on — hosts, paths, whole file bodies — and printing it would put
+ * someone's filesystem in front of anyone who can read the run. Each kind gets a
+ * sentence built from the few fields that describe the outcome; the rest is
+ * dropped by omission, because a projection cannot leak a field it never reads.
+ *
+ * Every string here is rendered as TEXT by the transcript. Nothing is HTML.
+ *
+ * The coding plane's vocabulary (apps/coding): `status` for a lifecycle move
+ * (started, routed, done, error, stopped, paused), `tool-call` for a step,
+ * `log` for a free line. A steering message a person sent is a `message`.
+ */
+import type { Event } from './sessions.ts';
+/** The payload as an object. A live frame may carry it as a JSON string. */
+export declare function decode(payload: unknown): Record<string, unknown> | string | null;
+/** One event's sentence, or '' when it says nothing a person needs. */
+export declare function said(e: Pick<Event, 'kind' | 'payload'>): string;
+export interface Outcome {
+    /** The last lifecycle status the run narrated, or ''. */
+    status: string;
+    /**
+     * That the pull request could not be opened, as narrated, or ''. Shown as a
+     * fact only — its text comes from an event any member can write, so it is
+     * never put on screen as the reason.
+     */
+    problem: string;
+}
+/**
+ * What the run narrated about how it ended, latest winning. Status text only:
+ * the branch and the pull request are read from the run's record (`pull`).
+ */
+export declare function outcome(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): Outcome;
+/** The turns, ordered and deduped: a recorded read and the live feed overlap. */
+export declare function merge<T extends Pick<Event, 'id' | 'seq'>>(...lists: T[][]): T[];
+/** The actor, short enough to label a block: `hanzo/2d4d67ab`, not the whole subject. */
+export declare function who(actor: string): string;
+/**
+ * A pull request address the builder will draw as a link: https, on GitHub or
+ * the platform's own git, shaped like a pull request, and IN THE RUN'S OWN
+ * REPOSITORY (`repo`, `owner/name`). Anything else is ''. Read from the run's
+ * record, which the coding service writes — never from an event, which any
+ * member of the org can append — and bound to the repository, because a record
+ * can be moved into a project it did not work on.
+ */
+export declare function pull(url: string, repo: string): {
+    href: string;
+    label: string;
+};

package/lib/api/turn.js

@@ -0,0 +1,121 @@
+const str = (v) => (typeof v === 'string' ? v : '');
+/** The payload as an object. A live frame may carry it as a JSON string. */
+export function decode(payload) {
+    if (payload && typeof payload === 'object')
+        return payload;
+    if (typeof payload !== 'string')
+        return null;
+    const text = payload.trim();
+    if (!text.startsWith('{'))
+        return payload;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        /* prose that opens with a brace */
+    }
+    return payload;
+}
+/** A file's name, never the host path it sat at. */
+const base = (path) => {
+    const cut = path.replace(/\/+$/, '');
+    return cut.slice(cut.lastIndexOf('/') + 1);
+};
+function status(b) {
+    const branch = str(b.branch);
+    switch (str(b.status)) {
+        case 'started':
+            return branch ? `Started on ${branch}` : 'Started';
+        case 'routed':
+            return 'Sent to a machine';
+        case 'done': {
+            if (b.changed === false)
+                return 'Done — nothing to change';
+            const pr = str(b.pr);
+            const tail = str(b.prError) ? ' — the pull request could not be opened' : pr ? ` — ${pr}` : '';
+            return branch ? `Pushed ${branch}${tail}` : `Done${tail}`;
+        }
+        case 'error':
+            return str(b.error) || 'The run hit an error';
+        case 'stopped':
+            return branch && b.changed ? `Stopped — work kept on ${branch}` : 'Stopped';
+        case 'paused':
+            return 'Paused';
+    }
+    return str(b.status);
+}
+/** One event's sentence, or '' when it says nothing a person needs. */
+export function said(e) {
+    const body = decode(e.payload);
+    if (typeof body === 'string')
+        return body;
+    if (!body)
+        return '';
+    if (e.kind === 'status')
+        return status(body);
+    for (const key of ['message', 'text', 'content', 'result', 'command']) {
+        const v = body[key];
+        if (typeof v === 'string' && v)
+            return v;
+    }
+    if (str(body.type) === 'done' && Array.isArray(body.changed)) {
+        const names = body.changed.map((f) => base(str(f))).filter(Boolean);
+        return names.length === 0
+            ? 'Done — no files changed'
+            : names.length <= 3
+                ? `Done — changed ${names.join(', ')}`
+                : `Done — changed ${names.length} files`;
+    }
+    if (str(body.type) === 'error')
+        return str(body.error) || 'The run hit an error';
+    return str(body.step) || str(body.name);
+}
+/**
+ * What the run narrated about how it ended, latest winning. Status text only:
+ * the branch and the pull request are read from the run's record (`pull`).
+ */
+export function outcome(events) {
+    const out = { status: '', problem: '' };
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.kind !== 'status')
+            continue;
+        const b = decode(e.payload);
+        if (!b || typeof b === 'string')
+            continue;
+        out.status = str(b.status) || out.status;
+        out.problem = str(b.prError) || out.problem;
+    }
+    return out;
+}
+/** The turns, ordered and deduped: a recorded read and the live feed overlap. */
+export function merge(...lists) {
+    const seen = new Map();
+    for (const list of lists)
+        for (const e of list)
+            seen.set(e.seq ? `s${e.seq}` : `i${e.id}`, e);
+    return [...seen.values()].sort((a, b) => a.seq - b.seq);
+}
+/** The actor, short enough to label a block: `hanzo/2d4d67ab`, not the whole subject. */
+export function who(actor) {
+    const cut = actor.indexOf('/');
+    if (cut === -1)
+        return actor.split('-')[0] || actor;
+    const head = actor.slice(cut + 1).split('-')[0] ?? '';
+    return head ? `${actor.slice(0, cut)}/${head}` : actor;
+}
+/**
+ * A pull request address the builder will draw as a link: https, on GitHub or
+ * the platform's own git, shaped like a pull request, and IN THE RUN'S OWN
+ * REPOSITORY (`repo`, `owner/name`). Anything else is ''. Read from the run's
+ * record, which the coding service writes — never from an event, which any
+ * member of the org can append — and bound to the repository, because a record
+ * can be moved into a project it did not work on.
+ */
+export function pull(url, repo) {
+    const m = /^https:\/\/(?:github\.com|git\.hanzo\.ai)\/([\w.-]+)\/([\w.-]+)\/pulls?\/(\d+)\/?$/.exec(url);
+    if (!m || !repo || `${m[1]}/${m[2]}`.toLowerCase() !== repo.toLowerCase())
+        return { href: '', label: '' };
+    return { href: url, label: `#${m[3]}` };
+}

package/lib/api/verdict.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A person's verdict on what a run said, recorded on the platform's own event
+ * bus in the org it was said in.
+ *
+ *   POST /v1/event {type: 'track', event: 'build.verdict', sessionId, properties}
+ *
+ * The receipt says whether it landed; a verdict that did not is reported, not
+ * shown as recorded.
+ */
+import { type Target } from './call.ts';
+export type Verdict = 'up' | 'down' | null;
+export declare function verdict(t: Target, session: string, project: string, v: Verdict): Promise<void>;

package/lib/api/verdict.js

@@ -0,0 +1,20 @@
+/**
+ * A person's verdict on what a run said, recorded on the platform's own event
+ * bus in the org it was said in.
+ *
+ *   POST /v1/event {type: 'track', event: 'build.verdict', sessionId, properties}
+ *
+ * The receipt says whether it landed; a verdict that did not is reported, not
+ * shown as recorded.
+ */
+import { call } from './call.js';
+export async function verdict(t, session, project, v) {
+    const out = await call(t, 'POST', '/v1/event', {
+        type: 'track',
+        event: 'build.verdict',
+        sessionId: session,
+        properties: { verdict: v ?? 'cleared', project },
+    });
+    if (!out || !out.accepted)
+        throw new Error('The verdict was not recorded');
+}

package/lib/builder.d.ts

@@ -0,0 +1,5 @@
+import { type Host } from './host.tsx';
+/** The builder. Mount it under a gui root (`<Hanzo>`), in a box with a height. */
+export declare function Builder({ host }: {
+    host: Host;
+}): import("react").JSX.Element;

package/lib/builder.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The builder: the rail, and whichever pane the address names.
+ *
+ *   /            New — the empty state, a composer over the repo it works on
+ *   /sess_…      one run, live
+ *   /-/artifacts what this org has built
+ *   /-/templates the public starters
+ *   /<slug>      a project's workspace, in this same window
+ *
+ * The rail is the sessions rail every Hanzo surface shares: New, the builder's
+ * places, the org's coding runs newest first with a live status dot, and the
+ * account. Its collapse is an explicit toggle kept per browser.
+ *
+ * A project's workspace takes the whole window — it has its own chat column,
+ * bar and panes — and its mark leads back here.
+ */
+import { SizableText, XStack, YStack } from '@hanzo/gui';
+import { Blocks, BookOpen, Cpu, LayoutTemplate, Menu, Puzzle } from '@hanzogui/lucide-icons-2';
+import { Button } from '@hanzo/ui';
+import { SessionRail } from '@hanzo/ui/chat';
+import { HanzoMark } from '@hanzo/ui/product';
+import { useMemo, useState } from 'react';
+import { useKept, useRecents } from './data.js';
+import { HostProvider, useHost, useTarget } from './host.js';
+import { Landing } from './landing.js';
+import { Project } from './project.js';
+import { path, route } from './route.js';
+import { Run } from './run.js';
+import { Artifacts, Templates } from './shelf.js';
+import { Account, Find } from './account.js';
+const DOTS = {
+    running: 'running',
+    paused: 'paused',
+    done: 'done',
+    stopped: 'stopped',
+    error: 'error',
+};
+function Shell() {
+    const host = useHost();
+    const t = useTarget();
+    const r = route(host.path);
+    const recents = useRecents(t, Boolean(host.person));
+    const [collapsed, setCollapsed] = useKept('hanzo.build.rail', false);
+    const [drawer, setDrawer] = useState(false);
+    const [order, setOrder] = useState('newest');
+    const [account, setAccount] = useState(false);
+    const [finding, setFinding] = useState(false);
+    const go = (p) => {
+        setDrawer(false);
+        host.go(p);
+    };
+    const rows = useMemo(() => {
+        const list = recents.value.map((s) => ({ id: s.id, title: s.title || 'Untitled run', status: DOTS[s.status] ?? 'idle' }));
+        if (order === 'running')
+            list.sort((a, b) => Number(b.status === 'running') - Number(a.status === 'running'));
+        return list;
+    }, [recents.value, order]);
+    const screen = r.kind === 'screen' ? r.screen : '';
+    const links = [
+        { id: 'artifacts', label: 'Artifacts', icon: _jsx(Blocks, { size: 16 }), onPress: () => go(path({ kind: 'screen', screen: 'artifacts' })), active: screen === 'artifacts' },
+        { id: 'customize', label: 'Customize', icon: _jsx(Puzzle, { size: 16 }), onPress: () => host.open(host.links.customize) },
+    ];
+    const more = [
+        { id: 'templates', label: 'Templates', icon: _jsx(LayoutTemplate, { size: 16 }), onPress: () => go(path({ kind: 'screen', screen: 'templates' })), active: screen === 'templates' },
+        { id: 'machines', label: 'Machines', icon: _jsx(Cpu, { size: 16 }), onPress: () => host.open(`${host.links.home.replace(/\/+$/, '')}/platform/computers`) },
+        { id: 'docs', label: 'Docs', icon: _jsx(BookOpen, { size: 16 }), onPress: () => window.open('https://docs.hanzo.ai/docs/dev', '_blank', 'noopener,noreferrer') },
+    ];
+    return (_jsxs(XStack, { flex: 1, minH: 0, minW: 0, bg: "$background", children: [_jsx(SessionRail, { onNew: () => go(''), fresh: r.kind === 'new', links: links, more: more, recents: rows, active: r.kind === 'run' ? r.id : null, onOpen: (id) => go(id), onSort: () => setOrder(order === 'newest' ? 'running' : 'newest'), sortLabel: order === 'newest' ? 'Show running first' : 'Show newest first', empty: _jsx(SizableText, { size: "$1", color: "$soft", px: "$2", children: !host.person ? 'Sign in to see your runs.' : recents.error ? recents.error.message : recents.loading ? 'Reading…' : 'No runs yet.' }), account: host.person
+                    ? { name: host.person.email || host.person.name, onPress: () => setAccount(true) }
+                    : { name: 'Sign in', onPress: () => host.signIn?.() }, onSettings: () => host.open(host.links.settings), onSearch: () => setFinding(true), collapsed: collapsed, onCollapse: setCollapsed, mark: _jsx(HanzoMark, { size: 18 }), open: drawer, onOpenChange: setDrawer, label: "Runs" }), _jsxs(YStack, { flex: 1, minW: 0, minH: 0, position: "relative", children: [_jsx(XStack, { height: 44, px: "$2", items: "center", shrink: 0, $md: { display: 'none' }, children: _jsx(Button, { variant: "ghost", size: "icon-sm", onPress: () => setDrawer(true), "aria-label": "Open runs", children: _jsx(Menu, { size: 18 }) }) }), r.kind === 'run' ? (_jsx(Run, { id: r.id }, r.id)) : r.kind === 'screen' ? (r.screen === 'artifacts' ? _jsx(Artifacts, {}) : _jsx(Templates, {})) : (_jsx(Landing, { onStarted: (id) => { recents.reload(); go(id); } }))] }), _jsx(Account, { open: account, onOpenChange: setAccount }), _jsx(Find, { open: finding, onOpenChange: setFinding, recents: rows, onOpen: (id) => { setFinding(false); go(id); } })] }));
+}
+function Screens() {
+    const host = useHost();
+    const r = route(host.path);
+    return r.kind === 'project' ? _jsx(Project, { slug: r.slug }, r.slug) : _jsx(Shell, {});
+}
+/** The builder. Mount it under a gui root (`<Hanzo>`), in a box with a height. */
+export function Builder({ host }) {
+    return (_jsx(HostProvider, { host: host, children: _jsx(YStack, { flex: 1, minH: 0, minW: 0, height: "100%", children: _jsx(Screens, {}) }) }));
+}

package/lib/data.d.ts

@@ -0,0 +1,42 @@
+import type { Target } from './api/call.ts';
+import { type Place } from './api/places.ts';
+import { type Project } from './api/projects.ts';
+import { type Detail, type Event, type Session } from './api/sessions.ts';
+export interface Read<T> {
+    value: T;
+    error: Error | null;
+    loading: boolean;
+    reload: () => void;
+}
+/** Run `load` whenever `key` changes (and on `reload`), keeping the last good value. */
+export declare function useRead<T>(load: (() => Promise<T>) | null, initial: T, key: unknown[]): Read<T>;
+/**
+ * The org's coding runs, newest first, kept current by the org's own session
+ * stream: a status that moves moves its dot, and a run started anywhere appears.
+ */
+export declare function useRecents(t: Target, signed: boolean): Read<Session[]>;
+export declare function usePlaces(t: Target, signed: boolean): Read<Place[]>;
+export declare function useProjects(t: Target, signed: boolean): Read<Project[]>;
+/** A value kept in this browser, per key; storage that throws keeps it in memory. */
+export declare function useKept<T>(key: string, initial: T): [T, (v: T) => void];
+export interface RunState {
+    detail: Read<Detail | null>;
+    /**
+     * The run's record, as last read or pushed: status, branch, pull request.
+     * The coding service writes it; events are the narration, and any member of
+     * the org can append one, so a link or a branch is never taken from them.
+     */
+    record: Session | null;
+    /** Every turn, recorded and live, in order. */
+    events: Event[];
+    /** The run's status as last reported by the record or the feed. */
+    status: string;
+    /** Why the feed stopped, when it was refused. */
+    refused: string;
+}
+/**
+ * One run: the recorded detail, then the live feed added to it. A reconnect
+ * after a drop re-reads the detail — frames missed while dropped are only in
+ * the record. `id` null reads nothing.
+ */
+export declare function useRun(t: Target, id: string | null): RunState;