tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/tui/mirror/resize-transaction.js

@@ -0,0 +1,221 @@
+import { createOptimisticProjection, deriveOptimisticProjection, enqueueOptimisticOperation, reconcileOptimisticOperation, replaceCommittedProjection, } from "@tmux-ide/core";
+function positiveCells(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${label} must be a positive safe integer`);
+    }
+    return value;
+}
+function nonEmpty(value, label) {
+    if (value.length === 0)
+        throw new TypeError(`${label} must not be empty`);
+    return value;
+}
+function sameTarget(state, observation) {
+    return (state.operationId === observation.operationId &&
+        state.workspaceName === observation.workspaceName &&
+        state.semanticPaneId === observation.semanticPaneId &&
+        state.axis === observation.axis);
+}
+/**
+ * Renderer-local pane-resize transaction.
+ *
+ * Pointer motion only changes the preview state. Release authors exactly one
+ * semantic intent and keeps that preview visible until the matching observed
+ * operation settles or rejects. The controller owns no timers, transport, or
+ * rendering effects beyond the functions supplied by its caller.
+ */
+export class ResizeTransactionController {
+    #options;
+    #state = Object.freeze({
+        phase: "idle",
+        canonicalCells: null,
+        outcome: null,
+    });
+    #cancelTimeout = null;
+    #projection = null;
+    #revision = 0;
+    #disposed = false;
+    constructor(options) {
+        if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+            throw new RangeError("resize transaction timeout must be positive");
+        }
+        this.#options = options;
+    }
+    state() {
+        return this.#state;
+    }
+    begin(input) {
+        // A second pointer-down must not silently retire an already-submitted
+        // operation (or replace a gesture whose pointer is still captured).
+        if (this.#disposed || this.#state.phase !== "idle")
+            return false;
+        this.#clearTimeout();
+        const authorityGeneration = nonEmpty(input.authorityGeneration, "authorityGeneration");
+        const workspaceName = nonEmpty(input.workspaceName, "workspaceName");
+        const semanticPaneId = nonEmpty(input.semanticPaneId, "semanticPaneId");
+        const canonicalCells = positiveCells(input.canonicalCells, "canonicalCells");
+        this.#projection = createOptimisticProjection({
+            generation: authorityGeneration,
+            revision: this.#revision,
+            value: canonicalCells,
+        });
+        this.#emit({
+            phase: "dragging",
+            authorityGeneration,
+            workspaceName,
+            semanticPaneId,
+            axis: input.axis,
+            canonicalCells,
+            previewCells: canonicalCells,
+            startedAt: this.#options.now(),
+        });
+        return true;
+    }
+    /** Purely local preview update. It never calls submit or schedules work. */
+    move(previewCells) {
+        if (this.#state.phase !== "dragging")
+            return false;
+        const next = positiveCells(previewCells, "previewCells");
+        if (next === this.#state.previewCells)
+            return false;
+        this.#emit({ ...this.#state, previewCells: next });
+        return true;
+    }
+    /**
+     * Submit once. Duplicate physical release/up/drop events return the existing
+     * operation id without authoring another mutation.
+     */
+    release() {
+        if (this.#state.phase === "pending")
+            return this.#state.operationId;
+        if (this.#state.phase !== "dragging")
+            return null;
+        const dragging = this.#state;
+        if (dragging.previewCells === dragging.canonicalCells) {
+            this.#emit({ phase: "idle", canonicalCells: dragging.canonicalCells, outcome: null });
+            return null;
+        }
+        const operationId = nonEmpty(this.#options.operationId(), "operationId");
+        const submittedAt = this.#options.now();
+        if (!this.#projection)
+            throw new Error("resize projection is unavailable");
+        this.#projection = enqueueOptimisticOperation(this.#projection, {
+            operationId,
+            intent: dragging.previewCells,
+            acceptedAtMs: submittedAt,
+            deadlineAtMs: submittedAt + this.#options.timeoutMs,
+        });
+        const pending = {
+            ...dragging,
+            phase: "pending",
+            operationId,
+            previewCells: deriveOptimisticProjection(this.#projection, {
+                predict: (_committed, cells) => cells,
+            }),
+            submittedAt,
+        };
+        this.#emit(pending);
+        this.#cancelTimeout = this.#options.schedule(() => this.#revertTimedOut(operationId), this.#options.timeoutMs);
+        try {
+            this.#options.submit({
+                operationId,
+                intent: {
+                    verb: "workspace.pane.resize",
+                    workspaceName: pending.workspaceName,
+                    semanticPaneId: pending.semanticPaneId,
+                    axis: pending.axis,
+                    cells: pending.previewCells,
+                },
+            });
+        }
+        catch (error) {
+            this.#revert(operationId, {
+                kind: "submit-failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return operationId;
+    }
+    observeLayout(observation) {
+        return this.#settle(observation, "layout");
+    }
+    reject(rejection) {
+        return this.#revert(rejection.operationId, {
+            kind: "rejected",
+            code: rejection.code,
+            message: rejection.message,
+        });
+    }
+    /** Escape/cancel is only meaningful before release. */
+    cancelDrag() {
+        if (this.#state.phase !== "dragging")
+            return false;
+        const canonicalCells = this.#state.canonicalCells;
+        this.#emit({ phase: "idle", canonicalCells, outcome: null });
+        return true;
+    }
+    dispose() {
+        this.#disposed = true;
+        this.retire();
+    }
+    /** Retire one runtime lane without permanently disposing the controller. */
+    retire() {
+        this.#clearTimeout();
+        this.#projection = null;
+        if (this.#state.phase !== "idle" || this.#state.canonicalCells !== null) {
+            this.#emit({ phase: "idle", canonicalCells: null, outcome: null });
+        }
+    }
+    #settle(observation, source) {
+        if (this.#state.phase !== "pending" ||
+            !sameTarget(this.#state, observation) ||
+            !this.#projection?.pending.some((operation) => operation.operationId === observation.operationId))
+            return false;
+        const cells = positiveCells(observation.cells, "observed cells");
+        const operationId = this.#state.operationId;
+        if (!this.#projection)
+            return false;
+        this.#revision += 1;
+        this.#projection = replaceCommittedProjection(this.#projection, {
+            generation: this.#projection.committed.generation,
+            revision: this.#revision,
+            value: cells,
+        }, { observedOperationIds: [operationId], nowMs: this.#options.now() });
+        this.#clearTimeout();
+        this.#emit({
+            phase: "idle",
+            canonicalCells: cells,
+            outcome: { kind: "settled", operationId, source, cells },
+        });
+        return true;
+    }
+    #revertTimedOut(operationId) {
+        this.#cancelTimeout = null;
+        this.#revert(operationId, { kind: "timed-out", timeoutMs: this.#options.timeoutMs });
+    }
+    #revert(operationId, reason) {
+        if (this.#state.phase !== "pending" ||
+            this.#state.operationId !== operationId ||
+            !this.#projection?.pending.some((operation) => operation.operationId === operationId))
+            return false;
+        if (this.#projection) {
+            this.#projection = reconcileOptimisticOperation(this.#projection, operationId, reason.kind === "timed-out" ? "timed-out" : "rejected");
+        }
+        const canonicalCells = this.#state.canonicalCells;
+        this.#clearTimeout();
+        this.#emit({
+            phase: "idle",
+            canonicalCells,
+            outcome: { kind: "reverted", operationId, reason },
+        });
+        return true;
+    }
+    #clearTimeout() {
+        this.#cancelTimeout?.();
+        this.#cancelTimeout = null;
+    }
+    #emit(state) {
+        this.#state = Object.freeze(state);
+        this.#options.onState(this.#state);
+    }
+}

package/packages/daemon/dist/tui/mirror/rich-placement-projection.d.ts

@@ -0,0 +1,64 @@
+import type { TerminalReplicaPlacement, TerminalReplicaSnapshot, WidgetMarker } from "@tmux-ide/contracts";
+/** A rectangle in canonical terminal-cell coordinates. */
+export interface TerminalCellRect {
+    readonly row: number;
+    readonly column: number;
+    readonly rows: number;
+    readonly columns: number;
+}
+/**
+ * The visible portion of a terminal replica. The origin permits future
+ * scroll/crop hosts without changing placement identity or projection rules.
+ */
+export type RichPlacementViewport = TerminalCellRect;
+/** Geometry suitable for an absolutely positioned host renderable. */
+export interface RichPlacementHostRect {
+    readonly top: number;
+    readonly left: number;
+    readonly height: number;
+    readonly width: number;
+}
+export interface RichPlacementClipping {
+    readonly top: boolean;
+    readonly right: boolean;
+    readonly bottom: boolean;
+    readonly left: boolean;
+}
+/**
+ * Semantic delivery currently authenticates placement identity and geometry,
+ * but does not carry the widget payload itself. Keep that limitation typed so
+ * hosts can render a capability-honest fallback instead of inventing content.
+ */
+export interface RichPlacementFallbackMetadata {
+    readonly kind: "authenticated-content-unavailable";
+    readonly widgetId: string;
+    readonly placementKind: string;
+    readonly contentDigest: string;
+}
+export interface RichPlacementProjection {
+    /** Stable across content, geometry and viewport changes. */
+    readonly renderableId: string;
+    readonly paneId: string;
+    readonly placementId: string;
+    readonly placement: TerminalReplicaPlacement;
+    /** Canonical clipped rectangle, or null when wholly outside the viewport. */
+    readonly clipped: TerminalCellRect | null;
+    /** Viewport-local OpenTUI coordinates, or null when not visible. */
+    readonly hostRect: RichPlacementHostRect | null;
+    readonly clipping: RichPlacementClipping;
+    readonly visible: boolean;
+    /** Adapter for the existing typed widget-fallback resolver. */
+    readonly marker: WidgetMarker;
+    readonly fallback: RichPlacementFallbackMetadata;
+}
+/**
+ * Project every canonical rich placement into a bounded host viewport.
+ *
+ * The array retains canonical order. `renderableId` deliberately excludes the
+ * digest and rectangle, allowing OpenTUI to retain the same renderable when
+ * content updates or tmux resizes it. Duplicate protocol ids are disambiguated
+ * by their stable occurrence within that id group.
+ */
+export declare function projectRichPlacements(paneId: string, placements: readonly TerminalReplicaPlacement[], viewport: RichPlacementViewport): readonly RichPlacementProjection[];
+/** Convenience projection for the full current terminal grid. */
+export declare function projectSnapshotRichPlacements(paneId: string, snapshot: Pick<TerminalReplicaSnapshot, "cols" | "rows" | "placements">, viewport?: RichPlacementViewport): readonly RichPlacementProjection[];

package/packages/daemon/dist/tui/mirror/rich-placement-projection.js

@@ -0,0 +1,80 @@
+/**
+ * Project every canonical rich placement into a bounded host viewport.
+ *
+ * The array retains canonical order. `renderableId` deliberately excludes the
+ * digest and rectangle, allowing OpenTUI to retain the same renderable when
+ * content updates or tmux resizes it. Duplicate protocol ids are disambiguated
+ * by their stable occurrence within that id group.
+ */
+export function projectRichPlacements(paneId, placements, viewport) {
+    const occurrenceById = new Map();
+    return placements.map((placement) => {
+        const occurrence = occurrenceById.get(placement.id) ?? 0;
+        occurrenceById.set(placement.id, occurrence + 1);
+        return projectRichPlacement(paneId, placement, viewport, occurrence);
+    });
+}
+/** Convenience projection for the full current terminal grid. */
+export function projectSnapshotRichPlacements(paneId, snapshot, viewport = {
+    row: 0,
+    column: 0,
+    rows: snapshot.rows,
+    columns: snapshot.cols,
+}) {
+    return projectRichPlacements(paneId, snapshot.placements, viewport);
+}
+function projectRichPlacement(paneId, placement, viewport, occurrence) {
+    const clipped = intersection(placement, viewport);
+    const marker = Object.freeze({
+        id: placement.id,
+        args: Object.freeze({ semanticPlacement: Object.freeze({ ...placement }) }),
+        lineIndex: placement.row,
+    });
+    const fallback = Object.freeze({
+        kind: "authenticated-content-unavailable",
+        widgetId: placement.id,
+        placementKind: placement.kind,
+        contentDigest: placement.contentDigest,
+    });
+    return Object.freeze({
+        renderableId: placementRenderableId(paneId, placement.id, occurrence),
+        paneId,
+        placementId: placement.id,
+        placement,
+        clipped,
+        hostRect: clipped === null
+            ? null
+            : Object.freeze({
+                top: clipped.row - viewport.row,
+                left: clipped.column - viewport.column,
+                height: clipped.rows,
+                width: clipped.columns,
+            }),
+        clipping: Object.freeze({
+            top: placement.row < viewport.row,
+            right: rectEnd(placement.column, placement.columns) > rectEnd(viewport.column, viewport.columns),
+            bottom: rectEnd(placement.row, placement.rows) > rectEnd(viewport.row, viewport.rows),
+            left: placement.column < viewport.column,
+        }),
+        visible: clipped !== null,
+        marker,
+        fallback,
+    });
+}
+function placementRenderableId(paneId, placementId, occurrence) {
+    // Length prefixes make this collision-free even when ids contain separators.
+    return `rich-placement:${paneId.length}:${paneId}:${placementId.length}:${placementId}:${occurrence}`;
+}
+function intersection(placement, viewport) {
+    const row = Math.max(placement.row, viewport.row);
+    const column = Math.max(placement.column, viewport.column);
+    const endRow = Math.min(rectEnd(placement.row, placement.rows), rectEnd(viewport.row, viewport.rows));
+    const endColumn = Math.min(rectEnd(placement.column, placement.columns), rectEnd(viewport.column, viewport.columns));
+    if (endRow <= row || endColumn <= column)
+        return null;
+    return Object.freeze({ row, column, rows: endRow - row, columns: endColumn - column });
+}
+function rectEnd(origin, length) {
+    const end = origin + length;
+    return Number.isSafeInteger(end) ? end : Number.MAX_SAFE_INTEGER;
+}

package/packages/daemon/dist/tui/mirror/runtime/application-appearance-owner.d.ts

@@ -0,0 +1,22 @@
+import { type Accessor } from "solid-js";
+import { type AppConfig } from "../../../lib/app-config.ts";
+import { type SemanticThemeSnapshot, type TerminalPaletteProjection, type ThemeModeSource } from "../theme.ts";
+import type { ApplicationTerminalPaletteOwner, ApplicationTerminalPaletteSnapshot } from "./application-terminal-palette-owner.ts";
+export interface ApplicationAppearanceOwner {
+    /** One publication boundary for every app-owned colour consumer. */
+    readonly appearance: Accessor<ApplicationAppearanceSnapshot>;
+    readonly note: Accessor<string | null>;
+    readonly setNote: (note: string | null) => void;
+    readonly theme: Accessor<SemanticThemeSnapshot>;
+    readonly palette: Accessor<TerminalPaletteProjection>;
+    readonly hostPalette: Accessor<ApplicationTerminalPaletteSnapshot>;
+    readonly setTransientNote: (note: string | null) => void;
+    readonly cycleTheme: () => void;
+    readonly dispose: () => void;
+}
+export interface ApplicationAppearanceSnapshot {
+    readonly generation: number;
+    readonly theme: SemanticThemeSnapshot;
+    readonly palette: TerminalPaletteProjection;
+}
+export declare function createAppearanceOwner(config: AppConfig, renderer: ThemeModeSource, terminalPaletteOwner: ApplicationTerminalPaletteOwner): ApplicationAppearanceOwner;

package/packages/daemon/dist/tui/mirror/runtime/application-appearance-owner.js

@@ -0,0 +1,79 @@
+import { batch, createSignal } from "solid-js";
+import { updateAppConfig } from "../../../lib/app-config.js";
+import { DARK_THEME, createSemanticThemeStore, createTerminalPaletteProjection, deriveSystemVisualHostDefaults, } from "../theme.js";
+import { createApplicationTransientNoteOwner } from "./application-transient-note-owner.js";
+function hostDefaults(snapshot) {
+    if (snapshot.availability !== "available")
+        return null;
+    return deriveSystemVisualHostDefaults(snapshot);
+}
+export function createAppearanceOwner(config, renderer, terminalPaletteOwner) {
+    const initialHostPalette = terminalPaletteOwner.getSnapshot();
+    const store = createSemanticThemeStore(config.theme, {
+        rendererMode: renderer.themeMode,
+        hostDefaults: hostDefaults(initialHostPalette),
+    });
+    const initialTheme = store.getSnapshot();
+    // Mirrored programs are foreign terminal applications, not semantic app
+    // components. They are launched with tmux-ide's dark terminal contract and
+    // may retain default-colour cells indefinitely. Keep that cell contract
+    // stable while app-owned overlays continue to follow the selected theme.
+    const terminalCellDefaults = DARK_THEME;
+    const [appearance, setAppearance] = createSignal(Object.freeze({
+        generation: 0,
+        theme: initialTheme,
+        palette: createTerminalPaletteProjection(initialTheme, terminalCellDefaults),
+    }));
+    const publishTheme = () => {
+        const nextTheme = store.getSnapshot();
+        setAppearance((current) => Object.freeze({
+            generation: current.generation + 1,
+            theme: nextTheme,
+            palette: createTerminalPaletteProjection(nextTheme, terminalCellDefaults),
+        }));
+    };
+    const stopTheme = store.subscribe(publishTheme);
+    const stopRendererTheme = store.followRendererThemeMode(renderer);
+    const theme = () => appearance().theme;
+    const palette = () => appearance().palette;
+    const [hostPalette, setHostPalette] = createSignal(initialHostPalette);
+    const stopHostPalette = terminalPaletteOwner.subscribe(() => {
+        const next = terminalPaletteOwner.getSnapshot();
+        batch(() => {
+            setHostPalette(next);
+            // The store publishes at most one complete semantic snapshot. Explicit
+            // dark/light settings retain these defaults without changing colours;
+            // switching back to system applies the latest valid host palette.
+            store.setHostDefaults(hostDefaults(next));
+        });
+    });
+    const [note, setNote] = createSignal(null);
+    const notice = createApplicationTransientNoteOwner({
+        read: note,
+        write: setNote,
+    });
+    const cycleTheme = () => {
+        const order = ["dark", "light", "system"];
+        const next = order[(order.indexOf(theme().setting) + 1) % order.length];
+        store.setMode(next);
+        updateAppConfig({ theme: { mode: next } });
+        notice.publish(`theme → ${next}`);
+    };
+    return {
+        appearance,
+        note,
+        setNote,
+        theme,
+        palette,
+        hostPalette,
+        setTransientNote: notice.publish,
+        cycleTheme,
+        dispose() {
+            stopTheme();
+            stopRendererTheme();
+            stopHostPalette();
+            terminalPaletteOwner.dispose();
+            notice.dispose();
+        },
+    };
+}

package/packages/daemon/dist/tui/mirror/runtime/application-bootstrap.d.ts

@@ -0,0 +1,61 @@
+import type { TuiApplicationLifecycle, TuiShutdownReport } from "./application-lifecycle.ts";
+export interface TuiBootstrapRenderer {
+    destroy(): void | Promise<void>;
+}
+export interface TuiMountedRoot<Root> {
+    readonly root: Root;
+    /** Input owners and root subscriptions have mounted when this resolves. */
+    readonly ready?: Promise<void>;
+    /** Unsubscribe/close root-owned resources before native renderer teardown. */
+    readonly close?: () => void | Promise<void>;
+}
+export interface TuiBootstrapContext<Args, Config, Renderer extends TuiBootstrapRenderer> {
+    readonly args: Args;
+    readonly config: Config;
+    readonly renderer: Renderer;
+    readonly lifecycle: TuiApplicationLifecycle;
+}
+export interface TuiApplicationBootstrapOptions<Args, Config, Renderer extends TuiBootstrapRenderer, Root> {
+    readonly argv: readonly string[];
+    readonly parseArgs: (argv: readonly string[]) => Args | Promise<Args>;
+    readonly loadConfig: (args: Args) => Config | Promise<Config>;
+    readonly createRenderer: (input: {
+        args: Args;
+        config: Config;
+    }) => Renderer | Promise<Renderer>;
+    readonly createLifecycle: (renderer: Renderer) => TuiApplicationLifecycle;
+    readonly mountRoot: (context: TuiBootstrapContext<Args, Config, Renderer>) => TuiMountedRoot<Root> | Promise<TuiMountedRoot<Root>>;
+    readonly publishReady: (context: TuiBootstrapContext<Args, Config, Renderer> & {
+        readonly root: Root;
+    }) => void | Promise<void>;
+}
+export interface TuiApplicationHandle<Args, Config, Renderer, Root> {
+    readonly args: Args;
+    readonly config: Config;
+    readonly renderer: Renderer;
+    readonly root: Root;
+    readonly lifecycle: TuiApplicationLifecycle;
+    shutdown(): Promise<TuiShutdownReport>;
+}
+export interface TuiRootFailureObserverOptions {
+    /** Break the bootstrap readiness wait with the original render failure. */
+    readonly rejectReadiness: (error: unknown) => void;
+    /** Record the failure before renderer teardown can remove diagnostics. */
+    readonly reportFailure?: (error: unknown) => void;
+    /** Retire application resources and the native renderer. */
+    readonly shutdown: () => void | Promise<unknown>;
+}
+/**
+ * Join a framework root's asynchronous failure to the bootstrap lifecycle.
+ *
+ * OpenTUI's Solid `render()` returns a root Promise independently from the
+ * readiness Promise awaited below. A rejected root must therefore reject that
+ * gate explicitly; merely shutting the renderer down strands bootstrap on a
+ * never-settling readiness wait and leaves the host process alive.
+ */
+export declare function observeTuiRootFailure(root: PromiseLike<unknown>, options: TuiRootFailureObserverOptions): void;
+/**
+ * Thin, dependency-injected boot sequence. No config, daemon, Solid, or native
+ * renderer work occurs at module evaluation time; each boundary is testable.
+ */
+export declare function startTuiApplication<Args, Config, Renderer extends TuiBootstrapRenderer, Root>(options: TuiApplicationBootstrapOptions<Args, Config, Renderer, Root>): Promise<TuiApplicationHandle<Args, Config, Renderer, Root>>;

package/packages/daemon/dist/tui/mirror/runtime/application-bootstrap.js

@@ -0,0 +1,51 @@
+/**
+ * Join a framework root's asynchronous failure to the bootstrap lifecycle.
+ *
+ * OpenTUI's Solid `render()` returns a root Promise independently from the
+ * readiness Promise awaited below. A rejected root must therefore reject that
+ * gate explicitly; merely shutting the renderer down strands bootstrap on a
+ * never-settling readiness wait and leaves the host process alive.
+ */
+export function observeTuiRootFailure(root, options) {
+    void Promise.resolve(root).catch(async (error) => {
+        options.reportFailure?.(error);
+        options.rejectReadiness(error);
+        await options.shutdown();
+    });
+}
+/**
+ * Thin, dependency-injected boot sequence. No config, daemon, Solid, or native
+ * renderer work occurs at module evaluation time; each boundary is testable.
+ */
+export async function startTuiApplication(options) {
+    const args = await options.parseArgs(options.argv);
+    const config = await options.loadConfig(args);
+    const renderer = await options.createRenderer({ args, config });
+    const lifecycle = options.createLifecycle(renderer);
+    const context = {
+        args,
+        config,
+        renderer,
+        lifecycle,
+    };
+    try {
+        const mounted = await options.mountRoot(context);
+        if (mounted.close)
+            lifecycle.registerCloser("application-root", mounted.close);
+        await mounted.ready;
+        if (!lifecycle.accepting) {
+            await lifecycle.shutdown("host");
+            throw new Error("OpenTUI root stopped before reaching input readiness");
+        }
+        await options.publishReady({ ...context, root: mounted.root });
+        return {
+            ...context,
+            root: mounted.root,
+            shutdown: () => lifecycle.shutdown("host"),
+        };
+    }
+    catch (error) {
+        await lifecycle.shutdown("bootstrap-error");
+        throw error;
+    }
+}

package/packages/daemon/dist/tui/mirror/runtime/application-generation-starter.d.ts

@@ -0,0 +1,26 @@
+import type { ApplicationShellBinding } from "./application-shell-binding.ts";
+import type { OpenTuiSessionOwner } from "./open-tui-session-owner.ts";
+import type { ApplicationSessionFocusOwner } from "./application-session-focus-owner.ts";
+import type { OpenTuiGenerationHostSnapshot } from "./open-tui-generation-host.ts";
+type Source = "keyboard" | "mouse";
+export interface ApplicationGenerationStartResult {
+    readonly opened: boolean;
+    readonly sessionName: string;
+    readonly generationKey: string | null;
+    readonly failure?: "superseded" | "attach-rejected" | "attach-failed" | "generation-not-ready";
+}
+/** Stable identity for one live semantic/input generation. */
+export declare function applicationGenerationNavigationKey(snapshot: OpenTuiGenerationHostSnapshot | null): string | null;
+export declare function createApplicationGenerationStarter(options: Readonly<{
+    binding: Pick<ApplicationShellBinding, "openSession">;
+    sessionOwner: () => OpenTuiSessionOwner;
+    focusOwner: () => ApplicationSessionFocusOwner | null;
+    setNote: (note: string | null) => void;
+    setSurface: (surface: "terminals") => void;
+}>): (sessionName: string, workspacePrepared?: boolean, source?: Source, focusFirstPane?: boolean) => Promise<ApplicationGenerationStartResult>;
+export declare function createApplicationAgentNavigator(options: {
+    readonly startGeneration: ReturnType<typeof createApplicationGenerationStarter>;
+    readonly sessionOwner: () => OpenTuiSessionOwner;
+    readonly selectPane: (paneId: string) => void;
+}): (sessionName: string, paneId: string, source?: Source) => Promise<boolean>;
+export {};