@opengeni/react 0.29.0 → 0.32.1

package/dist/hooks/use-workspace-capture.d.ts

@@ -0,0 +1,49 @@
+import type { SessionEvent, WorkspaceCaptureDegradedReason, WorkspaceCaptureManifest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseWorkspaceCaptureOptions = ClientOverride & {
+    /** Live event log (usually `useSessionEvents().events`) — a
+     *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
+    events?: SessionEvent[] | undefined;
+    /** Hold off the mount fetch (e.g. the workbench panel is collapsed). Default true. */
+    enabled?: boolean | undefined;
+};
+export type UseWorkspaceCaptureResult = {
+    /** The resolved manifest (tree index + per-repo diffs + file refs), or null when
+     *  no capture exists (falls back to the live/wake path — status quo). */
+    capture: WorkspaceCaptureManifest | null;
+    /** The loaded capture's monotonic revision, or null when unavailable. */
+    revision: number | null;
+    /** When the loaded capture was taken (ISO), for the "as of <time>" source badge. */
+    capturedAt: string | null;
+    /** Whether a capture is available at all (the `{available:false}` discriminator). */
+    available: boolean;
+    /** Why the newest durable revision is unavailable. null means no capture has
+     *  been attempted yet; a value means capture explicitly failed closed and
+     *  consumers must use the live box rather than trust an incomplete snapshot. */
+    degradedReason: WorkspaceCaptureDegradedReason | null;
+    /** The changed-file count from the capture's stats, resolved on the FIRST GET
+     *  (from the response's top-level `stats`, before any manifest-URL hop). null
+     *  until that first resolve; 0 when no capture exists. This is the pre-paint
+     *  "changes exist?" signal the dock uses to pick its default tab with no
+     *  embedder events-at-mount contract. */
+    fileCount: number | null;
+    /** A newer revision has been ANNOUNCED than the one currently loaded (a refresh
+     *  is in flight or pending). M5's source badge can show a subtle "updating…". */
+    isStale: boolean;
+    loading: boolean;
+    error: Error | null;
+    /** Force a re-fetch of the latest capture. */
+    refresh: () => Promise<void>;
+};
+/**
+ * The cold-paint data source: fetch the latest turn-end workspace capture with a
+ * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
+ * first paint). The manifest is served inline in the common
+ * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
+ *
+ * Subscribes to the live event log: a `workspace.revision.captured` for a revision
+ * newer than the one loaded triggers a background refresh (stale-while-revalidate).
+ * `{available:false}` is a value, never a crash — consumers fall back to the
+ * live/wake path exactly as before the capture feature existed.
+ */
+export declare function useWorkspaceCapture(sessionId: string | null | undefined, options?: UseWorkspaceCaptureOptions): UseWorkspaceCaptureResult;

package/dist/hooks/use-workspace-edit.d.ts

@@ -0,0 +1,73 @@
+import { type ClientOverride } from "../provider";
+/**
+ * The wake-on-edit state machine. This hook owns the logic and the UI renders
+ * its result. States are explicit and exhaustive:
+ *
+ *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
+ *   buffering         — local edits buffered; the box is not warm and no warm is
+ *                       yet in flight (the host has not attached).
+ *   warming           — edits buffered; the box is actively coming up (the host
+ *                       attached a viewer in response to `wantsWarm`).
+ *   flushing          — the box is warm; the guarded write is in flight.
+ *   flushed           — the buffer was written to the live box.
+ *   conflict          — the live file diverged from the captured base between
+ *                       capture and flush; NO write was issued (C2).
+ *   readonly-offline  — a self-hosted machine that is offline; read-only, no wake.
+ */
+export type WorkspaceEditState = "viewing-cold" | "buffering" | "warming" | "flushing" | "flushed" | "conflict" | "readonly-offline";
+export type WorkspaceEditConflict = {
+    path: string;
+    /** The capture-served content the edit was based on. */
+    base: string;
+    /** The live content found on the box at flush time (what would be overwritten). */
+    live: string;
+};
+export type UseWorkspaceEditOptions = ClientOverride & {
+    /** The file being edited (workspace-relative). null disables the machine. */
+    path?: string | null | undefined;
+    /** The capture-served content loaded into the editor — the flush base (C2). */
+    baseContent?: string | null | undefined;
+    /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
+    liveness?: string | undefined;
+    /** True while the host is actively warming the box (attach in flight, not warm
+     *  yet) — lifts `buffering` → `warming`. The host sets this after acting on
+     *  `wantsWarm` (e.g. flipping `attachFiles` on `useSessionCapabilities`). */
+    warming?: boolean | undefined;
+    /** A self-hosted machine that is OFFLINE: read-only, no remote wake possible. */
+    offline?: boolean | undefined;
+    /** Called once when the first cold edit needs the box warmed — the host wires
+     *  this to its liveness primitive (flip `attachFiles`/`attachViewer`). */
+    onWarmRequested?: (() => void) | undefined;
+};
+export type UseWorkspaceEditResult = {
+    state: WorkspaceEditState;
+    /** The editor should be read-only (self-hosted offline). */
+    readOnly: boolean;
+    /** The current buffered content (null = no local edit yet). */
+    buffer: string | null;
+    /** The host should warm the box (flip its attach primitive). Latches true from
+     *  the first cold edit until the buffer flushes or is discarded. */
+    wantsWarm: boolean;
+    /** Record an edit from the editor (idempotent per identical content). */
+    edit: (content: string) => void;
+    /** The conflict detail when `state === "conflict"`. */
+    conflict: WorkspaceEditConflict | null;
+    /** Flush the buffer regardless of the base guard (the user chose "overwrite"
+     *  from the conflict bar). Writes last-writer-wins. */
+    overwrite: () => Promise<void>;
+    /** Drop the local buffer and return to viewing the snapshot. */
+    discard: () => void;
+    error: Error | null;
+};
+/**
+ * Cold-editing without a spinner: the editor opens instantly from the capture,
+ * the first keystroke buffers locally AND signals the host to warm the box, and on
+ * warm the buffer flushes IF the live file still matches the captured base — else a
+ * non-blocking conflict is surfaced and nothing is overwritten.
+ *
+ * The base guard compares the live content at flush time against `baseContent`
+ * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
+ * the design specifies — M1 leaves `baseHash` null, so the loaded content IS the
+ * authoritative base — and avoids async Web Crypto in the render path.
+ */
+export declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;

package/dist/hooks/use-workspace-sessions.d.ts

@@ -0,0 +1,30 @@
+import type { Session } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseWorkspaceSessionsOptions = ClientOverride & {
+    limit?: number | undefined;
+    parentSessionId?: string | null | undefined;
+    cursor?: string | undefined;
+    search?: string | undefined;
+    /** Return only the complete personal pinned projection. */
+    pinsOnly?: boolean | undefined;
+    /** Refresh interval (ms) for fleet/manager views. Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseWorkspaceSessionsResult = {
+    /**
+     * All visible rows, with pins first. This preserves the pre-pinning hook
+     * contract for consumers that only read `sessions`.
+     */
+    sessions: Session[];
+    /** The complete personal pinned section, also present in `sessions`. */
+    pinned: Session[];
+    /** True when the server omitted older pins from its bounded pinned section. */
+    pinnedTruncated: boolean;
+    nextCursor: string | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** List the workspace's sessions — the data behind fleet and manager views. */
+export declare function useWorkspaceSessions(options?: UseWorkspaceSessionsOptions): UseWorkspaceSessionsResult;

package/dist/hooks/use-workspaces.d.ts

@@ -0,0 +1,22 @@
+import type { CreateWorkspaceRequest, UpdateWorkspaceRequest, Workspace } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseWorkspacesOptions = Pick<ClientOverride, "client"> & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseWorkspacesResult = {
+    workspaces: Workspace[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateWorkspaceRequest) => Promise<Workspace | null>;
+    update: (workspaceId: string, request: UpdateWorkspaceRequest) => Promise<Workspace | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * The caller's workspaces (workspace switchers, onboarding). Not scoped to
+ * the provider's workspace, so it only needs the client.
+ */
+export declare function useWorkspaces(options?: UseWorkspacesOptions): UseWorkspacesResult;

package/dist/human-input.d.ts

@@ -0,0 +1,18 @@
+import type { HumanInputQuestion, SessionEvent } from "@opengeni/sdk";
+/** Minimal actionable request shape available from the durable event log. */
+export type PendingHumanInputRequest = {
+    id: string;
+    turnId: string | null;
+    questions: HumanInputQuestion[];
+    allowSkip: boolean;
+    expiresAt: string | null;
+};
+/** Parse one generic `session.humanInput.requested` event defensively. */
+export declare function humanInputRequestFromEvent(event: Pick<SessionEvent, "type" | "payload" | "turnId">): PendingHumanInputRequest | null;
+/**
+ * Fold a durable event log into the structured requests that are actionable
+ * now. Responses remove one request; a terminal owning turn clears any
+ * unresolved requests that died with it. Replaying history cannot resurrect a
+ * previously answered card.
+ */
+export declare function projectPendingHumanInputRequests(events: SessionEvent[]): PendingHumanInputRequest[];