@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/ai/headless/use-ai-run.js

@@ -0,0 +1,212 @@
+/**
+ * One background AI run: start, poll until it settles, cancel — issue #434,
+ * epic #419.
+ *
+ * `POST /ai/runs` enqueues the request as a queue job (CLAUDE.md: every
+ * long-running activity is a queue job) and answers 202 with a run id; this
+ * hook then reads `GET /ai/runs/:id` every `intervalMs` (2 s by default)
+ * until the run is `succeeded`, `failed` or `cancelled`, and stops.
+ *
+ * POLLING IS A TIMEOUT CHAIN, NOT AN INTERVAL: the next read is scheduled
+ * only after the previous one answered, so a slow API can never stack
+ * overlapping requests.
+ *
+ * A FAILED READ IS NOT A FAILED RUN (#509). A read that fails for a reason
+ * that can clear on its own — the browser's network `TypeError` ("Failed to
+ * fetch"), a 5xx, a 408/429 — marks the last-known `run` as `stale` and keeps
+ * polling with a modest linear backoff; the next successful read clears it.
+ * Only after {@link AI_RUN_MAX_POLL_FAILURES} consecutive failures does the
+ * hook give up, stop polling and surface `error` (with `stale` still set, so
+ * the card can say the status it shows is the last one it saw, not the
+ * current one). A read the server refuses outright (any other 4xx — 404: not
+ * theirs, or gone) will not start answering on its own, so it stops polling
+ * and surfaces the error at once, as before. A run that itself settled
+ * `failed` is not a read failure at all: it arrives as `run.errorCode`.
+ *
+ * `onSettled` fires exactly once per run, when it reaches a terminal state.
+ *
+ * ANY RUN, NOT ONLY TEXT (#445). `start` queues a text response; `startWith`
+ * takes whichever call created the run — `POST /ai/images`,
+ * `POST /ai/images/edits`, and the media routes after them all answer the
+ * same 202 `{ runId, jobId }` and settle through the same `GET /ai/runs/:id`.
+ * Narrow the settled `output` with `isAiResponseRunOutput` /
+ * `isAiImageRunOutput`.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { cancelAiRun, createAiRun, getAiRun } from './client.js';
+import { isPlatformApiError } from '../../core/index.js';
+import { toAiErrorInfo } from './errors.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useAiApi } from './use-ai-api.js';
+/**
+ * The AI run poll interval ms.
+ *
+ * @stability experimental
+ */
+export const AI_RUN_POLL_INTERVAL_MS = 2000;
+/**
+ * Consecutive transient read failures tolerated before the hook gives up.
+ *
+ * @stability experimental
+ */
+export const AI_RUN_MAX_POLL_FAILURES = 3;
+/**
+ * Whether a failed `GET /ai/runs/:id` may succeed if simply retried: a
+ * network-level failure (no HTTP response at all), a 5xx, a 408 or a 429.
+ */
+function isTransientReadFailure(err) {
+    if (!isPlatformApiError(err))
+        return true;
+    return err.status >= 500 || err.status === 408 || err.status === 429;
+}
+const TERMINAL = ['succeeded', 'failed', 'cancelled'];
+/**
+ * Is AI run terminal.
+ *
+ * @stability experimental
+ */
+export function isAiRunTerminal(status) {
+    return TERMINAL.includes(status);
+}
+/**
+ * Use AI run.
+ *
+ * @stability experimental
+ */
+export function useAiRun(options = {}) {
+    const { intervalMs = AI_RUN_POLL_INTERVAL_MS, onSettled } = options;
+    const api = useAiApi(options.api);
+    const [runId, setRunId] = useState(null);
+    const [run, setRun] = useState(null);
+    const [isStarting, setIsStarting] = useState(false);
+    const [isCancelling, setIsCancelling] = useState(false);
+    const [error, setError] = useState(null);
+    const [polling, setPolling] = useState(false);
+    const [stale, setStale] = useState(false);
+    const isMounted = useIsMounted();
+    const onSettledRef = useRef(onSettled);
+    onSettledRef.current = onSettled;
+    const settledRef = useRef(null);
+    const accept = useCallback((next) => {
+        if (!isMounted())
+            return;
+        setRun(next);
+        setStale(false);
+        if (isAiRunTerminal(next.status)) {
+            setPolling(false);
+            if (settledRef.current !== next.id) {
+                settledRef.current = next.id;
+                onSettledRef.current?.(next);
+            }
+        }
+    }, [isMounted]);
+    useEffect(() => {
+        if (!runId || !polling)
+            return;
+        let cancelled = false;
+        let timer = null;
+        let failures = 0;
+        const poll = async () => {
+            try {
+                const next = await getAiRun(api, runId);
+                if (cancelled)
+                    return;
+                failures = 0;
+                accept(next);
+                if (!isAiRunTerminal(next.status))
+                    timer = setTimeout(poll, intervalMs);
+            }
+            catch (err) {
+                if (cancelled || !isMounted())
+                    return;
+                const transient = isTransientReadFailure(err);
+                failures += 1;
+                setStale(true);
+                if (transient && failures < AI_RUN_MAX_POLL_FAILURES) {
+                    // Keep the last-known run on screen, flagged stale; back off a little.
+                    timer = setTimeout(poll, intervalMs * (failures + 1));
+                    return;
+                }
+                const info = toAiErrorInfo(err, 'Could not read the background run');
+                setError(isPlatformApiError(err)
+                    ? info
+                    : {
+                        ...info,
+                        message: "Lost contact with the server while checking this run's status. The run may still be in progress.",
+                    });
+                setPolling(false);
+            }
+        };
+        timer = setTimeout(poll, intervalMs);
+        return () => {
+            cancelled = true;
+            if (timer !== null)
+                clearTimeout(timer);
+        };
+    }, [runId, polling, intervalMs, accept, isMounted]);
+    const startWith = useCallback(async (create) => {
+        setIsStarting(true);
+        setError(null);
+        setStale(false);
+        setRun(null);
+        setRunId(null);
+        setPolling(false);
+        try {
+            const started = await create();
+            if (!isMounted())
+                return started.runId;
+            setRunId(started.runId);
+            setPolling(true);
+            return started.runId;
+        }
+        catch (err) {
+            if (isMounted())
+                setError(toAiErrorInfo(err, 'Could not start the background run'));
+            return null;
+        }
+        finally {
+            if (isMounted())
+                setIsStarting(false);
+        }
+    }, [isMounted]);
+    const start = useCallback((request) => startWith(() => createAiRun(api, request)), [api, startWith]);
+    const cancel = useCallback(async () => {
+        if (!runId)
+            return;
+        setIsCancelling(true);
+        try {
+            const next = await cancelAiRun(api, runId);
+            accept(next);
+        }
+        catch (err) {
+            if (isMounted())
+                setError(toAiErrorInfo(err, 'Could not cancel the background run'));
+        }
+        finally {
+            if (isMounted())
+                setIsCancelling(false);
+        }
+    }, [runId, accept, isMounted]);
+    const clear = useCallback(() => {
+        setRunId(null);
+        setRun(null);
+        setError(null);
+        setStale(false);
+        setPolling(false);
+    }, []);
+    const isActive = isStarting || polling;
+    return {
+        run,
+        runId,
+        isActive,
+        isStarting,
+        isCancelling,
+        error,
+        stale,
+        start,
+        startWith,
+        cancel,
+        clear,
+    };
+}
+//# sourceMappingURL=use-ai-run.js.map

package/dist/ai/headless/use-ai-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-run.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-run.ts"],"names":[],"mappings":"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"}

package/dist/ai/headless/use-ai-storage.d.ts

@@ -0,0 +1,13 @@
+import type { StorageObjectsClient } from '../../storage/index.js';
+import type { PlatformApiClient } from '../../core/index.js';
+/**
+ * The storage objects client over the AI transport (`upload`, `uploadAndWait`,
+ * `downloadUrl`, ...). Stable while the transport is.
+ *
+ * @param explicit - a transport to use instead of the host's.
+ * @returns the client.
+ *
+ * @stability experimental
+ */
+export declare function useAiStorageObjects(explicit?: PlatformApiClient): StorageObjectsClient;
+//# sourceMappingURL=use-ai-storage.d.ts.map

package/dist/ai/headless/use-ai-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-storage.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-storage.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,oBAAoB,CAGtF"}

package/dist/ai/headless/use-ai-storage.js

@@ -0,0 +1,19 @@
+// The caller's storage objects client for the AI media pages (issue #890): an
+// upload goes to storage first, the AI route names it by id.
+import { useMemo } from 'react';
+import { createStorageObjectsClient } from '../../storage/index.js';
+import { useAiApi } from './use-ai-api.js';
+/**
+ * The storage objects client over the AI transport (`upload`, `uploadAndWait`,
+ * `downloadUrl`, ...). Stable while the transport is.
+ *
+ * @param explicit - a transport to use instead of the host's.
+ * @returns the client.
+ *
+ * @stability experimental
+ */
+export function useAiStorageObjects(explicit) {
+    const api = useAiApi(explicit);
+    return useMemo(() => createStorageObjectsClient(api), [api]);
+}
+//# sourceMappingURL=use-ai-storage.js.map

package/dist/ai/headless/use-ai-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-storage.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-storage.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6DAA6D;AAE7D,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA4B;IAC9D,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,0BAA0B,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/ai/headless/use-ai-usage.d.ts

@@ -0,0 +1,30 @@
+import { type AiMyUsageGroupBy, type AiMyUsageQuery, type AiUsageQuery, type AiUsageReport } from './types.js';
+import type { AiHookOptions } from './use-ai-api.js';
+/**
+ * The use AI usage return wire shape.
+ *
+ * @stability experimental
+ */
+export interface UseAiUsageReturn<G extends string> {
+    /** The report. */
+    report: AiUsageReport<G> | null;
+    /** Whether loading. */
+    isLoading: boolean;
+    /** The error. */
+    error: string | null;
+    /** The refresh. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Organisation-wide usage, one grouping per call.
+ *
+ * @stability experimental
+ */
+export declare function useAiUsage(query: AiUsageQuery, options?: AiHookOptions): UseAiUsageReturn<AiUsageQuery['groupBy']>;
+/**
+ * The caller's own usage.
+ *
+ * @stability experimental
+ */
+export declare function useMyAiUsage(query: AiMyUsageQuery, options?: AiHookOptions): UseAiUsageReturn<AiMyUsageGroupBy>;
+//# sourceMappingURL=use-ai-usage.d.ts.map

package/dist/ai/headless/use-ai-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-usage.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-usage.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD,kBAAkB;IAClB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mBAAmB;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AA2CD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,aAAkB,GAC1B,gBAAgB,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAe3C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,aAAkB,GAC1B,gBAAgB,CAAC,gBAAgB,CAAC,CAQpC"}

package/dist/ai/headless/use-ai-usage.js

@@ -0,0 +1,80 @@
+/**
+ * AI usage aggregates (issue #444, epic #420) — `GET /api/admin/ai/usage`
+ * (`useAiUsage`, `ai_config:read`) and `GET /api/ai/usage/me` (`useMyAiUsage`,
+ * `ai:use`).
+ *
+ * Both are thin readers over one shared loader: the query is a PARAMETER, the
+ * effect keys on its scalars, and a response that arrives after the query has
+ * changed is dropped rather than painted over the newer one (switching 7 → 90
+ * days quickly must not end on the 7-day numbers).
+ *
+ * Like `useJobInsights`, neither polls: usage over a 30-day window does not
+ * move at a timescale worth an interval, and refreshing is an explicit act.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isPlatformApiError } from '../../core/index.js';
+import { getAiUsage, getMyAiUsage } from './client.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useAiApi } from './use-ai-api.js';
+function useUsageReport(api, fetcher, queryKey, fallbackError) {
+    const [report, setReport] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    const latest = useRef(0);
+    const fetcherRef = useRef(fetcher);
+    fetcherRef.current = fetcher;
+    const load = useCallback(async () => {
+        const ticket = ++latest.current;
+        const current = () => isMounted() && ticket === latest.current;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const data = await fetcherRef.current();
+            if (current())
+                setReport(data);
+        }
+        catch (err) {
+            if (current()) {
+                setReport(null);
+                setError(isPlatformApiError(err) ? err.message : fallbackError);
+            }
+        }
+        finally {
+            if (current())
+                setIsLoading(false);
+        }
+        // `queryKey` stands in for the query object, so a new object with the same
+        // values does not re-fetch.
+    }, [api, queryKey, fallbackError, isMounted]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    return { report, isLoading, error, refresh: load };
+}
+/**
+ * Organisation-wide usage, one grouping per call.
+ *
+ * @stability experimental
+ */
+export function useAiUsage(query, options = {}) {
+    const api = useAiApi(options.api);
+    return useUsageReport(api, () => getAiUsage(api, query), JSON.stringify([
+        query.groupBy,
+        query.from,
+        query.to,
+        query.userId,
+        query.provider,
+        query.model,
+    ]), 'Failed to load AI usage');
+}
+/**
+ * The caller's own usage.
+ *
+ * @stability experimental
+ */
+export function useMyAiUsage(query, options = {}) {
+    const api = useAiApi(options.api);
+    return useUsageReport(api, () => getMyAiUsage(api, query), JSON.stringify([query.groupBy, query.from, query.to]), 'Failed to load your AI usage');
+}
+//# sourceMappingURL=use-ai-usage.js.map

package/dist/ai/headless/use-ai-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-usage.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-usage.ts"],"names":[],"mappings":"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"}

package/dist/ai/headless/use-ai-user-settings.d.ts

@@ -0,0 +1,38 @@
+import type { UseUserSettingsResult, UserSettingsDocument, UserSettingsUpdateBase } from '../../settings/index.js';
+import type { AiHookOptions } from './use-ai-api.js';
+import type { AiDefaultModel } from './types.js';
+/**
+ * The part of the user settings document the AI pages read: the default
+ * model, a provider/model pair and never a key.
+ *
+ * @stability experimental
+ */
+export interface AiUserSettings extends UserSettingsDocument {
+    /** `ai.defaultModel`: `null` or absent means "no default chosen". */
+    ai?: {
+        /** The default model. */
+        defaultModel?: AiDefaultModel | null;
+    };
+}
+/**
+ * The PATCH body the AI pages send.
+ *
+ * @stability experimental
+ */
+export interface AiUserSettingsUpdate extends UserSettingsUpdateBase {
+    /** A new default model, or `null` to clear it. */
+    ai?: {
+        /** The default model. */
+        defaultModel?: AiDefaultModel | null;
+    };
+}
+/**
+ * The user settings document, for its `ai.defaultModel`.
+ *
+ * @param options - the transport.
+ * @returns the settings hook's state and actions.
+ *
+ * @stability experimental
+ */
+export declare function useAiUserSettings(options?: AiHookOptions): UseUserSettingsResult<AiUserSettings, AiUserSettingsUpdate>;
+//# sourceMappingURL=use-ai-user-settings.d.ts.map

package/dist/ai/headless/use-ai-user-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-user-settings.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-user-settings.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D,qEAAqE;IACrE,EAAE,CAAC,EAAE;QACH,yBAAyB;QACzB,YAAY,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;KACtC,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,kDAAkD;IAClD,EAAE,CAAC,EAAE;QACH,yBAAyB;QACzB,YAAY,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;KACtC,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,aAAkB,GAC1B,qBAAqB,CAAC,cAAc,EAAE,oBAAoB,CAAC,CAK7D"}

package/dist/ai/headless/use-ai-user-settings.js

@@ -0,0 +1,20 @@
+// The caller's AI preferences (issue #890): `user_settings.ai.defaultModel`,
+// read and written through the settings slice's `useUserSettings` (GET and
+// PATCH `/user-settings`). The AI pages never edit the theme, so loading the
+// document never pushes the stored theme into the shell (`syncTheme: false`).
+import { useUserSettings } from '../../settings/index.js';
+/**
+ * The user settings document, for its `ai.defaultModel`.
+ *
+ * @param options - the transport.
+ * @returns the settings hook's state and actions.
+ *
+ * @stability experimental
+ */
+export function useAiUserSettings(options = {}) {
+    return useUserSettings({
+        ...(options.api === undefined ? {} : { api: options.api }),
+        syncTheme: false,
+    });
+}
+//# sourceMappingURL=use-ai-user-settings.js.map

package/dist/ai/headless/use-ai-user-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-user-settings.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-user-settings.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAoC1D;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAyB,EAAE;IAE3B,OAAO,eAAe,CAAuC;QAC3D,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;AACL,CAAC"}

package/dist/ai/headless/use-microphone-permission.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The browser's microphone permission, observed up front — and requested only
+ * from a click.
+ *
+ * Issue #508. The Playground's Voice mode used to learn about a blocked
+ * microphone only AFTER the user pressed Start: `getUserMedia` rejected with
+ * `NotAllowedError` and a static "Microphone access was blocked" warning
+ * appeared, with no way forward on a phone (Android Chrome in the report)
+ * where the remedy lives two settings screens away. This hook lets the page
+ * know BEFORE a session is attempted, so it can offer an explicit "Allow
+ * microphone" button while the browser will still ask, and platform-specific
+ * steps once it will not.
+ *
+ * MODELLED ON `useBrowserNotificationPermission.ts`, with one deliberate
+ * difference: this hook DOES request, via `request()` — but only ever from a
+ * user gesture (a click handler). Mobile browsers refuse or silently ignore a
+ * gestureless `getUserMedia`, and prompting on page load would be exactly the
+ * uninvited permission dialog users learn to dismiss.
+ *
+ * WHY STATE RATHER THAN A ONE-OFF READ
+ * ------------------------------------
+ * The value changes under the page: a user told "blocked — allow it in site
+ * settings" goes to those settings and comes back. So it is re-read on:
+ *
+ *   1. The Permissions API's `change` event, where available — the precise,
+ *     immediate signal.
+ *   2. `visibilitychange` → visible, the fallback for a browser whose
+ *     Permissions API does not know `microphone` (Firefox, older Safari), and
+ *     precisely the moment a user returns from the OS or browser settings.
+ *   3. Every `request()`, in a `finally`, whatever it resolved to.
+ */
+/**
+ * Permission as the Voice mode needs to reason about it.
+ *
+ * - `'insecure'` — not a secure context (plain `http://`): browsers remove
+ *   `navigator.mediaDevices` entirely, so no amount of "allow" can help; the
+ *   remedy is HTTPS.
+ * - `'unsupported'` — a secure context with no `getUserMedia` at all.
+ * - `'unknown'` — capture exists but the browser will not say whether it is
+ *   allowed (no Permissions API, or it does not know `microphone`). Not a
+ *   problem: the browser simply asks when the microphone is requested.
+ * - `'prompt'` / `'granted'` / `'denied'` — the Permissions API's own states.
+ 
+ *
+ * @stability experimental
+ */
+export type MicrophonePermission = 'unsupported' | 'insecure' | 'unknown' | 'prompt' | 'granted' | 'denied';
+/**
+ * What `request()` resolved to. `no-mic`: allowed, but no input device exists.
+ *
+ * @stability experimental
+ */
+export type MicrophoneRequestResult = 'granted' | 'denied' | 'no-mic' | 'error';
+/**
+ * The platform whose settings steps to show for a blocked microphone.
+ *
+ * @stability experimental
+ */
+export type MicPlatform = 'android' | 'ios' | 'desktop';
+/**
+ * Classify a user agent for the "how do I unblock it" copy — nothing else.
+ *
+ * iPadOS 13+ reports a desktop Safari UA ("Macintosh"); that case cannot be
+ * told apart from a user agent string alone, and the desktop steps (site
+ * settings in the address bar) are still a sensible answer there.
+ 
+ *
+ * @stability experimental
+ */
+export declare function detectMicPlatform(userAgent: string): MicPlatform;
+/**
+ * The use microphone permission result wire shape.
+ *
+ * @stability experimental
+ */
+export interface UseMicrophonePermissionResult {
+    /** What the browser says right now. See `MicrophonePermission`. */
+    permission: MicrophonePermission;
+    /** True while `request()`'s `getUserMedia` is awaiting the user's answer. */
+    requesting: boolean;
+    /**
+     * Ask for the microphone. MUST be called from a click handler. Opens and
+     * immediately releases a stream — nothing is recorded — then re-queries.
+     */
+    request: () => Promise<MicrophoneRequestResult>;
+    /** Force a re-read (e.g. after a Start that failed with `mic-denied`). */
+    refresh: () => void;
+}
+/**
+ * Use microphone permission.
+ *
+ * @stability experimental
+ */
+export declare function useMicrophonePermission(): UseMicrophonePermissionResult;
+//# sourceMappingURL=use-microphone-permission.d.ts.map

package/dist/ai/headless/use-microphone-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-microphone-permission.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-microphone-permission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAC9B,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAKhE;AAoDD;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,mEAAmE;IACnE,UAAU,EAAE,oBAAoB,CAAC;IACjC,6EAA6E;IAC7E,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAChD,0EAA0E;IAC1E,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,6BAA6B,CA0GvE"}