@ggui-ai/gadgets 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,663 @@
+import { GadgetHook, GadgetDescriptor, GadgetExportBase, JsonValue } from '@ggui-ai/protocol';
+export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
+
+/**
+ * `createGguiGadget` — the plugin SDK factory for ggui client
+ * library wrappers.
+ *
+ * Authors compose 3rd-party JS libraries (Leaflet, Mapbox, Stripe,
+ * Chart.js, …) into stable React hooks that satisfy
+ * {@link GadgetHook}. The factory:
+ *
+ *   1. Strictly validates the spec at call time via
+ *      `strictGadgetDescriptorSchema` — non-empty teaching text
+ *      (`description` / `usage` / `example`), at least one of
+ *      `package` / `bundleUrl`, plus a non-function `hookImpl` check
+ *      the schema can't see. Throws {@link WrapperConformanceError}
+ *      with field-level paths on any violation.
+ *   2. Returns the React hook function as the primary export, with
+ *      the serializable {@link GadgetDescriptor} descriptor attached
+ *      as `.descriptor`. Single export, dual purpose:
+ *
+ *      ```ts
+ *      export const useLeafletMap = createGguiGadget({
+ *        hook: 'useLeafletMap',
+ *        description: '...',
+ *        usage: '...',
+ *        example: { ... },
+ *        package: '@my-org/ggui-leaflet',
+ *        styleUrl: '/leaflet.css',
+ *        hookImpl: (options) => { …real React hook… },
+ *      });
+ *
+ *      // Call as a React hook from generated component code:
+ *      const map = useLeafletMap({ center: [0, 0], zoom: 2 });
+ *
+ *      // Register on App.gadgets via the descriptor:
+ *      app.gadgets.push(useLeafletMap.descriptor);
+ *      ```
+ *
+ * Why no `bind: (lib) => …` indirection: wrappers bundle their
+ * underlying dependencies at build time (per the "ggui hosts every
+ * bundle" model that the CSP derivation depends on). Authors `import L
+ * from 'leaflet'` inside the wrapper and tsup/esbuild rolls it into
+ * the published bundle. The factory doesn't need to load 3rd-party
+ * libs at runtime — just validate the spec + plumb the descriptor.
+ *
+ * Why no separate `HookResult` shape: the existing protocol
+ * {@link GadgetHook} already nails the return contract
+ * (`{value, status, error?, start, stop?}`). Re-using it keeps
+ * stdlib hooks and 3rd-party plugins indistinguishable at the
+ * consumption site — generated component code calls them the same
+ * way.
+ */
+
+/**
+ * Author input to {@link createGguiGadget}. A `createGguiGadget` call
+ * builds a gadget PACKAGE that exposes exactly one HOOK export — so
+ * the spec keeps the per-export teaching fields flat (`hook`,
+ * `description`, `usage`, `example`, `gotchas`, `permission`,
+ * `required`) alongside the package identity + transport fields
+ * (`package`, `version`, `bundleUrl`, …) and a `hookImpl` runtime
+ * function. The factory assembles these into a
+ * {@link GadgetDescriptor} of the package+exports shape.
+ *
+ * Generic over `TOutput` / `TOptions` so consumers get type-safe
+ * value + options surfaces. Defaults to `void` / `unknown` for hooks
+ * that take no options.
+ */
+interface GguiGadgetSpec<TOutput, TOptions = void> extends Omit<GadgetDescriptor, 'exports'>, Omit<GadgetExportBase, 'description' | 'usage' | 'example'> {
+    /**
+     * Hook name — `use`-prefixed camelCase. Becomes the single hook
+     * export of the assembled descriptor.
+     */
+    hook: string;
+    /** REQUIRED — see {@link GadgetExportBase.description}. */
+    description: string;
+    /** REQUIRED — see {@link GadgetExportBase.usage}. */
+    usage: string;
+    /** REQUIRED — see {@link GadgetExportBase.example}. */
+    example: JsonValue;
+    /**
+     * The React hook implementation. Conforms to
+     * {@link GadgetHook} — same shape stdlib hooks satisfy.
+     * Authors `import` underlying 3rd-party libs at build time and
+     * compose inside this function.
+     */
+    hookImpl: GadgetHook<TOutput, TOptions>;
+}
+/**
+ * Output of {@link createGguiGadget} — the React hook
+ * function with the serializable {@link GadgetDescriptor}
+ * descriptor attached as `.descriptor`. Authors export this as their
+ * primary surface; consumers call it as a hook and operators
+ * register the descriptor.
+ */
+type GguiGadget<TOutput, TOptions = void> = GadgetHook<TOutput, TOptions> & {
+    /** Serializable registry entry — register on App.gadgets. */
+    readonly descriptor: GadgetDescriptor;
+};
+/**
+ * Conformance violation thrown by the wrapper-author SDK
+ * ({@link createGguiGadget} / `defineGadgetPackage`) when the supplied
+ * spec fails the strict registry schema or the SDK-specific checks
+ * (`impl` shape). Carries the zod issues so authoring tools can
+ * highlight individual fields.
+ */
+declare class WrapperConformanceError extends Error {
+    readonly code: "wrapper_conformance";
+    readonly violations: ReadonlyArray<{
+        readonly path: ReadonlyArray<string | number>;
+        readonly message: string;
+    }>;
+    constructor(
+    /** Identifying label for the failing spec — a hook name
+     * (`createGguiGadget`) or a package name (`defineGadgetPackage`). */
+    label: string | undefined, violations: ReadonlyArray<{
+        readonly path: ReadonlyArray<string | number>;
+        readonly message: string;
+    }>);
+}
+/**
+ * Build a ggui gadget. See file-level docstring for
+ * the usage pattern.
+ *
+ * Throws {@link WrapperConformanceError} synchronously when the spec
+ * is malformed — caller-time validation means a bad wrapper fails at
+ * module-load, not at first invocation.
+ */
+declare function createGguiGadget<TOutput, TOptions = void>(spec: GguiGadgetSpec<TOutput, TOptions>): GguiGadget<TOutput, TOptions>;
+
+/**
+ * `defineGadgetPackage` — the wrapper-author SDK builder for a gadget
+ * PACKAGE that ships one or more exports, hooks AND/OR components,
+ * behind a single npm identity.
+ *
+ * Where {@link createGguiGadget} is the single-hook convenience (the
+ * common case — returns the callable hook with `.descriptor` grafted
+ * on), `defineGadgetPackage` is the general builder: it takes the
+ * package identity + transport metadata once, plus a list of export
+ * declarations, and returns the validated {@link GadgetDescriptor}.
+ *
+ * A gadget package mixing kinds — say a chart package exporting a
+ * `Chart` component + a `useChartTheme` hook — is exactly one
+ * descriptor with two `exports[]`. Authoring it:
+ *
+ *   ```ts
+ *   export const Chart: ComponentType<ChartProps> = (props) => { … };
+ *   export const useChartTheme: GadgetHook<ChartTheme> = () => { … };
+ *
+ *   export const chartDescriptor = defineGadgetPackage({
+ *     package: '@my-org/gadget-chart',
+ *     version: '0.0.1',
+ *     styleUrl: 'https://…/chart.css',
+ *     exports: [
+ *       { component: 'Chart', impl: Chart,
+ *         description: '…', usage: '…', example: { … } },
+ *       { hook: 'useChartTheme', impl: useChartTheme,
+ *         description: '…', usage: '…', example: { … } },
+ *     ],
+ *   });
+ *   ```
+ *
+ * The author exports each impl directly (typed where defined — no
+ * casts) and `defineGadgetPackage` produces the registry descriptor.
+ * `impl` is threaded purely so the SDK can conformance-check it is a
+ * function at module-load (the same fail-fast `createGguiGadget` does
+ * for `hookImpl`); the builder never inspects its signature.
+ *
+ * Throws {@link WrapperConformanceError} synchronously on a malformed
+ * spec — a bad package fails at module-load, not at first use.
+ */
+
+/**
+ * Any callable — a React hook or component. `defineGadgetPackage`
+ * conformance-checks `impl` is a function but never depends on its
+ * signature, so the broadest "some function" type is correct here
+ * (`never[]` params accept any concrete signature without variance
+ * friction; it is NOT `any` — the value stays opaque).
+ */
+type GadgetImpl = (...args: never[]) => unknown;
+/** Per-export teaching text — required for the registry-strict schema. */
+interface GadgetExportTeaching {
+    /** Human-readable description of what the export does. */
+    readonly description: string;
+    /** When / why / by-whom the export is used. */
+    readonly usage: string;
+    /** Concrete usage example for boilerplate + prompt priming. */
+    readonly example: JsonValue;
+    /** Anti-patterns + known gotchas surfaced in code-gen prompts. */
+    readonly gotchas?: string;
+    /** Optional Web-Permissions identifier the export gates on. */
+    readonly permission?: string;
+    /** Whether the UI MUST mount this export. Default `false`. */
+    readonly required?: boolean;
+}
+/** A hook export declaration — `use`-prefixed name + its impl. */
+interface GadgetHookExportSpec extends GadgetExportTeaching {
+    /** Hook name — `use`-prefixed camelCase (`HOOK_NAME_RE`). */
+    readonly hook: string;
+    /** The React hook implementation. */
+    readonly impl: GadgetImpl;
+}
+/** A component export declaration — PascalCase name + its impl. */
+interface GadgetComponentExportSpec extends GadgetExportTeaching {
+    /** Component name — PascalCase (`COMPONENT_NAME_RE`). */
+    readonly component: string;
+    /** The React component implementation. */
+    readonly impl: GadgetImpl;
+}
+/**
+ * One export of a gadget package — a hook or a component,
+ * discriminated by which identifier field is present. Mirrors the
+ * protocol's {@link GadgetExport} field-presence union.
+ */
+type GadgetExportSpec = GadgetHookExportSpec | GadgetComponentExportSpec;
+/** Author input to {@link defineGadgetPackage}. */
+interface GadgetPackageSpec {
+    /** Bare npm package name. */
+    readonly package: string;
+    /** Exact semver pin. */
+    readonly version: string;
+    /** ggui-hosted ESM bundle URL. */
+    readonly bundleUrl?: string;
+    /** Registry hostname the bundle URL is derived from. */
+    readonly bundleHost?: string;
+    /** `sha384-<base64>` SRI of the bundle. */
+    readonly bundleSri?: string;
+    /** Stylesheet URL the package ships. */
+    readonly styleUrl?: string;
+    /** Outbound origins the package's exports call at runtime (CSP). */
+    readonly connect?: readonly string[];
+    /** `App.publicEnv` keys the package's exports require. */
+    readonly requires?: readonly string[];
+    /** Published `.d.ts` URL — required registry-side for non-stdlib. */
+    readonly typesUrl?: string;
+    /** `sha384-<base64>` SRI of the `.d.ts`. */
+    readonly typesSri?: string;
+    /** The exports the package ships — at least one, hooks and/or
+     * components. */
+    readonly exports: readonly GadgetExportSpec[];
+}
+/**
+ * Build + validate a gadget package descriptor. See the file-level
+ * docstring for the authoring pattern.
+ *
+ * Throws {@link WrapperConformanceError} synchronously when the spec
+ * is malformed (non-function `impl`, missing teaching text, malformed
+ * package identity / export name).
+ */
+declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
+
+/**
+ * `@ggui-ai/gadgets/catalog-adapter`.
+ *
+ * The contract surface between the ggui server and a per-deployment
+ * gadget catalog. The wire-side `DataContract.clientCapabilities.gadgets`
+ * is intentionally narrow — it is package-keyed and carries identity
+ * only (`(package, export name)`, no `version`, no transport
+ * metadata), so push-time resolution looks up the matching
+ * {@link GadgetDescriptor} descriptor by npm package name. This module
+ * declares the pluggable "where do descriptors come from?" port + ships
+ * two batteries-included implementations:
+ *
+ *   - {@link InMemoryGadgetCatalog} — static map, configured at
+ *     construction. Right for tests, the OSS default seed, and
+ *     deployments that ship a fixed catalog at boot.
+ *
+ *   - {@link CachingGadgetCatalog} — decorator over any other adapter
+ *     with per-appId TTL caching + single-flight deduplication. Right
+ *     for production cloud paths where descriptors live in DynamoDB /
+ *     a registry service and re-fetching on every push would burn
+ *     network round-trips. Caches are scoped per-appId so two apps
+ *     never see each other's catalogs.
+ *
+ * ## Design contract
+ *
+ *   - One method: `list(appId)`. Single batch read — never an N+1
+ *     "fetch descriptor for one package at a time" pattern. The
+ *     resolution caller indexes the returned array by `package`
+ *     itself. Single network call per push (with cache, often zero).
+ *
+ *   - Return type is `readonly GadgetDescriptor[]` — the same shape the
+ *     wire push-time resolution + downstream consumers (boilerplate
+ *     generator, CSP builder, Permissions-Policy deriver, system
+ *     prompt builder) already speak.
+ *
+ *   - Errors propagate. Adapters MUST throw on retrieval failure
+ *     rather than returning an empty array — silent "no gadgets"
+ *     would let pushes through with broken gadget refs and surface
+ *     as render-time hook-resolution failures. The caller's job is
+ *     to decide whether the push fails (gate fires) or proceeds
+ *     ungated.
+ *
+ * ## Deployment-specific adapters
+ *
+ * Per-deployment adapters wear this same interface: a JSON-backed
+ * adapter reads from the `ggui.json#app.gadgets` array; a
+ * database-backed adapter reads from an app-metadata store. Both
+ * implement `GadgetCatalogAdapter`, so the enrichment pipeline doesn't
+ * care which environment is feeding it.
+ */
+
+/**
+ * Per-deployment source of registered gadget descriptors.
+ *
+ * Named parties: caller (push-time resolution / dev tools) ↔ adapter
+ * (deployment-specific descriptor backing store, e.g., JSON, DynamoDB,
+ * in-memory).
+ *
+ * Obligations:
+ *   - `list(appId)` MUST return the full set of descriptors registered
+ *     for `appId` in a single call. No pagination at this layer;
+ *     adapters that page internally MUST aggregate before returning.
+ *   - On retrieval failure, the adapter MUST throw — silently
+ *     returning `[]` is forbidden (it would mask broken catalogs).
+ *
+ * Failure mode: thrown error propagates to caller. Caller decides
+ * whether to fail the push (strict) or fall back to a default set
+ * (lenient).
+ *
+ * Observable violation: caller observes a thrown error or a
+ * descriptor-list whose contents are inconsistent with `appId`.
+ */
+interface GadgetCatalogAdapter {
+    /**
+     * Resolve the full registered gadget catalog for a given app.
+     *
+     * Single-batch by design. Callers MUST NOT call this in a loop
+     * per-package; index the returned array by `entry.package` instead.
+     */
+    list(appId: string): Promise<readonly GadgetDescriptor[]>;
+}
+/**
+ * Static map-backed adapter. Pre-populated at construction; never
+ * fetches anything at runtime. Right for tests, examples, and
+ * deployments whose catalog is known at boot.
+ */
+declare class InMemoryGadgetCatalog implements GadgetCatalogAdapter {
+    #private;
+    constructor(byApp: ReadonlyMap<string, readonly GadgetDescriptor[]>);
+    /**
+     * Convenience factory for the common "every app gets the same
+     * catalog" case (the OSS stdlib seed pattern). Apps not explicitly
+     * keyed fall back to the supplied default.
+     */
+    static withDefault(defaultEntries: readonly GadgetDescriptor[], perApp?: ReadonlyMap<string, readonly GadgetDescriptor[]>): InMemoryGadgetCatalog;
+    list(appId: string): Promise<readonly GadgetDescriptor[]>;
+}
+/**
+ * Decorator adapter — wraps any {@link GadgetCatalogAdapter} with
+ * per-appId TTL caching + single-flight deduplication. Right for
+ * production paths where the inner adapter hits DynamoDB / a registry
+ * service and per-push fetches would dominate latency.
+ *
+ * Concurrent `list(appId)` calls during a cache miss share ONE
+ * inflight Promise — no thundering herd against the inner adapter.
+ *
+ * Caches are scoped per-appId; entry TTL is configurable
+ * (default 30s — short enough that operator changes propagate
+ * promptly, long enough to amortize cold-start). Set `ttlMs: 0` for
+ * single-flight-only behavior (no TTL caching, just dedup).
+ */
+interface CachingGadgetCatalogOptions {
+    /**
+     * Per-entry time-to-live in milliseconds. Cache entries older than
+     * this are refetched on next `list()`. `0` disables TTL caching
+     * entirely (single-flight dedup only).
+     *
+     * Default: 30000 (30s).
+     */
+    readonly ttlMs?: number;
+    /**
+     * Clock injection for tests. Default `Date.now`.
+     */
+    readonly now?: () => number;
+}
+declare class CachingGadgetCatalog implements GadgetCatalogAdapter {
+    #private;
+    constructor(inner: GadgetCatalogAdapter, options?: CachingGadgetCatalogOptions);
+    list(appId: string): Promise<readonly GadgetDescriptor[]>;
+    /**
+     * Drop the cached entry for `appId`. Right for operator-triggered
+     * invalidation (gadget registered / unregistered / updated). When
+     * `appId` is omitted, drops every cached entry.
+     */
+    invalidate(appId?: string): void;
+}
+
+/**
+ * `getPublicEnv(key, opts?)`.
+ *
+ * Wrapper-author accessor for the public env channel. Reads values
+ * the operator stamped on `App.publicEnv` and the server projected
+ * (filtered to declared wrappers' `requires`) onto
+ * `globalThis.__ggui__.publicEnv`.
+ *
+ * Usage pattern (inside a wrapper's `hookImpl`):
+ *
+ *   ```ts
+ *   import { createGguiGadget, getPublicEnv } from '@ggui-ai/gadgets';
+ *   import mapboxgl from 'mapbox-gl';
+ *
+ *   export const useMapbox = createGguiGadget({
+ *     hook: 'useMapbox',
+ *     requires: ['GGUI_PUBLIC_APP_MAPBOX_TOKEN'],
+ *     hookImpl: (opts) => {
+ *       mapboxgl.accessToken = getPublicEnv('GGUI_PUBLIC_APP_MAPBOX_TOKEN');
+ *       return useMapboxInternal(opts);
+ *     },
+ *     // …
+ *   });
+ *   ```
+ *
+ * Semantics
+ * ---------
+ *
+ *   - **Throws** when called before the iframe runtime initializes
+ *     (`globalThis.__ggui__` absent). This indicates the wrapper is
+ *     running outside the ggui iframe (test misconfig, host SDK
+ *     misuse).
+ *   - **Throws** by default when the requested key is not present in
+ *     the registry. The thrown error names the missing key + lists
+ *     available keys — gives gadget authors actionable diagnostics
+ *     without leaking the values themselves.
+ *   - Pass `{ optional: true }` to get `undefined` for a missing key
+ *     instead of throwing. Use when the wrapper has a sensible
+ *     fallback (e.g., a default origin); the push gate enforces that
+ *     declared `requires` keys are present, so the typical wrapper
+ *     path uses the throwing default.
+ *   - Empty-string values are returned verbatim (the operator may
+ *     have intentionally configured a key with no value).
+ *
+ * The push gate (`assertPublicEnvSatisfied`) verifies the
+ * `App.publicEnv` satisfies every declared wrapper's `requires` BEFORE
+ * the iframe boots. So in well-configured deployments, the only
+ * `getPublicEnv` throws are gadget authoring bugs (typoed key, key
+ * not declared in `requires`). In production, the push gate catches
+ * the misconfiguration upstream.
+ */
+interface GetPublicEnvOptions {
+    /**
+     * When true, returns `undefined` for a missing key instead of
+     * throwing. Use sparingly — the push gate enforces declared
+     * `requires`, so a missing key usually indicates a wrapper bug
+     * (key not in `requires` array). The throwing default is the
+     * right call for keys that ARE declared in `requires`.
+     */
+    readonly optional?: boolean;
+}
+/**
+ * Return the public env value at `key`. Throws on missing-required;
+ * returns `undefined` when `{ optional: true }`.
+ *
+ * `target` is the global root to read from; defaults to `globalThis`.
+ * Exposed for tests; production callers omit it.
+ */
+declare function getPublicEnv(key: string, opts?: GetPublicEnvOptions, target?: typeof globalThis): string | undefined;
+
+/**
+ * `useGeolocation` — browser-capability hook for reading the user's
+ * current location via the Geolocation API. Satisfies
+ * `GadgetHook<GeolocationCoords, GeolocationOptions>`.
+ *
+ * Lifecycle:
+ *   - `idle` — initial, no request fired.
+ *   - `prompting` — permission prompt visible (browser-controlled).
+ *   - `active` — permission granted; for watch mode, position updates
+ *     stream as they arrive.
+ *   - `completed` — terminal for one-shot mode (`watch: false`) after
+ *     a successful read.
+ *   - `denied` — user rejected the permission prompt or the request
+ *     errored with `PERMISSION_DENIED`.
+ *   - `error` — any other failure (`POSITION_UNAVAILABLE`, `TIMEOUT`,
+ *     or `Geolocation API unavailable`).
+ *
+ * Contract authors declare this hook via
+ * `clientCapabilities.gadgets['@ggui-ai/gadgets'] = { useGeolocation: {} }`
+ * and the UI generator emits the import + call site. Values surface to
+ * the agent via `contextSpec` (the component code threads `value` into
+ * the relevant slot's setter).
+ */
+
+/** Coordinates returned by the hook. Pure JSON for easy contextSpec
+ *  threading. */
+interface GeolocationCoords {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly accuracy: number;
+    readonly altitude?: number;
+    readonly altitudeAccuracy?: number;
+    readonly heading?: number;
+    readonly speed?: number;
+    readonly timestamp: number;
+}
+/** Options accepted by `useGeolocation`. */
+interface GeolocationOptions {
+    /** Continuously stream updates instead of single read. Default: false. */
+    readonly watch?: boolean;
+    /** Request high-accuracy positioning. Default: false. */
+    readonly enableHighAccuracy?: boolean;
+    /** Max age (ms) of a cached position the browser may return.
+     *  Default: 0 (always fresh). */
+    readonly maximumAge?: number;
+    /** Request timeout in ms. Default: Infinity. */
+    readonly timeout?: number;
+}
+declare const useGeolocation: GadgetHook<GeolocationCoords, GeolocationOptions>;
+
+/**
+ * `useClipboardWrite` — browser-capability hook for writing text to
+ * the system clipboard via `navigator.clipboard.writeText`. Satisfies
+ * `GadgetHook<string, ClipboardWriteOptions>`.
+ *
+ * One-shot semantics: call `start({text})` to write; status moves
+ * `idle → prompting → completed` on success or `idle → prompting →
+ * denied/error` on failure. The hook's `value` carries the most
+ * recently written text so component code can confirm what landed
+ * on the clipboard.
+ *
+ * `useClipboardPaste` is a separate hook — the read direction has
+ * different permission semantics (requires explicit user-gesture
+ * activation in most browsers).
+ */
+
+interface ClipboardWriteOptions {
+    /** Text to write. Required at call site, not at hook construction. */
+    readonly text: string;
+}
+declare const useClipboardWrite: GadgetHook<string, ClipboardWriteOptions>;
+
+/**
+ * `useClipboardPaste` — browser-capability hook for reading text from
+ * the system clipboard via `navigator.clipboard.readText`. Satisfies
+ * `GadgetHook<string, void>`.
+ *
+ * Most browsers require an explicit user gesture (button click) to
+ * invoke `start()` — wire this hook to a "paste" button rather than
+ * firing on mount.
+ *
+ * Lifecycle: idle → prompting → completed (with the text in `value`)
+ * on success; denied/error on failure.
+ */
+
+declare const useClipboardPaste: GadgetHook<string>;
+
+/**
+ * `useNotifications` — browser-capability hook for showing system
+ * notifications via the Notification API. Satisfies
+ * `GadgetHook<NotificationResult, NotificationOptions>`.
+ *
+ * Permission semantics: the first `start()` call requests permission
+ * via `Notification.requestPermission()`; subsequent calls reuse the
+ * granted permission. Permission denial is sticky on the browser
+ * side — once denied, future `start()` calls error with
+ * `permission_denied` without re-prompting.
+ *
+ * Lifecycle: idle → prompting → completed (after notification
+ * dismissed/clicked) or denied/error.
+ */
+
+interface NotificationOptions_ {
+    readonly title: string;
+    readonly body?: string;
+    readonly icon?: string;
+    readonly tag?: string;
+}
+interface NotificationResult {
+    readonly outcome: 'clicked' | 'closed';
+    readonly tag?: string;
+}
+declare const useNotifications: GadgetHook<NotificationResult, NotificationOptions_>;
+
+/**
+ * `useFilePicker` — browser-capability hook for prompting the user
+ * to select one or more files. Uses `<input type="file">` as the
+ * universal fallback; the File System Access API
+ * (`showOpenFilePicker`) is preferred when available.
+ *
+ * Returns one entry per selected file with `name`, `size`, `type`,
+ * and the raw `File` handle on `_file` for component code that
+ * wants to read content (the contract doesn't carry the File over
+ * the wire — component reads + extracts what it needs for the
+ * agent's contextSpec / actionSpec payload).
+ *
+ * Lifecycle: idle → prompting → completed (with picked files) or
+ * denied/error.
+ */
+
+interface FilePickerOptions {
+    /** Allow multi-select. Default: false. */
+    readonly multiple?: boolean;
+    /** MIME-type filter (e.g., 'image/*', '.pdf'). Optional. */
+    readonly accept?: string;
+}
+interface PickedFile {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    /** Raw File handle. NOT serialized — component reads + extracts. */
+    readonly _file: File;
+}
+interface FilePickerResult {
+    readonly files: readonly PickedFile[];
+}
+declare const useFilePicker: GadgetHook<FilePickerResult, FilePickerOptions>;
+
+/**
+ * `useMicrophone` — browser-capability hook for capturing audio via
+ * `MediaDevices.getUserMedia({audio: true})` + MediaRecorder.
+ *
+ * Lifecycle: idle → prompting → active (recording) → completed
+ * (with the captured blob). `stop()` ends the recording; without it,
+ * the recording continues until the user revokes mic access or the
+ * tab loses focus.
+ *
+ * Returns the captured audio as a Blob + duration metadata so
+ * component code can thread the URL or upload-handle into a
+ * contextSpec slot or actionSpec payload.
+ */
+
+interface MicrophoneOptions {
+    /** MIME type for the recorder. Defaults to whatever the browser supports. */
+    readonly mimeType?: string;
+}
+interface MicrophoneResult {
+    readonly blob: Blob;
+    readonly durationMs: number;
+    readonly mimeType: string;
+}
+declare const useMicrophone: GadgetHook<MicrophoneResult, MicrophoneOptions>;
+
+/**
+ * `useCamera` — browser-capability hook for capturing a still photo
+ * via `MediaDevices.getUserMedia({video: true})` + canvas drawing.
+ *
+ * Lifecycle: idle → prompting → active (camera live) → completed
+ * (with the captured photo as a data URL). The hook returns a single
+ * snapshot per `start()` — call `stop()` to release the camera
+ * without taking a photo.
+ *
+ * Component code threads the data URL into a contextSpec slot or
+ * actionSpec payload. For continuous video / multi-frame capture, a
+ * different hook would be needed (out of v1 scope).
+ */
+
+interface CameraOptions {
+    /** Prefer front ('user') or rear ('environment') camera. Optional. */
+    readonly facingMode?: 'user' | 'environment';
+    /** MIME type for the encoded snapshot. Default: 'image/png'. */
+    readonly mimeType?: string;
+    /** JPEG quality 0–1. Only used when mimeType is image/jpeg. */
+    readonly quality?: number;
+}
+interface CameraResult {
+    /** Encoded snapshot as a data URL. */
+    readonly dataUrl: string;
+    readonly width: number;
+    readonly height: number;
+    readonly mimeType: string;
+}
+declare const useCamera: GadgetHook<CameraResult, CameraOptions>;
+
+export { CachingGadgetCatalog, type CachingGadgetCatalogOptions, type CameraOptions, type CameraResult, type ClipboardWriteOptions, type FilePickerOptions, type FilePickerResult, type GadgetCatalogAdapter, type GadgetComponentExportSpec, type GadgetExportSpec, type GadgetHookExportSpec, type GadgetImpl, type GadgetPackageSpec, type GeolocationCoords, type GeolocationOptions, type GetPublicEnvOptions, type GguiGadget, type GguiGadgetSpec, InMemoryGadgetCatalog, type MicrophoneOptions, type MicrophoneResult, type NotificationOptions_ as NotificationOptions, type NotificationResult, type PickedFile, WrapperConformanceError, createGguiGadget, defineGadgetPackage, getPublicEnv, useCamera, useClipboardPaste, useClipboardWrite, useFilePicker, useGeolocation, useMicrophone, useNotifications };