@digitornai/sdk 0.1.0

package/dist/compile.d.ts

@@ -0,0 +1,31 @@
+/** Result of a {@link useCompile} run. */
+export interface CompileResult {
+    /** True when the build command exited 0. */
+    ok: boolean;
+    /** Tail of the build log (stdout+stderr), bounded by the daemon. */
+    log: string;
+    /** True when the build hit the daemon's time budget. */
+    timedOut: boolean;
+}
+/**
+ * Rebuild the current session's document without an agent turn.
+ *
+ * The app owns the button (via {@link useTopBarActions}); this hook owns the
+ * action. It POSTs to the session's build endpoint, which runs the command the
+ * APP DECLARED in its manifest (`runtime.preview_compile`) inside the workdir,
+ * with the app's provisioned requirements on PATH (e.g. `tectonic`). The
+ * command is author-defined and never travels from here, so the iframe cannot
+ * ask the host to run something arbitrary. The existing preview watcher shows
+ * the fresh output.
+ *
+ * ```tsx
+ * const { compile, compiling } = useCompile();
+ * useTopBarActions([
+ *   { id: "recompile", label: "Recompile", icon: "hammer", onClick: () => void compile() },
+ * ]);
+ * ```
+ */
+export declare function useCompile(): {
+    compile: () => Promise<CompileResult>;
+    compiling: boolean;
+};

package/dist/compile.js

@@ -0,0 +1,48 @@
+import * as React from "react";
+import { useDigitorn } from "./provider.js";
+import { useWorkspaceEndpoint } from "./workspace.js";
+/**
+ * Rebuild the current session's document without an agent turn.
+ *
+ * The app owns the button (via {@link useTopBarActions}); this hook owns the
+ * action. It POSTs to the session's build endpoint, which runs the command the
+ * APP DECLARED in its manifest (`runtime.preview_compile`) inside the workdir,
+ * with the app's provisioned requirements on PATH (e.g. `tectonic`). The
+ * command is author-defined and never travels from here, so the iframe cannot
+ * ask the host to run something arbitrary. The existing preview watcher shows
+ * the fresh output.
+ *
+ * ```tsx
+ * const { compile, compiling } = useCompile();
+ * useTopBarActions([
+ *   { id: "recompile", label: "Recompile", icon: "hammer", onClick: () => void compile() },
+ * ]);
+ * ```
+ */
+export function useCompile() {
+    const { root, headers, preview } = useWorkspaceEndpoint();
+    const { session } = useDigitorn();
+    const [compiling, setCompiling] = React.useState(false);
+    const compile = React.useCallback(async () => {
+        setCompiling(true);
+        try {
+            const url = preview
+                ? `${root}/preview/compile?t=${encodeURIComponent(session.previewToken)}`
+                : `${root}/preview/compile`;
+            const res = await fetch(url, { method: "POST", headers });
+            const body = (await res.json().catch(() => ({})));
+            return {
+                ok: body?.ok === true,
+                log: typeof body?.log === "string" ? body.log : "",
+                timedOut: body?.timed_out === true,
+            };
+        }
+        catch (e) {
+            return { ok: false, log: String(e?.message ?? e), timedOut: false };
+        }
+        finally {
+            setCompiling(false);
+        }
+    }, [root, headers, preview, session.previewToken]);
+    return { compile, compiling };
+}

package/dist/connect.d.ts

@@ -0,0 +1,11 @@
+import { type Socket } from "socket.io-client";
+import type { SessionInfo, Envelope } from "./types.js";
+import type { Action } from "./reducer.js";
+type Dispatch = (action: Action) => void;
+export declare function createConnection(session: SessionInfo, dispatch: Dispatch, seqRef: {
+    current: number;
+}, onEnvelope?: (env: Envelope) => void): Socket;
+export declare function emitSendMessage(socket: Socket | null, sessionId: string, text: string, correlationId: string): void;
+export declare function emitAbort(socket: Socket | null, sessionId: string): void;
+export declare function emitResolveApproval(socket: Socket | null, sessionId: string, id: string, approved: boolean, reason?: string): void;
+export {};

package/dist/connect.js

@@ -0,0 +1,89 @@
+import { io } from "socket.io-client";
+export function createConnection(session, dispatch, seqRef, onEnvelope) {
+    let url = `${session.baseUrl}/events`;
+    if (session.token)
+        url += `?token=${encodeURIComponent(session.token)}`;
+    // The embedded preview can't present a usable JWT, so it authenticates its
+    // socket with the per-session `?t=` preview token - the daemon accepts it and
+    // locks the socket to this session's room (read-only). A JWT, when present,
+    // is still tried first. This is what lets the preview get live push instead
+    // of polling.
+    const auth = {};
+    if (session.token)
+        auth.token = session.token;
+    if (session.previewToken) {
+        auth.preview_token = session.previewToken;
+        auth.app_id = session.appId;
+        auth.session_id = session.sessionId;
+    }
+    const socket = io(url, {
+        transports: ["websocket"],
+        auth,
+        forceNew: true,
+        reconnectionDelay: 500,
+        reconnectionDelayMax: 5000,
+    });
+    socket.on("connect", () => {
+        dispatch({ type: "connected" });
+        socket.emit("join_session", {
+            app_id: session.appId,
+            session_id: session.sessionId,
+            since: seqRef.current,
+        });
+    });
+    socket.on("disconnect", () => dispatch({ type: "disconnected" }));
+    socket.on("connect_error", () => dispatch({ type: "disconnected" }));
+    socket.on("event", (env) => {
+        if (!env || typeof env.type !== "string")
+            return;
+        if (typeof env.seq === "number" && env.seq > seqRef.current) {
+            seqRef.current = env.seq;
+        }
+        dispatch({ type: "event", env });
+        onEnvelope?.(env);
+    });
+    // The daemon also emits a handful of signals as their OWN named Socket.IO
+    // event (not wrapped in the generic "event" envelope) - a build/dev-server
+    // becoming reachable is the one apps most want to react to. Folded into
+    // the same `state.events` stream so `useEvents(e => e.type === "...")`
+    // sees them too, instead of every app re-implementing its own listener.
+    // `seq: 0` keeps these out of the replay/resume bookkeeping above - they
+    // are live-only notifications, never part of session history.
+    socket.on("web_preview:attached", (payload) => {
+        // The payload's own `type` field means "static" | "devserver" (the kind
+        // of attachment) - spread it BEFORE the envelope's `type`, so the
+        // Envelope-level field stays "web_preview:attached" and the payload's
+        // own `type` survives as e.g. `env.type_` would - actually keep it
+        // under a distinct key so nothing is lost.
+        const { type: attachKind, ...rest } = payload;
+        const env = {
+            seq: 0,
+            ts: Date.now(),
+            session_id: session.sessionId,
+            ...rest,
+            attach_kind: attachKind,
+            type: "web_preview:attached",
+        };
+        dispatch({ type: "event", env });
+        onEnvelope?.(env);
+    });
+    return socket;
+}
+export function emitSendMessage(socket, sessionId, text, correlationId) {
+    socket?.emit("send_message", {
+        session_id: sessionId,
+        text,
+        correlation_id: correlationId,
+    });
+}
+export function emitAbort(socket, sessionId) {
+    socket?.emit("abort_turn", { session_id: sessionId });
+}
+export function emitResolveApproval(socket, sessionId, id, approved, reason) {
+    socket?.emit("resolve_approval", {
+        session_id: sessionId,
+        id,
+        approved,
+        reason,
+    });
+}

package/dist/hooks.d.ts

@@ -0,0 +1,24 @@
+import type { ChatMessage, Envelope } from "./types.js";
+export declare function useConnection(): {
+    connected: boolean;
+    error: string | null;
+};
+export declare function useChat(): {
+    messages: ChatMessage[];
+    send: (text: string) => void;
+    abort: () => void;
+    busy: boolean;
+};
+export declare function useStream(): {
+    content: string;
+    reasoning: string;
+    toolCalls: import("./types.js").ToolCall[];
+    streaming: boolean;
+};
+export declare function useAgentStatus(): import("./types.js").AgentStatus;
+export declare function useApprovals(): {
+    pending: import("./types.js").Approval[];
+    approve: (id: string, reason?: string) => void;
+    reject: (id: string, reason?: string) => void;
+};
+export declare function useEvents(filter?: (e: Envelope) => boolean): Envelope[];

package/dist/hooks.js

@@ -0,0 +1,41 @@
+import { useDigitorn } from "./provider.js";
+export function useConnection() {
+    const { state } = useDigitorn();
+    return { connected: state.connected, error: state.error };
+}
+export function useChat() {
+    const { state, send, abort } = useDigitorn();
+    return {
+        messages: state.messages,
+        send,
+        abort,
+        busy: state.turnActive,
+    };
+}
+export function useStream() {
+    const { state } = useDigitorn();
+    const last = state.messages[state.messages.length - 1];
+    const tail = last && last.role === "assistant" ? last : null;
+    return {
+        content: tail?.content ?? "",
+        reasoning: tail?.reasoning ?? "",
+        toolCalls: tail?.toolCalls ?? [],
+        streaming: !!tail?.streaming,
+    };
+}
+export function useAgentStatus() {
+    const { state } = useDigitorn();
+    return state.status;
+}
+export function useApprovals() {
+    const { state, resolveApproval } = useDigitorn();
+    return {
+        pending: state.approvals,
+        approve: (id, reason) => resolveApproval(id, true, reason),
+        reject: (id, reason) => resolveApproval(id, false, reason),
+    };
+}
+export function useEvents(filter) {
+    const { state } = useDigitorn();
+    return filter ? state.events.filter(filter) : state.events;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { Digitorn, useDigitorn, useTheme, useThumbnailMode, type DigitornProps, type EventListener, type ThemeInfo, type ThemeMode, } from "./provider.js";
+export { useConnection, useChat, useStream, useAgentStatus, useApprovals, useEvents, } from "./hooks.js";
+export { useWorkspace, useWatch, useFile, useFileJson, useWorkspaceEndpoint, } from "./workspace.js";
+export type { WorkspaceApi, WatchMatch, FileChange, DirEntry, } from "./workspace.js";
+export { useAgentSnapshot, type AgentSnapshotCapture, type UseAgentSnapshotOptions, } from "./agentSnapshot.js";
+export { useSharedDoc, type SharedDocOptions } from "./shared.js";
+export { useTopBarActions, switchView, type TopBarAction } from "./topbar.js";
+export { useCompile, type CompileResult } from "./compile.js";
+export { usePreviewAttach, type PreviewAttach } from "./previewAttach.js";
+export type { State, ChatMessage, ToolCall, Approval, AgentStatus, Envelope, SessionInfo, } from "./types.js";
+export { useAgentAction, useAgentActions, agentTarget, type AgentActionArgs, type AgentActionHandler, type AgentActionMap, } from "./agentAction.js";
+export * from "./agentContext.js";
+export { reportProposals, onReviewCommand, type ReviewCommand, type ProposalsState, } from "./reviewMode.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+export { Digitorn, useDigitorn, useTheme, useThumbnailMode, } from "./provider.js";
+export { useConnection, useChat, useStream, useAgentStatus, useApprovals, useEvents, } from "./hooks.js";
+// ── Workspace: the universal, unopinionated primitives ────────────────
+// The agent's edits live in the daemon workdir; these hooks let ANY app read /
+// watch / write whatever state it wants (one JSON, a folder, many files).
+export { useWorkspace, useWatch, useFile, useFileJson, useWorkspaceEndpoint, } from "./workspace.js";
+export { useAgentSnapshot, } from "./agentSnapshot.js";
+// Convenience sugar over the above for the common "one JSON file" case.
+export { useSharedDoc } from "./shared.js";
+// Top bar: let a custom workspace view add its own buttons/menus to the
+// host chrome while it's the active tab, and ask the host to switch views.
+export { useTopBarActions, switchView } from "./topbar.js";
+// One-click rebuild of the current document without an agent turn - the app
+// owns the button (useTopBarActions), this owns the action.
+export { useCompile } from "./compile.js";
+// The agent's build/dev-server preview, checked once on mount and kept live -
+// the primitive a Lovable-style view switches itself on.
+export { usePreviewAttach } from "./previewAttach.js";
+// Expose semantic actions to a driving agent (the preview shim's app_action →
+// digitorn:act event). Standalone — no provider required.
+export { useAgentAction, useAgentActions, agentTarget, } from "./agentAction.js";
+export * from "./agentContext.js";
+export { reportProposals, onReviewCommand, } from "./reviewMode.js";

package/dist/previewAttach.d.ts

@@ -0,0 +1,37 @@
+export interface PreviewAttach {
+    /** Fully authenticated, session-scoped URL - drop it straight into an
+     *  `<iframe src>`. */
+    url: string;
+    /** "static" (a built index.html), "devserver" (a running dev server), or
+     *  "web" (the app's own bundled `web/dist/` UI). */
+    kind: "static" | "devserver" | "web";
+}
+/**
+ * The agent's build/dev-server preview, kept live - the one primitive a
+ * Lovable-style custom view needs to switch itself from "nothing yet" to
+ * "here's what the agent built", and keep switching every time a new build
+ * lands. `undefined` until something is attached.
+ *
+ * Checks once on mount (so reopening a session that already has a build
+ * shows it immediately, not just future ones) and then follows every live
+ * `web_preview:attached` push - no polling either way.
+ *
+ * ```tsx
+ * function LiveBuildPreview() {
+ *   const attach = usePreviewAttach();
+ *   if (!attach) return <Welcome />;              // your own empty state
+ *   return <iframe src={attach.url} title="build" />;
+ * }
+ * ```
+ *
+ * A view isn't limited to swapping what it renders - the same trigger can
+ * drive a full navigation instead:
+ *
+ * ```tsx
+ * const attach = usePreviewAttach();
+ * React.useEffect(() => {
+ *   if (attach) window.location.href = "/built.html";
+ * }, [attach]);
+ * ```
+ */
+export declare function usePreviewAttach(): PreviewAttach | undefined;

package/dist/previewAttach.js

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { useDigitorn } from "./provider.js";
+import { useWorkspaceEndpoint } from "./workspace.js";
+/**
+ * The agent's build/dev-server preview, kept live - the one primitive a
+ * Lovable-style custom view needs to switch itself from "nothing yet" to
+ * "here's what the agent built", and keep switching every time a new build
+ * lands. `undefined` until something is attached.
+ *
+ * Checks once on mount (so reopening a session that already has a build
+ * shows it immediately, not just future ones) and then follows every live
+ * `web_preview:attached` push - no polling either way.
+ *
+ * ```tsx
+ * function LiveBuildPreview() {
+ *   const attach = usePreviewAttach();
+ *   if (!attach) return <Welcome />;              // your own empty state
+ *   return <iframe src={attach.url} title="build" />;
+ * }
+ * ```
+ *
+ * A view isn't limited to swapping what it renders - the same trigger can
+ * drive a full navigation instead:
+ *
+ * ```tsx
+ * const attach = usePreviewAttach();
+ * React.useEffect(() => {
+ *   if (attach) window.location.href = "/built.html";
+ * }, [attach]);
+ * ```
+ */
+export function usePreviewAttach() {
+    const { session, onEvent } = useDigitorn();
+    const { root, headers } = useWorkspaceEndpoint();
+    const [attach, setAttach] = React.useState(undefined);
+    React.useEffect(() => {
+        if (!session.sessionId)
+            return;
+        let cancelled = false;
+        const url = session.previewToken
+            ? `${root}/preview/web-preview?t=${encodeURIComponent(session.previewToken)}`
+            : `${session.baseUrl}/api/apps/${encodeURIComponent(session.appId)}/web-preview?session_id=${encodeURIComponent(session.sessionId)}`;
+        fetch(url, { headers })
+            .then((r) => r.json())
+            .then((d) => {
+            if (cancelled || !d.attached || !d.url)
+                return;
+            setAttach({ url: d.url, kind: d.type ?? "static" });
+        })
+            .catch(() => { });
+        return () => {
+            cancelled = true;
+        };
+    }, [session.sessionId, session.previewToken, root, headers]);
+    React.useEffect(() => onEvent((env) => {
+        const e = env;
+        if (e.type !== "web_preview:attached" || !e.url)
+            return;
+        setAttach({ url: e.url, kind: e.attach_kind ?? "static" });
+    }), [onEvent]);
+    return attach;
+}

package/dist/provider.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+import { type State, type SessionInfo, type Envelope } from "./types.js";
+/** Subscribe to raw event envelopes as they arrive. Returns an unsubscribe. */
+export type EventListener = (env: Envelope) => void;
+/** Light/dark the host is currently showing (resolved from its "auto"). */
+export type ThemeMode = "light" | "dark";
+/** The host theme, mirrored into the preview so an app can match it. */
+export type ThemeInfo = {
+    /** Resolved light or dark - the value an app should adapt to. */
+    mode: ThemeMode;
+    /** Host accent color, when provided (else null). */
+    accent: string | null;
+};
+type DigitornContextValue = {
+    state: State;
+    session: SessionInfo;
+    theme: ThemeInfo;
+    /** True when the app is being rendered for a GALLERY THUMBNAIL capture
+     *  (the host loads the preview URL with `thumbnail=1`). Apps should honor it
+     *  by rendering their content clean and fit-to-view: no chrome/toolbars, no
+     *  interaction affordances, zoomed to the content. A generic primitive - every
+     *  embedded app reads the same flag, nothing app-specific lives in the host. */
+    thumbnail: boolean;
+    send: (text: string) => void;
+    abort: () => void;
+    resolveApproval: (id: string, approved: boolean, reason?: string) => void;
+    onEvent: (listener: EventListener) => () => void;
+};
+export type DigitornProps = Partial<SessionInfo> & {
+    children: React.ReactNode;
+};
+export declare function Digitorn({ children, ...rest }: DigitornProps): React.JSX.Element;
+export declare function useDigitorn(): DigitornContextValue;
+/**
+ * The host theme, mirrored into the preview and kept live. `mode` is "light" or
+ * "dark"; the SDK also sets `data-theme` on the document root, so most apps need
+ * only CSS (`:root[data-theme="dark"] { … }`) and never call this. Reach for it
+ * when an app has its OWN theming API to drive (e.g. Excalidraw's appState.theme).
+ */
+export declare function useTheme(): ThemeInfo;
+/**
+ * True when the app is being rendered for a gallery-thumbnail capture (preview
+ * URL carries `thumbnail=1`). Render clean and fit-to-view - hide chrome/tools,
+ * disable interaction, zoom to the content - so the captured JPEG is just the
+ * document. A shared primitive: every embedded app reads the same flag.
+ */
+export declare function useThumbnailMode(): boolean;
+export {};

package/dist/provider.js

@@ -0,0 +1,182 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { createConnection, emitSendMessage, emitAbort, emitResolveApproval, } from "./connect.js";
+import { reduce } from "./reducer.js";
+import { initialState, } from "./types.js";
+const DigitornContext = React.createContext(null);
+// ── Theme ────────────────────────────────────────────────────────────────
+// The preview iframe adopts the HOST's theme automatically, matching the shared
+// postMessage contract (host side: src/lib/preview-postmessage.ts). The host
+// seeds `?theme=` in the iframe URL and posts `digi:theme-change` on every
+// change; the SDK resolves it to light/dark, applies `data-theme` (+ colorScheme
+// + `--digitorn-accent`) on the document, and exposes it via `useTheme()`. Any
+// app can then style off `:root[data-theme="dark"]` with no per-app wiring - a
+// preview should never look out of place against the surrounding app.
+function resolveMode(raw) {
+    const t = (raw ?? "").toLowerCase();
+    if (t === "dark" || t === "light")
+        return t;
+    // "auto"/"system"/absent → follow the OS preference.
+    return typeof window !== "undefined" &&
+        window.matchMedia?.("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light";
+}
+function initialTheme() {
+    if (typeof window === "undefined")
+        return { mode: "light", accent: null };
+    const q = new URLSearchParams(window.location.search);
+    return { mode: resolveMode(q.get("theme") ?? q.get("mode")), accent: q.get("accent") };
+}
+function applyTheme(t) {
+    if (typeof document === "undefined")
+        return;
+    const root = document.documentElement;
+    root.dataset.theme = t.mode;
+    root.style.colorScheme = t.mode;
+    if (t.accent)
+        root.style.setProperty("--digitorn-accent", t.accent);
+}
+function resolveSession(props) {
+    const q = typeof window !== "undefined"
+        ? new URLSearchParams(window.location.search)
+        : new URLSearchParams();
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    // The preview iframe is served by the daemon at
+    //   /api/apps/{app_id}/sessions/{session_id}/preview/serve/...
+    // so the app + session are recoverable from the path even when the host
+    // only put session_id + token in the query. This lets the SDK self-bootstrap
+    // with zero host wiring beyond the token the preview already carries.
+    const path = typeof window !== "undefined" ? window.location.pathname : "";
+    const m = path.match(/\/api\/apps\/([^/]+)\/sessions\/([^/]+)/);
+    const pathApp = m?.[1] ? decodeURIComponent(m[1]) : "";
+    const pathSid = m?.[2] ? decodeURIComponent(m[2]) : "";
+    return {
+        baseUrl: props.baseUrl ?? q.get("daemon") ?? origin,
+        appId: props.appId ?? q.get("app") ?? q.get("app_id") ?? pathApp,
+        sessionId: props.sessionId ?? q.get("session") ?? q.get("session_id") ?? pathSid,
+        token: props.token ?? q.get("token") ?? undefined,
+        previewToken: props.previewToken ?? q.get("t") ?? undefined,
+    };
+}
+/** Read the gallery-thumbnail capture flag from the preview URL (`thumbnail=1`). */
+function resolveThumbnail() {
+    if (typeof window === "undefined")
+        return false;
+    const v = new URLSearchParams(window.location.search).get("thumbnail");
+    return v === "1" || v === "true";
+}
+function newCorrelationId() {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        return `c-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+}
+export function Digitorn({ children, ...rest }) {
+    const session = React.useMemo(() => resolveSession(rest), []);
+    const thumbnail = React.useMemo(() => resolveThumbnail(), []);
+    const [state, dispatch] = React.useReducer(reduce, initialState);
+    const socketRef = React.useRef(null);
+    const seqRef = React.useRef(0);
+    const listenersRef = React.useRef(new Set());
+    // Theme: seed from the URL / OS, then follow the host live via the shared
+    // `digi:theme-change` postMessage (contract: src/lib/preview-postmessage.ts).
+    const [theme, setTheme] = React.useState(initialTheme);
+    React.useEffect(() => {
+        applyTheme(theme);
+    }, [theme]);
+    React.useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        // Tell the host we're ready to receive pushes; it re-sends the current
+        // theme (and clears its loading state) on `digi:ready`.
+        try {
+            window.parent?.postMessage({ type: "digi:ready" }, "*");
+        }
+        catch {
+            /* cross-origin parent may reject - the URL seed already covered us */
+        }
+        const onMessage = (e) => {
+            const d = e.data;
+            if (!d || d.type !== "digi:theme-change" || !d.theme)
+                return;
+            setTheme({ mode: resolveMode(d.theme.mode), accent: d.theme.accent ?? null });
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, []);
+    React.useEffect(() => {
+        if (!session.sessionId)
+            return;
+        // Always connect: the host uses its JWT, the embedded preview uses its
+        // per-session `?t=` preview token (createConnection puts whichever it has in
+        // the socket auth). Either way the daemon joins us to the session room and
+        // PUSHES `workspace_changes` - the poll in useWatch only wakes if this
+        // socket never connects.
+        const socket = createConnection(session, dispatch, seqRef, (env) => {
+            for (const l of listenersRef.current) {
+                try {
+                    l(env);
+                }
+                catch {
+                    /* a listener throwing must not break the fan-out */
+                }
+            }
+        });
+        socketRef.current = socket;
+        return () => {
+            socket.removeAllListeners();
+            socket.disconnect();
+            socketRef.current = null;
+        };
+    }, [session]);
+    const onEvent = React.useCallback((listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+            listenersRef.current.delete(listener);
+        };
+    }, []);
+    const send = React.useCallback((text) => {
+        const t = text.trim();
+        if (!t)
+            return;
+        const cid = newCorrelationId();
+        dispatch({ type: "local_user", content: t, correlationId: cid });
+        emitSendMessage(socketRef.current, session.sessionId, t, cid);
+    }, [session.sessionId]);
+    const abort = React.useCallback(() => {
+        emitAbort(socketRef.current, session.sessionId);
+    }, [session.sessionId]);
+    const resolveApproval = React.useCallback((id, approved, reason) => {
+        emitResolveApproval(socketRef.current, session.sessionId, id, approved, reason);
+    }, [session.sessionId]);
+    const value = React.useMemo(() => ({ state, session, theme, thumbnail, send, abort, resolveApproval, onEvent }), [state, session, theme, thumbnail, send, abort, resolveApproval, onEvent]);
+    return (_jsx(DigitornContext.Provider, { value: value, children: children }));
+}
+export function useDigitorn() {
+    const ctx = React.useContext(DigitornContext);
+    if (!ctx) {
+        throw new Error("useDigitorn must be used inside <Digitorn>");
+    }
+    return ctx;
+}
+/**
+ * The host theme, mirrored into the preview and kept live. `mode` is "light" or
+ * "dark"; the SDK also sets `data-theme` on the document root, so most apps need
+ * only CSS (`:root[data-theme="dark"] { … }`) and never call this. Reach for it
+ * when an app has its OWN theming API to drive (e.g. Excalidraw's appState.theme).
+ */
+export function useTheme() {
+    return useDigitorn().theme;
+}
+/**
+ * True when the app is being rendered for a gallery-thumbnail capture (preview
+ * URL carries `thumbnail=1`). Render clean and fit-to-view - hide chrome/tools,
+ * disable interaction, zoom to the content - so the captured JPEG is just the
+ * document. A shared primitive: every embedded app reads the same flag.
+ */
+export function useThumbnailMode() {
+    return useDigitorn().thumbnail;
+}

package/dist/reducer.d.ts

@@ -0,0 +1,14 @@
+import type { State, Envelope } from "./types.js";
+export type Action = {
+    type: "connected";
+} | {
+    type: "disconnected";
+} | {
+    type: "local_user";
+    content: string;
+    correlationId: string;
+} | {
+    type: "event";
+    env: Envelope;
+};
+export declare function reduce(state: State, action: Action): State;