@bendyline/docblocks 2.6.1 → 2.7.0

package/dist/capabilities-CdQAc745.d.ts

@@ -0,0 +1,1233 @@
+import { F as FileCommitResult, c as FileSystemEntry, b as FileMeta } from './types-BvDnr3YU.js';
+import { D as DocBlocksHostFsV2API } from './filesystem-v2-C8AdSXUN.js';
+
+/** Provider-neutral catalog management. IDs never authorize filesystem access. */
+interface AiKnowledgeCatalog {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly installedVersion: string | null;
+    readonly enabled: boolean;
+    readonly updateAvailable: boolean;
+    readonly downloadBytes: number | null;
+    readonly documents: number | null;
+    readonly state: 'available' | 'installed' | 'downloading' | 'error';
+    readonly percent: number | null;
+    readonly message: string | null;
+}
+interface AiKnowledgeState {
+    readonly catalogs: readonly AiKnowledgeCatalog[];
+    /**
+     * A one-time model download that improves knowledge results, sized for the
+     * offer. Null when not offered: installed, unavailable, or no enabled
+     * catalog would use it. The provider decides; people only see the offer.
+     */
+    readonly improvement: {
+        readonly downloadBytes: number;
+        readonly downloading: boolean;
+    } | null;
+}
+type AiKnowledgeAction = {
+    readonly action: 'install' | 'remove' | 'enable' | 'disable' | 'cancel';
+    readonly catalogId: string;
+}
+/** Start the `improvement` download. */
+ | {
+    readonly action: 'improve';
+};
+interface AiKnowledgeAPI {
+    state(): Promise<AiResult<AiKnowledgeState>>;
+    update(action: AiKnowledgeAction): Promise<AiResult<null>>;
+}
+declare function parseAiKnowledgeAction(value: unknown): AiKnowledgeAction | null;
+declare function parseAiKnowledgeState(value: unknown): AiKnowledgeState | null;
+
+/**
+ * The host-agnostic AI seam.
+ *
+ * Nothing here names a provider product. Model ids are opaque strings, the
+ * vocabulary is "provider" and "connection", and the capability is described by
+ * what it can do rather than by what is installed behind it. That is deliberate:
+ * the desktop bridge, the VS Code bridge and any future mobile bridge all
+ * satisfy this contract, and `packages/react` must never learn which one it is
+ * talking to.
+ *
+ * Every operation that can fail for an expected reason returns `AiResult`
+ * rather than rejecting. A provider that is not running, a user who declines
+ * approval and a model that is still downloading are ordinary states of this
+ * feature, not exceptions, and a renderer must be able to render them without a
+ * try/catch around every call.
+ */
+/** An expected-failure envelope. Rejections stay reserved for genuine bugs. */
+type AiResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: AiError;
+};
+type AiErrorCode = 
+/** No provider is installed, running, or reachable. */
+'provider-unavailable' | 'approval-denied' | 'approval-timeout' | 'approval-expired'
+/** The stored credential no longer carries the scopes this operation needs. */
+ | 'approval-required'
+/** The provider is reachable but has its connected-app surface switched off. */
+ | 'inference-disabled'
+/** The provider believes this app already holds a credential we no longer have. */
+ | 'already-connected' | 'model-unavailable' | 'model-download-failed'
+/** A hosted runtime was expected but is missing or unusable on this build. */
+ | 'runtime-missing' | 'workspace-not-registered'
+/** The host does not implement this operation at all. */
+ | 'unsupported' | 'budget-exceeded' | 'rate-limited' | 'timeout' | 'cancelled' | 'unknown';
+interface AiError {
+    readonly code: AiErrorCode;
+    /** Shown to the user. Never truncate a provider's own explanation into this. */
+    readonly message: string;
+    /** Optional diagnostic detail for logs; not for display. */
+    readonly detail?: string;
+}
+/**
+ * Why AI is not on offer.
+ *
+ * `opt-out` is first-class rather than an absence, because "the user has not
+ * switched this on" must never be reported as a broken provider. A host may
+ * still check whether its companion provider is installed so the settings UI
+ * can explain the connection only when it is relevant; it must not connect or
+ * start a hosted provider while this state holds.
+ */
+type AiUnavailableReason = 'opt-out' | 'platform-unsupported' | 'not-installed' | 'not-running' | 'disconnected';
+type AiConnectionStep = 'detecting' | 'awaiting-approval' | 'preparing-model' | 'preparing-workspace';
+interface AiProgress {
+    /** Short machine-ish label, e.g. `weights`. Bounded; not free prose. */
+    readonly phase: string;
+    readonly message: string;
+    /** 0-100, or null when the work reports no measurable total. */
+    readonly percent: number | null;
+}
+interface AiProviderInfo {
+    readonly name: string;
+    readonly version: string | null;
+    /** Whether the provider runs as a separate install or inside this app. */
+    readonly mode: 'installed' | 'hosted' | 'remote';
+}
+interface AiModelInfo {
+    readonly id: string;
+    readonly label: string;
+    /** True when inference happens on this device. */
+    readonly local: boolean;
+    /** Token budget, when the provider reports one. Drives prompt budgeting. */
+    readonly contextWindow: number | null;
+    readonly isDefault: boolean;
+    /** Omitted by hosts whose listing contains only ready models. */
+    readonly availability?: 'available' | 'unavailable' | 'download-required' | 'downloading';
+    /** Native readiness explanation, suitable for the model picker. */
+    readonly unavailableReason?: string;
+}
+/** A provider-catalog model that can be added to this device. */
+interface AiModelDownloadInfo {
+    readonly id: string;
+    readonly label: string;
+    readonly contextWindow: number | null;
+    /** Expected weight download size, when the provider reports one. */
+    readonly downloadBytes: number | null;
+    readonly state: 'download-required' | 'downloading';
+}
+type AiStatus = {
+    readonly kind: 'unavailable';
+    readonly reason: AiUnavailableReason;
+} | {
+    readonly kind: 'connecting';
+    readonly step: AiConnectionStep;
+    /**
+     * A short challenge the user types into the provider to approve this app.
+     * It is a one-time proof of presence, not a credential, which is why it
+     * may cross to the renderer for display.
+     */
+    readonly verificationCode: string | null;
+    readonly progress: AiProgress | null;
+} | {
+    readonly kind: 'ready';
+    readonly provider: AiProviderInfo;
+    readonly model: AiModelInfo | null;
+    readonly activeRequests: number;
+} | {
+    readonly kind: 'error';
+    readonly error: AiError;
+    readonly retryable: boolean;
+};
+type AiReviewMode = 'off' | 'explicit' | 'implicit';
+interface AiPreferences {
+    readonly enabled: boolean;
+    /** Preferred model id, or null to take the provider's default. */
+    readonly model: string | null;
+    readonly reviewMode: AiReviewMode;
+}
+type AiPreferencesPatch = Partial<AiPreferences>;
+interface AiChatMessage {
+    readonly role: 'system' | 'user' | 'assistant';
+    readonly content: string;
+}
+/**
+ * What the request is for.
+ *
+ * This exists so the host can apply different budgets to a person waiting on a
+ * draft and a background review pass. It is never sent to the model.
+ */
+type AiChatPurpose = 'write' | 'review' | 'illustrate' | 'chat';
+interface AiChatRequest {
+    readonly messages: readonly AiChatMessage[];
+    /** Opaque provider model id. Omitted means "the host's current choice". */
+    readonly model?: string;
+    readonly temperature?: number;
+    /** Optional caller cap. Writing without one uses the host/model's available capacity. */
+    readonly maxTokens?: number;
+    readonly purpose: AiChatPurpose;
+}
+interface AiChatCompletion {
+    readonly text: string;
+    readonly model: string;
+    readonly finishReason: 'stop' | 'length' | 'cancelled';
+    readonly usage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+    } | null;
+}
+/** Request-local metadata. Unknown counts stay null; streamed chunks are not tokens. */
+interface AiChatProgress {
+    readonly phase: 'starting' | 'queued' | 'loading_model' | 'prefill' | 'reasoning' | 'generating';
+    /** Engine-reported percentage for model loading or prompt processing only. */
+    readonly percent: number | null;
+    /** Exact engine count, including private reasoning when the engine counts it. */
+    readonly outputTokens: number | null;
+    readonly tokensPerSecond: number | null;
+}
+type AiChatEvent = {
+    readonly kind: 'progress';
+    readonly progress: AiChatProgress;
+} | {
+    readonly kind: 'delta';
+    readonly text: string;
+} | {
+    readonly kind: 'done';
+    readonly completion: AiChatCompletion;
+} | {
+    readonly kind: 'error';
+    readonly error: AiError;
+};
+interface AiChatHandle {
+    readonly done: Promise<AiResult<AiChatCompletion>>;
+    cancel(): void;
+}
+/**
+ * One explicitly requested model install.
+ *
+ * Cancelling stops this caller's progress stream. A provider-owned background
+ * download may still finish and appear in the next model refresh.
+ */
+interface AiModelInstallHandle {
+    readonly done: Promise<AiResult<AiModelInfo>>;
+    cancel(): void;
+}
+type AiModelInstallEvent = {
+    readonly kind: 'progress';
+    readonly progress: AiProgress;
+} | {
+    readonly kind: 'done';
+    readonly model: AiModelInfo;
+} | {
+    readonly kind: 'error';
+    readonly error: AiError;
+};
+interface AiEnsureWorkspaceHandle {
+    readonly done: Promise<AiResult<{
+        readonly indexed: boolean;
+    }>>;
+    cancel(): void;
+}
+interface AiSearchQuery {
+    readonly query: string;
+    readonly mode: 'names' | 'full';
+    readonly maxResults?: number;
+}
+interface AiSearchHit {
+    /** Canonical root-relative workspace path. Never an absolute filesystem path. */
+    readonly path: string;
+    readonly title: string | null;
+    readonly snippet: string | null;
+    readonly score: number;
+}
+interface AiSearchResult {
+    readonly hits: readonly AiSearchHit[];
+    readonly truncated: boolean;
+}
+interface AiImageRequest {
+    readonly prompt: string;
+    readonly width?: number;
+    readonly height?: number;
+}
+interface AiImageResult {
+    readonly mimeType: 'image/png';
+    readonly data: ArrayBuffer;
+    readonly width: number;
+    readonly height: number;
+}
+interface AiTranscribeRequest {
+    readonly audio: ArrayBuffer;
+    readonly mimeType: string;
+    readonly language?: string;
+}
+interface AiTranscript {
+    readonly text: string;
+    readonly language: string | null;
+}
+interface AiSynthesizeRequest {
+    readonly text: string;
+    readonly voice?: string;
+}
+interface AiSpeechAudio {
+    readonly mimeType: 'audio/wav';
+    readonly data: ArrayBuffer;
+}
+/**
+ * The AI namespace on `DocBlocksHostAPI`.
+ *
+ * The members below the core group are optional one by one rather than as a
+ * block, because they fail independently: a paired-device mobile host could
+ * plausibly transcribe from its own microphone while offering no image
+ * generation and no workspace index. `deriveHostCapabilities` observes each,
+ * so a host cannot claim an ability whose member is missing.
+ *
+ * A host that cannot do AI at all — an unsupported platform — omits this whole
+ * namespace rather than exposing one that always fails.
+ */
+interface DocBlocksHostAiAPI {
+    /** Optional catalog browsing, downloads, and retrieval model setup. */
+    readonly knowledge?: AiKnowledgeAPI;
+    /** Whether the host's user-installed companion provider is present. */
+    providerInstalled(): Promise<boolean>;
+    status(): Promise<AiStatus>;
+    onStatus(listener: (status: AiStatus) => void): () => void;
+    getPreferences(): Promise<AiPreferences>;
+    setPreferences(patch: AiPreferencesPatch): Promise<AiPreferences>;
+    /**
+     * Run detection and approval. Called only from an explicit user gesture —
+     * never at startup, where a silent reconnect is the host's own business.
+     */
+    connect(): Promise<AiResult<AiStatus>>;
+    disconnect(): Promise<AiResult<null>>;
+    models(): Promise<AiResult<readonly AiModelInfo[]>>;
+    /** Catalog models this host can download. Optional for older providers. */
+    availableModels?(): Promise<AiResult<readonly AiModelDownloadInfo[]>>;
+    /** Start a model download from an explicit user gesture. */
+    installModel?(modelId: string, onProgress?: (progress: AiProgress) => void): AiModelInstallHandle;
+    /**
+     * Start a streamed completion.
+     *
+     * The correlation id is minted by the bridge, not by the caller, so a
+     * renderer cannot address another renderer's stream.
+     */
+    chat(request: AiChatRequest, onEvent: (event: AiChatEvent) => void): AiChatHandle;
+    ensureWorkspace?(workspaceId: string, onProgress?: (progress: AiProgress) => void): AiEnsureWorkspaceHandle;
+    search?(workspaceId: string, query: AiSearchQuery): Promise<AiResult<AiSearchResult>>;
+    generateImage?(request: AiImageRequest): Promise<AiResult<AiImageResult>>;
+    /** @deprecated Speech lives on `DocBlocksHostAPI.speech`; no host implements this. */
+    transcribe?(request: AiTranscribeRequest): Promise<AiResult<AiTranscript>>;
+    /** @deprecated Speech lives on `DocBlocksHostAPI.speech`; no host implements this. */
+    synthesize?(request: AiSynthesizeRequest): Promise<AiResult<AiSpeechAudio>>;
+}
+
+/**
+ * Git host API — wire types for the desktop shell's git integration.
+ *
+ * The desktop app spawns the user's system git from the main process, so
+ * credentials (helpers, SSH agent, signing config and raw remote URLs) remain
+ * in the main process. Everything here is generic git; the only host-specific
+ * conveniences are remote-URL parsing (`GitRemoteInfo.web`) and PR creation
+ * via the GitHub CLI when installed.
+ *
+ * Expected git failures cross IPC as data (`GitResult`), never as thrown
+ * errors — `ipcMain.handle` rejections lose structure. Throwing is reserved
+ * for contract violations (unregistered root, path escape).
+ */
+
+/** Every git operation resolves this — expected failures are data, not throws. */
+type GitResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: GitError;
+};
+interface GitError {
+    code: GitErrorCode;
+    /** One-line human summary (classified stderr or synthesized). */
+    message: string;
+    /** Truncated raw stderr for a details disclosure in the UI. */
+    stderr?: string;
+    exitCode?: number;
+}
+type GitErrorCode = 'git-not-available' | 'not-a-repository' | 'auth-failed' | 'remote-not-found' | 'no-upstream' | 'network' | 'non-fast-forward' | 'merge-conflict' | 'uncommitted-changes' | 'detached-head' | 'unborn-branch' | 'identity-not-configured' | 'branch-exists' | 'invalid-ref-name' | 'nothing-to-commit' | 'invalid-url' | 'destination-exists' | 'pr-exists' | 'gh-not-available' | 'timeout' | 'cancelled' | 'permission-denied' | 'unknown';
+interface GitCapabilities {
+    /** False in store-sandboxed builds, when git is absent, or git < 2.23. */
+    gitAvailable: boolean;
+    gitVersion: string | null;
+    ghAvailable: boolean;
+    ghVersion: string | null;
+}
+interface GitRepoDetection {
+    isRepo: boolean;
+    /** False when the workspace root is a subdirectory of a larger repo. */
+    rootIsToplevel?: boolean;
+    /** Main-owned repository authority; absent while expanded access is ungranted. */
+    repositoryId?: string;
+    /** True when Git metadata or the work tree extends beyond the workspace grant. */
+    requiresExpandedGrant?: boolean;
+    /**
+     * Display path of the enclosing repository root. Present only alongside
+     * `requiresExpandedGrant` so the in-app consent surface can name what the
+     * user would be granting access to.
+     */
+    repositoryRoot?: string;
+}
+type GitFileStatusCode = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'type-changed' | 'untracked' | 'ignored' | 'unmerged';
+interface GitFileChange {
+    /** Slash-prefixed path relative to the WORKSPACE root (fs API convention). */
+    path: string;
+    /** Previous path for renames/copies (workspace-relative, slash-prefixed). */
+    origPath?: string;
+    /** Index-vs-HEAD state (staged), if any. */
+    index?: GitFileStatusCode;
+    /** Worktree-vs-index state (unstaged), if any. */
+    worktree?: GitFileStatusCode;
+    conflicted: boolean;
+}
+interface GitStatus {
+    /** Branch name; null when detached or unborn with no branch. */
+    branch: string | null;
+    detached: boolean;
+    /** HEAD points at a branch with no commits yet. */
+    unborn: boolean;
+    /** Full HEAD SHA; null when unborn. */
+    head: string | null;
+    /** Upstream ref short name, e.g. "origin/main". */
+    upstream: string | null;
+    ahead: number;
+    behind: number;
+    changes: GitFileChange[];
+    /** True when `changes` was capped. */
+    truncated: boolean;
+    operation: 'merge' | 'rebase' | 'cherry-pick' | 'revert' | 'bisect' | null;
+}
+interface GitBranchInfo {
+    /** "main" for local branches, "origin/main" for remote entries. */
+    name: string;
+    kind: 'local' | 'remote';
+    current: boolean;
+    upstream: string | null;
+    ahead: number;
+    behind: number;
+    upstreamGone: boolean;
+    headSha: string;
+    headSubject: string;
+    /** ISO 8601. */
+    headDate: string;
+}
+interface GitLogOptions {
+    /** Workspace-relative file path — per-file history (follows renames). */
+    path?: string;
+    /** Default 100; the host caps at 1000. */
+    maxCount?: number;
+    skip?: number;
+}
+interface GitLogEntry {
+    sha: string;
+    parents: string[];
+    authorName: string;
+    authorEmail: string;
+    /** ISO 8601. */
+    authorDate: string;
+    subject: string;
+    /** Ref decorations ("HEAD -> main", "origin/main", "tag: v1"). */
+    refs: string[];
+}
+/** Typed revision selector — the renderer never passes raw rev strings. */
+type GitRevision = {
+    kind: 'head';
+} | {
+    kind: 'index';
+} | {
+    kind: 'commit';
+    sha: string;
+} | {
+    kind: 'parent-of';
+    sha: string;
+};
+interface GitFileAtRevision {
+    /** Null when the file is absent at that revision, or binary/too large. */
+    content: string | null;
+    binary: boolean;
+}
+interface GitRemoteInfo {
+    name: string;
+    /** Sanitized web location. Raw fetch/push URLs never cross IPC. */
+    web: {
+        host: string;
+        owner: string;
+        repo: string;
+        webUrl: string;
+    } | null;
+}
+interface GitCloneProgress {
+    /** e.g. "Receiving objects", "Resolving deltas", "Checking out files". */
+    phase: string;
+    percent: number | null;
+    /** Raw progress line for display. */
+    detail?: string;
+}
+interface GitCloneHandle {
+    /**
+     * Resolves `ok(null)` if the user cancels the destination picker; on
+     * success resolves the registered workspace ready to open.
+     */
+    result: Promise<GitResult<ElectronWorkspaceInfo | null>>;
+    /** Kill git and remove the partial clone directory. */
+    cancel: () => void;
+}
+interface DocBlocksHostGitAPI {
+    capabilities(): Promise<GitCapabilities>;
+    /**
+     * Detect a persisted workspace by opaque workspace id and mint repository
+     * authority. Never prompts: a workspace inside a larger repository comes
+     * back with `requiresExpandedGrant` and no `repositoryId` until the user
+     * opts in through `grantExpandedRepo`.
+     */
+    detectRepo(workspaceId: string): Promise<GitResult<GitRepoDetection>>;
+    /**
+     * Grant expanded access to the repository enclosing the workspace and mint
+     * repository authority. Must be called from an explicit user gesture. The
+     * choice is remembered for that repository; `always` remembers it for every
+     * repository opened from a subfolder.
+     */
+    grantExpandedRepo(workspaceId: string, opts?: {
+        always?: boolean;
+    }): Promise<GitResult<GitRepoDetection>>;
+    init(workspaceId: string): Promise<GitResult<void>>;
+    status(repositoryId: string): Promise<GitResult<GitStatus>>;
+    stage(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+    unstage(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+    /** Revert tracked files to HEAD; delete untracked ones. Destructive — the renderer confirms. */
+    discard(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+    /**
+     * With `paths`: stages exactly those files (`add -A -- <paths>`) and commits
+     * them, leaving other staged entries staged. Without: commits the index as-is.
+     */
+    commit(repositoryId: string, message: string, paths?: string[]): Promise<GitResult<{
+        sha: string;
+    }>>;
+    push(repositoryId: string, opts?: {
+        setUpstream?: boolean;
+    }): Promise<GitResult<void>>;
+    pull(repositoryId: string): Promise<GitResult<void>>;
+    fetch(repositoryId: string): Promise<GitResult<void>>;
+    listBranches(repositoryId: string): Promise<GitResult<GitBranchInfo[]>>;
+    createBranch(repositoryId: string, name: string, opts?: {
+        checkout?: boolean;
+    }): Promise<GitResult<void>>;
+    checkoutBranch(repositoryId: string, name: string): Promise<GitResult<void>>;
+    log(repositoryId: string, opts?: GitLogOptions): Promise<GitResult<GitLogEntry[]>>;
+    /** Files changed in one commit plus the full message body. */
+    commitFiles(repositoryId: string, sha: string): Promise<GitResult<{
+        body: string;
+        files: GitFileChange[];
+    }>>;
+    readFileAtRevision(repositoryId: string, path: string, revision: GitRevision): Promise<GitResult<GitFileAtRevision>>;
+    listRemotes(repositoryId: string): Promise<GitResult<GitRemoteInfo[]>>;
+    /**
+     * Clone a remote repository. The main process shows a native picker for the
+     * destination parent directory, then registers the clone as a workspace.
+     */
+    clone(url: string, onProgress?: (p: GitCloneProgress) => void): GitCloneHandle;
+    /** `gh pr create --web` (falls back to `gh pr view --web` if one exists). */
+    createPullRequest(repositoryId: string): Promise<GitResult<void>>;
+    /**
+     * Throttled status stream for a workspace root. Emits once immediately on
+     * subscribe. Returns an unsubscribe function.
+     */
+    onStatusChanged(repositoryId: string, listener: (status: GitStatus) => void): () => void;
+}
+
+/**
+ * The host-agnostic speech seam: dictation (speech to text) and narration
+ * (text to speech).
+ *
+ * This is deliberately separate from `ai`. The AI namespace is shaped around a
+ * provider connection — installed or hosted, approved or not — while speech
+ * engines run inside the host itself and need only a downloaded model. A host
+ * may offer speech without AI and AI without speech.
+ *
+ * Shapes follow the vocabulary of the Gezel audio schemas (transcribe requests
+ * with a continuity prompt, synthesis streamed as independently playable
+ * chunks, the `ready` / `download-required` / `unavailable` /
+ * `permission-required` readiness states) so the two products describe the
+ * same engines the same way. Nothing here names an engine: model and voice ids
+ * are opaque strings.
+ *
+ * Every operation that can fail for an expected reason returns `SpeechResult`
+ * rather than rejecting; a missing model is an ordinary state, not a bug.
+ */
+/** An expected-failure envelope. Rejections stay reserved for genuine bugs. */
+type SpeechResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: SpeechError;
+};
+type SpeechErrorCode = 
+/** The operation needs a model that has not been downloaded. */
+'model-missing' | 'model-download-failed'
+/** The engine cannot run on this machine (missing runtime, OS too old). */
+ | 'engine-unavailable'
+/** The engine started but failed this request, or crashed. */
+ | 'engine-failed' | 'invalid-request'
+/** Too many requests in flight; retry after the current one finishes. */
+ | 'busy' | 'timeout' | 'cancelled' | 'unknown';
+interface SpeechError {
+    readonly code: SpeechErrorCode;
+    /** Shown to the user. */
+    readonly message: string;
+    /** Optional diagnostic detail for logs; not for display. */
+    readonly detail?: string;
+}
+type SpeechModelKind = 'stt' | 'tts';
+type SpeechReadinessState = 'ready'
+/** A model must be downloaded first; never started without a user gesture. */
+ | 'download-required'
+/** The engine cannot run here; `reason` says why. */
+ | 'unavailable'
+/** The operating system has refused microphone access to this app. */
+ | 'permission-required';
+/** Readiness never initiates a download, asks for permission, or warms a model. */
+interface SpeechReadiness {
+    readonly state: SpeechReadinessState;
+    readonly reason?: string;
+    /** The model that would serve requests, when one is chosen. */
+    readonly model?: string;
+}
+interface SpeechStatus {
+    readonly stt: SpeechReadiness;
+    readonly tts: SpeechReadiness;
+}
+interface SpeechModelInfo {
+    readonly id: string;
+    readonly kind: SpeechModelKind;
+    readonly label: string;
+    readonly description: string;
+    readonly downloadBytes: number;
+    readonly installed: boolean;
+    /** An older app download exists; update it explicitly before using this model. */
+    readonly updateRequired?: boolean;
+    /**
+     * Where the installed copy lives. `shared` is a verified read-only copy
+     * another local app already downloaded, which costs this app no disk.
+     */
+    readonly source: 'app' | 'shared' | null;
+    /** This installation uses the shared speech cache; Remove releases only its references. */
+    readonly sharedStorage?: boolean;
+    readonly recommended: boolean;
+    readonly license: string;
+    readonly licenseUrl: string;
+}
+interface SpeechVoiceInfo {
+    readonly id: string;
+    readonly label: string;
+    /** BCP 47 tag, e.g. `en-US`. */
+    readonly language: string;
+    readonly gender: 'female' | 'male' | null;
+    /** The TTS model that speaks this voice. */
+    readonly modelId: string;
+}
+interface SpeechCatalog {
+    readonly models: readonly SpeechModelInfo[];
+    readonly voices: readonly SpeechVoiceInfo[];
+}
+interface SpeechProgress {
+    readonly phase: 'downloading' | 'verifying';
+    readonly receivedBytes: number;
+    /** Null when the server reports no length. */
+    readonly totalBytes: number | null;
+}
+type SpeechInstallEvent = {
+    readonly kind: 'progress';
+    readonly progress: SpeechProgress;
+} | {
+    readonly kind: 'done';
+    readonly model: SpeechModelInfo;
+} | {
+    readonly kind: 'error';
+    readonly error: SpeechError;
+};
+interface SpeechInstallHandle {
+    readonly done: Promise<SpeechResult<SpeechModelInfo>>;
+    cancel(): void;
+}
+interface SpeechPreferences {
+    /** Dictation model id, or null for the recommended installed model. */
+    readonly sttModel: string | null;
+    /** Narration voice id, or null for the default voice. */
+    readonly voice: string | null;
+    /** Narration speed, 0.5 to 2. */
+    readonly speed: number;
+}
+type SpeechPreferencesPatch = Partial<SpeechPreferences>;
+interface SpeechTranscribeRequest {
+    /** One self-contained take. */
+    readonly audio: ArrayBuffer;
+    readonly mimeType: 'audio/wav';
+    /**
+     * Recent transcript tail for continuity of vocabulary and punctuation. It is
+     * a hint to the recogniser, never text to re-transcribe.
+     */
+    readonly prompt?: string;
+    readonly language?: string;
+}
+interface SpeechSegment {
+    /** Seconds from the start of the take. */
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+}
+interface SpeechTranscript {
+    /** Trimmed; empty when the take held no speech. */
+    readonly text: string;
+    readonly language: string | null;
+    readonly segments: readonly SpeechSegment[];
+    readonly durationMs: number;
+}
+interface SpeechSynthesizeRequest {
+    readonly text: string;
+    /** Voice id, or omitted for the preferred voice. */
+    readonly voice?: string;
+    /** 0.5 to 2, or omitted for the preferred speed. */
+    readonly speed?: number;
+}
+/** Model-derived word allocation, relative to the chunk's audio and request text. */
+interface SpeechWordTiming {
+    readonly textStart: number;
+    readonly textEnd: number;
+    readonly startSec: number;
+    readonly endSec: number;
+}
+/** One independently playable piece of a synthesis, usually a sentence. */
+interface SpeechAudioChunk {
+    readonly index: number;
+    /** Mono 32-bit float samples. */
+    readonly pcm: ArrayBuffer;
+    readonly sampleRate: number;
+    readonly durationSec: number;
+    /** UTF-16 range of the request text this chunk speaks. */
+    readonly textStart: number;
+    readonly textEnd: number;
+    /** Optional for engines without model durations. Expanded words may share a source range. */
+    readonly wordTimings?: readonly SpeechWordTiming[];
+}
+interface SpeechSynthesisSummary {
+    readonly voice: string;
+    readonly model: string;
+    readonly sampleRate: number;
+    readonly durationSec: number;
+    readonly chunks: number;
+}
+/**
+ * A finite synthesis stream. Audio always arrives as at least one `chunk`
+ * before `done`, so a caller can play chunks as they come.
+ */
+type SpeechSynthesizeEvent = {
+    readonly kind: 'progress';
+    readonly phase: 'loading' | 'synthesizing';
+    readonly completedCharacters: number;
+    readonly totalCharacters: number;
+} | {
+    readonly kind: 'chunk';
+    readonly chunk: SpeechAudioChunk;
+} | {
+    readonly kind: 'done';
+    readonly summary: SpeechSynthesisSummary;
+} | {
+    readonly kind: 'error';
+    readonly error: SpeechError;
+};
+interface SpeechSynthesisHandle {
+    readonly done: Promise<SpeechResult<SpeechSynthesisSummary>>;
+    cancel(): void;
+}
+/**
+ * The speech namespace on `DocBlocksHostAPI`.
+ *
+ * `transcribe` and `synthesize` are optional one by one: an engine can be
+ * missing for this platform while the other works, and
+ * `deriveHostCapabilities` observes each. A host with neither engine omits the
+ * whole namespace.
+ */
+interface DocBlocksHostSpeechAPI {
+    status(): Promise<SpeechStatus>;
+    onStatus(listener: (status: SpeechStatus) => void): () => void;
+    catalog(): Promise<SpeechResult<SpeechCatalog>>;
+    /** Start a model download. Called only from an explicit user gesture. */
+    installModel(modelId: string, onProgress?: (progress: SpeechProgress) => void): SpeechInstallHandle;
+    removeModel(modelId: string): Promise<SpeechResult<null>>;
+    getPreferences(): Promise<SpeechPreferences>;
+    setPreferences(patch: SpeechPreferencesPatch): Promise<SpeechPreferences>;
+    /** Warm an engine ahead of a request, e.g. when the user starts dictating. */
+    prepare(kind: SpeechModelKind): Promise<SpeechResult<null>>;
+    transcribe?(request: SpeechTranscribeRequest): Promise<SpeechResult<SpeechTranscript>>;
+    synthesize?(request: SpeechSynthesizeRequest, onEvent: (event: SpeechSynthesizeEvent) => void): SpeechSynthesisHandle;
+}
+
+/**
+ * DocBlocksHostAPI — the contract exposed by the Electron desktop shell
+ * to its renderer process via contextBridge.
+ *
+ * This file is the single source of truth for the host ↔ renderer
+ * bridge. The Electron preload script exposes an implementation matching
+ * this shape; the React renderer calls it through `window.docBlocksHost`.
+ */
+
+/** Filesystem operations scoped to a main-owned registered workspace id. */
+interface DocBlocksHostFsAPI {
+    readFile(workspaceId: string, path: string): Promise<string | null>;
+    writeFile(workspaceId: string, path: string, content: string): Promise<void>;
+    commitFile(workspaceId: string, path: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    delete(workspaceId: string, path: string): Promise<void>;
+    rename(workspaceId: string, oldPath: string, newPath: string): Promise<void>;
+    readDirectory(workspaceId: string, path: string): Promise<FileSystemEntry[]>;
+    exists(workspaceId: string, path: string): Promise<boolean>;
+    createDirectory(workspaceId: string, path: string): Promise<void>;
+    stat(workspaceId: string, path: string): Promise<FileMeta | null>;
+    readBinary(workspaceId: string, path: string): Promise<ArrayBuffer | null>;
+    writeBinary(workspaceId: string, path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Subscribe to change notifications for a watched root. Returns an
+     * unsubscribe function. The main process uses chokidar under the hood.
+     */
+    watch(workspaceId: string, onChange: (path: string) => void): () => void;
+}
+/** Descriptor returned for an Electron-managed workspace (backed by a folder). */
+interface ElectronWorkspaceInfo {
+    id: string;
+    name: string;
+    /** Display/persistence metadata only. Privileged host calls accept `id`, never this path. */
+    rootPath: string;
+    /**
+     * True for the app's own default workspace — the one DocBlocks creates and
+     * may seed with its starter document. Folders the user picked or cloned are
+     * never default. Hosts that cannot tell omit it.
+     */
+    isDefault?: boolean;
+}
+/** Workspace-management operations exposed to the renderer. */
+interface DocBlocksHostWorkspacesAPI {
+    /** List only folders already persisted as trusted main-process roots. */
+    list(): Promise<ElectronWorkspaceInfo[]>;
+    /**
+     * Return the default workspace (creating DocBlocks inside the operating
+     * system's Documents folder on first call, or the user's configured default).
+     */
+    getDefault(): Promise<ElectronWorkspaceInfo>;
+    /**
+     * Open the native folder picker. Returns null if the user cancels.
+     * The selected folder is registered in the main process whitelist.
+     */
+    pickFolder?(): Promise<ElectronWorkspaceInfo | null>;
+    /**
+     * Re-register a previously picker-approved workspace by main-owned id.
+     * Called on app startup before any filesystem operation.
+     */
+    register(workspaceId: string): Promise<void>;
+    /** Remove a workspace from the trusted whitelist. */
+    unregister(id: string): Promise<void>;
+}
+/** Shell operations — reveal in Finder/Explorer, open external URLs. */
+interface DocBlocksHostShellAPI {
+    /** Reveal a registered workspace root or one root-relative entry. */
+    revealInFolder?(workspaceId: string, workspacePath?: string): Promise<void>;
+    /** Open a registered workspace root in Finder or the platform file manager. */
+    openWorkspaceFolder?(workspaceId: string): Promise<void>;
+    /** Open a URL in the default browser. */
+    openExternal(url: string): Promise<void>;
+}
+/** Native clipboard operations exposed through the trusted host boundary. */
+interface DocBlocksHostClipboardAPI {
+    /** Replace the system clipboard's plain-text contents. */
+    writeText(text: string): Promise<void>;
+    /** Resolve a registered workspace entry in main and copy its absolute path. */
+    writeWorkspacePath?(workspaceId: string, workspacePath: string): Promise<void>;
+}
+/** Exact, main-owned export authority. The display path is never authority. */
+interface HostExportTargetGrant {
+    /** Null means this is a display-only suggestion and save must show a picker. */
+    grantId: string | null;
+    displayPath: string;
+}
+/** Native export target selection and binary file writing. */
+interface DocBlocksHostExportAPI {
+    /** A share-sheet outcome is never a durable export target. Android can only report presentation. */
+    share?(filename: string, data: ArrayBuffer | Uint8Array): Promise<'shared' | 'presented' | 'cancelled'>;
+    /** Resolve an exact remembered grant or a display-only host suggestion. */
+    resolveTarget?(documentId: string, filename: string): Promise<HostExportTargetGrant>;
+    /** Open the native Save dialog and remember the selected target. */
+    pickTarget?(documentId: string, filename: string, currentGrantId?: string | null): Promise<HostExportTargetGrant | null>;
+    /** Write only to an exact target granted by the main process. */
+    save(documentId: string, filename: string, grantId: string | null, data: ArrayBuffer | Uint8Array): Promise<HostExportTargetGrant | null>;
+    /**
+     * Open a chunked upload for an export too large for one `save` message.
+     * Authority is settled before any bytes move: the grant must already exist.
+     * Returns an owner-scoped transfer id.
+     */
+    beginSave?(documentId: string, filename: string, grantId: string, size: number): Promise<string>;
+    /** Append the next in-order chunk of `EXPORT_TRANSFER_LIMITS.chunkBytes` or fewer. */
+    writeChunk?(transferId: string, offset: number, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /** Publish a complete upload to its granted target; null when replacement is declined. */
+    finishSave?(transferId: string): Promise<HostExportTargetGrant | null>;
+    /** Discard an upload. Idempotent, and harmless after `finishSave`. */
+    closeTransfer?(transferId: string): Promise<void>;
+}
+/** System ffmpeg detection. */
+interface DocBlocksHostFfmpegAPI {
+    /** True if `ffmpeg` is available on PATH. */
+    available(): Promise<boolean>;
+    /** Version string from `ffmpeg -version`, or null if unavailable. */
+    version(): Promise<string | null>;
+}
+/** Auto-updater control. */
+interface DocBlocksHostUpdaterAPI {
+    /** Kick off a check without collapsing a failed check into "no update". */
+    checkForUpdates(): Promise<UpdateCheckResult>;
+    /** Current app version string. */
+    getVersion(): Promise<string>;
+    /**
+     * Quit the app and apply a downloaded update. Should only be called
+     * after an `UpdaterStatus` of kind `'downloaded'` has been observed.
+     */
+    quitAndInstall(): Promise<UpdateInstallResult>;
+    /**
+     * Subscribe to updater status events. Returns an unsubscribe function.
+     */
+    onStatus(listener: (status: UpdaterStatus) => void): () => void;
+}
+type UpdateInstallResult = 'installing' | 'cancelled' | 'not-ready';
+type UpdateCheckResult = {
+    kind: 'available';
+    version: string;
+} | {
+    kind: 'not-available';
+} | {
+    kind: 'store-managed';
+} | {
+    kind: 'error';
+    message: string;
+};
+type UpdaterStatus = {
+    kind: 'checking';
+} | {
+    kind: 'available';
+    version: string;
+    releaseNotes?: string;
+    releaseUrl?: string;
+} | {
+    kind: 'not-available';
+} | {
+    kind: 'downloading';
+    percent: number;
+} | {
+    kind: 'downloaded';
+    version: string;
+    releaseNotes?: string;
+    releaseUrl?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** Menu-command events pushed from the main process to the renderer. */
+type MenuCommand = 'file:new' | 'file:openFolder' | 'file:revealWorkspace' | 'file:settings' | 'git:commit' | 'git:push' | 'git:pull' | 'git:fetch' | 'git:newBranch' | 'git:switchBranch' | 'git:history' | 'git:clone' | 'git:openOnRemote' | 'git:createPullRequest' | 'help:about' | 'help:checkForUpdates' | 'help:viewOnGitHub'
+/** Open (or refocus) the find bar in the active document. */
+ | 'edit:find'
+/** Start or stop dictation into the active editor. */
+ | 'edit:toggleDictation'
+/** Read the document (or the selection) aloud, or stop reading. */
+ | 'edit:readAloud';
+/**
+ * One pinned document mirrored from the renderer into native menu surfaces.
+ *
+ * The renderer owns the authoritative pinned list (localStorage). The main
+ * process only caches the latest snapshot so the tray / menu bar can offer a
+ * one-click shortcut per document; it never persists or mutates it.
+ */
+interface HostPinnedDocument {
+    readonly workspaceId: string;
+    readonly workspaceName: string;
+    /** Canonical, root-relative workspace path. */
+    readonly path: string;
+}
+/**
+ * Renderer-to-main channel that keeps native menu surfaces in sync with
+ * renderer-owned state.
+ */
+interface DocBlocksHostMenuAPI {
+    /**
+     * Publish the current pinned-document list so the desktop tray can offer a
+     * shortcut per document that activates it in the main window. Replaces any
+     * previously published list; send an empty array to clear the shortcuts.
+     */
+    setPinnedDocuments(documents: readonly HostPinnedDocument[]): void;
+}
+/**
+ * OS open-file / deep-link event resolved by the host.
+ * - 'workspace-file': a file inside an already-registered workspace.
+ * - 'external-file': a loose markdown file outside any workspace — opened in a
+ *   transient workspace and saved through an opaque resource grant.
+ * - 'external-bundle': a `.dbk`/zip bundle — unpacked into a transient
+ *   workspace and re-zipped through an opaque resource grant on save.
+ */
+type OpenRequest = {
+    kind: 'workspace-file';
+    workspaceId: string;
+    /** Slash-prefixed path relative to the workspace root. */
+    path: string;
+} | {
+    kind: 'external-file';
+    resourceId: string;
+    name: string;
+} | {
+    kind: 'external-bundle';
+    resourceId: string;
+    name: string;
+};
+/**
+ * Read/write access to individual OS files the user has explicitly opened
+ * (via "Open With" / deep link), outside the workspace-root whitelist. The
+ * main process gates these with owner-scoped, exact-file capabilities.
+ */
+interface DocBlocksHostExternalAPI {
+    readText(resourceId: string): Promise<string | null>;
+    readBinary(resourceId: string): Promise<ArrayBuffer | null>;
+    writeText(resourceId: string, content: string): Promise<void>;
+    writeBinary(resourceId: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    commitText(resourceId: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    commitBinary(resourceId: string, data: ArrayBuffer | Uint8Array, expectedVersion: string | null): Promise<ExternalBinaryCommitResult>;
+    /** Revoke one external resource when its transient document is closed. */
+    revoke(resourceId: string): Promise<void>;
+}
+type ExternalBinaryCommitResult = {
+    status: 'committed';
+    version: string;
+} | {
+    status: 'conflict';
+    version: string | null;
+    data: ArrayBuffer | null;
+};
+/**
+ * Environment metadata provided by the host.
+ *
+ * Read synchronously by the renderer, so a host implementation must have
+ * these values in hand before it exposes the bridge — they cannot be awaited.
+ *
+ * Every field is main-process authority. A host must derive them from what it
+ * actually knows about itself (in Electron: `app.getVersion()` and
+ * `app.isPackaged`) and never from renderer-visible environment variables:
+ * `npm_package_version` exists only under an `npm run` script and `NODE_ENV`
+ * is unset in a packaged app, so both silently lie in exactly the builds users
+ * install. `appVersion` in particular reaches users through the About surface
+ * and issue-report URLs.
+ */
+interface HostEnvironment {
+    /** Which shell installed this bridge. Ask a capability, not this, wherever possible. */
+    surface: HostSurfaceKind;
+    /** Short user-facing label for About and issue reports: 'desktop', 'iOS', 'Android'. */
+    surfaceLabel: string;
+    platform: HostPlatform;
+    /** Real, user-facing app version. Never a placeholder like '0.0.0'. */
+    appVersion: string;
+    /** True only in an unpackaged development run. */
+    isDev: boolean;
+}
+type HostCloseReason = 'window-close' | 'app-quit' | 'update-install' | 'reload' | 'force-reload'
+/**
+ * The OS is suspending the app. Unlike every reason above this is a deadline,
+ * not a negotiation: iOS and Android will not let the app veto it, so a
+ * `blocked` result cannot raise a dialog and must simply be journalled.
+ */
+ | 'app-background';
+interface HostPrepareCloseRequest {
+    requestId: string;
+    reason: HostCloseReason;
+    /** Absolute epoch-millisecond deadline chosen by the main process. */
+    deadline: number;
+}
+type HostPrepareCloseResult = {
+    status: 'ready';
+    persistedRevision: number;
+} | {
+    status: 'blocked';
+    code: 'save-failed' | 'external-conflict' | 'not-ready';
+    message: string;
+};
+/**
+ * Main-owned close handshake. Preload privately correlates replies; the
+ * renderer never chooses request or window identifiers.
+ */
+interface DocBlocksHostLifecycleAPI {
+    /** Request the main-owned guarded close path for this renderer window. */
+    requestWindowClose?(): void;
+    onPrepareClose(listener: (request: HostPrepareCloseRequest) => Promise<HostPrepareCloseResult>): () => void;
+    onCancelClose?(listener: (requestId: string) => void): () => void;
+    /** Observe current durable content after a native app returns to the foreground. */
+    onResume?(listener: () => void): () => void;
+    /** Return true when a dialog, drawer, or document navigation consumed Android Back. */
+    onBack?(listener: () => boolean): () => void;
+}
+/** The full DocBlocks desktop host API. */
+interface DocBlocksHostAPI {
+    env: HostEnvironment;
+    fsV2: DocBlocksHostFsV2API;
+    workspaces: DocBlocksHostWorkspacesAPI;
+    /**
+     * Everything below is optional because a host may genuinely not provide it —
+     * a mobile shell has no updater, no native menu bar, and no Git. Marking
+     * them optional is what turns "audit every isElectronHost() call site" into a
+     * list the typechecker produces. Never reach for one directly: ask
+     * `hostSupports(...)` first, or read it through a capability-gated branch.
+     */
+    fs?: DocBlocksHostFsAPI;
+    external?: DocBlocksHostExternalAPI;
+    shell?: DocBlocksHostShellAPI;
+    clipboard?: DocBlocksHostClipboardAPI;
+    exports?: DocBlocksHostExportAPI;
+    ffmpeg?: DocBlocksHostFfmpegAPI;
+    git?: DocBlocksHostGitAPI;
+    updater?: DocBlocksHostUpdaterAPI;
+    lifecycle?: DocBlocksHostLifecycleAPI;
+    menu?: DocBlocksHostMenuAPI;
+    /**
+     * Absent entirely on a host that cannot do AI — an unsupported platform
+     * omits the namespace rather than exposing one whose every call fails.
+     */
+    ai?: DocBlocksHostAiAPI;
+    /**
+     * Absent on a host with no speech engine for this platform. Present
+     * independently of `ai`: speech engines run in the host and need only a
+     * downloaded model, not a provider connection.
+     */
+    speech?: DocBlocksHostSpeechAPI;
+    /**
+     * Subscribe to menu commands dispatched by the native menu.
+     * Returns an unsubscribe function.
+     */
+    onMenuCommand?(listener: (cmd: MenuCommand) => void): () => void;
+    /**
+     * Subscribe to open-file / open-url requests from the OS.
+     * Returns an unsubscribe function.
+     */
+    onOpenRequest(listener: (request: OpenRequest) => void): () => void;
+}
+
+/**
+ * Which shell installed the bridge.
+ *
+ * This is an identity question, and almost nothing should be asking it — ask a
+ * capability instead. It exists for the handful of places that genuinely differ
+ * by product rather than by ability, such as which documentation URL to open.
+ */
+type HostSurfaceKind = 'electron' | 'capacitor';
+type HostPlatform = 'darwin' | 'win32' | 'linux' | 'ios' | 'android';
+declare const HOST_SURFACE_KINDS: readonly HostSurfaceKind[];
+declare const HOST_PLATFORMS: readonly HostPlatform[];
+/**
+ * What the installed host can actually do.
+ *
+ * Every member is a question a caller genuinely asks. None is a proxy for
+ * "which shell is this" — that was the failure of `isElectronHost()`, which
+ * stood in for a dozen unrelated decisions and which no mobile host could
+ * answer honestly either way.
+ */
+interface HostCapabilities {
+    /** The host owns durable workspace roots, addressed by registered id. */
+    readonly nativeWorkspaces: boolean;
+    /** `workspaces.list()` is authoritative and must be reconciled at startup. */
+    readonly workspaceAuthority: boolean;
+    readonly workspaceFolderPicker: boolean;
+    readonly defaultWorkspace: boolean;
+    readonly filesystemV2: boolean;
+    /** Can show an entry in the OS file manager. iOS cannot. */
+    readonly revealInFileManager: boolean;
+    readonly openWorkspaceFolder: boolean;
+    readonly externalNavigation: boolean;
+    readonly clipboard: boolean;
+    /** Any host-owned save path at all. */
+    readonly exportDestinations: boolean;
+    /** Remembered, re-resolvable export targets (`resolveTarget`/`pickTarget`). */
+    readonly exportRememberedTargets: boolean;
+    readonly externalResources: boolean;
+    readonly openRequests: boolean;
+    readonly menuCommands: boolean;
+    readonly pinnedDocumentMirror: boolean;
+    readonly guardedClose: boolean;
+    readonly git: boolean;
+    readonly updater: boolean;
+    readonly systemFfmpeg: boolean;
+    /**
+     * Assisted writing and review: a streamed completion plus a status channel.
+     *
+     * The AI abilities below are separate flags rather than one, because they are
+     * independently absent. A paired-device mobile host could plausibly transcribe
+     * from its own microphone while offering no image generation and no index.
+     */
+    readonly aiAssist: boolean;
+    /** The host can list and download provider-catalog models. */
+    readonly aiModelManagement: boolean;
+    readonly aiKnowledgeManagement: boolean;
+    /** The host can bind a workspace folder to a provider-side index. */
+    readonly aiWorkspaceIndex: boolean;
+    readonly aiSearch: boolean;
+    readonly aiImages: boolean;
+    /** @deprecated Speech moved to `host.speech`; use `speechInput`. Always false on current hosts. */
+    readonly aiTranscription: boolean;
+    /** @deprecated Speech moved to `host.speech`; use `speechOutput`. Always false on current hosts. */
+    readonly aiSpeechSynthesis: boolean;
+    /** Dictation: the host can transcribe recorded takes. */
+    readonly speechInput: boolean;
+    /** Narration: the host can synthesize speech from text. */
+    readonly speechOutput: boolean;
+    /** The host can list, download, and remove speech models. */
+    readonly speechModelManagement: boolean;
+    /** Documents live in the web origin (IndexedDB) rather than on the host. */
+    readonly browserOriginStorage: boolean;
+    /** The host draws the window chrome, so the shell must leave room for it. */
+    readonly ownsWindowChrome: boolean;
+}
+/** All-false (plus browser storage) — exported so callers can render hostless. */
+declare const NO_HOST_CAPABILITIES: HostCapabilities;
+/**
+ * Parse the host-declared environment.
+ *
+ * `env` is data crossing a trust boundary, so it gets a real parser rather than
+ * a cast. An unknown surface or platform, an unbounded string, or an unexpected
+ * key makes the whole host untrusted — `deriveHostCapabilities` then reports
+ * nothing, which fails closed instead of half-enabling a bridge we do not
+ * understand.
+ */
+declare function parseHostEnvironment(value: unknown): HostEnvironment | null;
+/**
+ * Derive capabilities from what the bridge actually exposes.
+ *
+ * Observed, never self-declared: a host cannot claim a capability whose API
+ * member is missing, nor hide one whose member is present, so the two can never
+ * drift. It also means preload or plugin version skew degrades to "unsupported"
+ * rather than to a runtime TypeError on first use. This mirrors what
+ * `ElectronFileSystemProviderV2` already does when it feature-detects the
+ * chunked-transfer methods.
+ */
+declare function deriveHostCapabilities(host: unknown): HostCapabilities;
+
+export { type GitCapabilities as $, type AiChatCompletion as A, type AiSearchHit as B, type AiSearchQuery as C, type AiSearchResult as D, type AiSpeechAudio as E, type AiStatus as F, type AiSynthesizeRequest as G, type AiTranscribeRequest as H, type AiTranscript as I, type AiUnavailableReason as J, type DocBlocksHostAPI as K, type DocBlocksHostAiAPI as L, type DocBlocksHostClipboardAPI as M, type DocBlocksHostExportAPI as N, type DocBlocksHostExternalAPI as O, type DocBlocksHostFfmpegAPI as P, type DocBlocksHostFsAPI as Q, type DocBlocksHostGitAPI as R, type DocBlocksHostLifecycleAPI as S, type DocBlocksHostMenuAPI as T, type DocBlocksHostShellAPI as U, type DocBlocksHostSpeechAPI as V, type DocBlocksHostUpdaterAPI as W, type DocBlocksHostWorkspacesAPI as X, type ElectronWorkspaceInfo as Y, type ExternalBinaryCommitResult as Z, type GitBranchInfo as _, type AiChatEvent as a, type GitCloneHandle as a0, type GitCloneProgress as a1, type GitError as a2, type GitErrorCode as a3, type GitFileAtRevision as a4, type GitFileChange as a5, type GitFileStatusCode as a6, type GitLogEntry as a7, type GitLogOptions as a8, type GitRemoteInfo as a9, type SpeechPreferences as aA, type SpeechPreferencesPatch as aB, type SpeechProgress as aC, type SpeechReadiness as aD, type SpeechReadinessState as aE, type SpeechResult as aF, type SpeechSegment as aG, type SpeechStatus as aH, type SpeechSynthesisHandle as aI, type SpeechSynthesisSummary as aJ, type SpeechSynthesizeEvent as aK, type SpeechSynthesizeRequest as aL, type SpeechTranscribeRequest as aM, type SpeechTranscript as aN, type SpeechVoiceInfo as aO, type SpeechWordTiming as aP, type UpdateCheckResult as aQ, type UpdateInstallResult as aR, type UpdaterStatus as aS, deriveHostCapabilities as aT, parseAiKnowledgeAction as aU, parseAiKnowledgeState as aV, parseHostEnvironment as aW, type GitRepoDetection as aa, type GitResult as ab, type GitRevision as ac, type GitStatus as ad, HOST_PLATFORMS as ae, HOST_SURFACE_KINDS as af, type HostCapabilities as ag, type HostCloseReason as ah, type HostEnvironment as ai, type HostExportTargetGrant as aj, type HostPinnedDocument as ak, type HostPlatform as al, type HostPrepareCloseRequest as am, type HostPrepareCloseResult as an, type HostSurfaceKind as ao, type MenuCommand as ap, NO_HOST_CAPABILITIES as aq, type OpenRequest as ar, type SpeechAudioChunk as as, type SpeechCatalog as at, type SpeechError as au, type SpeechErrorCode as av, type SpeechInstallEvent as aw, type SpeechInstallHandle as ax, type SpeechModelInfo as ay, type SpeechModelKind as az, type AiChatHandle as b, type AiChatMessage as c, type AiChatProgress as d, type AiChatPurpose as e, type AiChatRequest as f, type AiConnectionStep as g, type AiEnsureWorkspaceHandle as h, type AiError as i, type AiErrorCode as j, type AiImageRequest as k, type AiImageResult as l, type AiKnowledgeAPI as m, type AiKnowledgeAction as n, type AiKnowledgeCatalog as o, type AiKnowledgeState as p, type AiModelDownloadInfo as q, type AiModelInfo as r, type AiModelInstallEvent as s, type AiModelInstallHandle as t, type AiPreferences as u, type AiPreferencesPatch as v, type AiProgress as w, type AiProviderInfo as x, type AiResult as y, type AiReviewMode as z };