@shenora/react 0.9.1 → 0.11.0

package/README.md

@@ -1,165 +1,152 @@
-# @shenora/react
-
-React client for [Shenora](https://github.com/JiarongGu/Shenora) desktop hosts (.NET + WinForms +
-WebView2). The typed bridge between a React frontend and the Shenora host: correlated `invoke`
-with timeouts and structured errors, the event hub host notifications stream into, typed module
-services, React hooks, and a pluggable transport with a browser fallback so the UI can be
-developed in a plain browser. Headless by design — no UI components, bring your own design
-system. Versioned in lockstep with the `Shenora.*` NuGet packages.
-
-```ts
-import {
-  getBridge, useShenoraEvent, useShenoraQuery, BaseModuleService, createShenoraStore,
-} from '@shenora/react';
-
-// Once at startup, after your listeners are attached: it starts notification delivery (anything the
-// host buffered arrives in the first batch). Drop zones need no particular ordering against it — the
-// host clears them when a new DOCUMENT loads, not on this handshake.
-await getBridge().notifyReady();
-
-// a typed service per backend module:
-interface NoteRequests { GET_ALL: void; ADD: { title: string } }
-class NoteService extends BaseModuleService<NoteRequests> {
-  constructor() { super('NOTES'); }
-  getAll() { return this.send<Note[]>('GET_ALL'); }
-  add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
-}
-
-// in components:
-const { data, loading, refetch } = useShenoraQuery<Note[]>('NOTES', 'GET_ALL');
-useShenoraEvent<Note>('NOTES', 'ADDED', (note) => refetch());
-```
-
-Failed calls reject with `OperationError` — a structured `code` (an i18n key: translate
-`errors.{code}`) plus interpolation `parameters`, never raw host exception text.
-
-### Long-running work: post, then read a store
-
-`invoke` awaits a correlated reply and carries a timeout, and its handler's synchronous segment runs
-on the host's **UI thread** — so it is for calls that are quick and UI-thread-safe. Everything else
-posts and streams results back as events:
-
-```ts
-const useDeploy = createShenoraStore('DEPLOY', {
-  initial: { status: 'idle', lines: [] as string[] },
-  // Loaded on the FIRST subscriber, so a component that mounts mid-run isn't empty:
-  // events it missed cannot be replayed.
-  snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
-  on: {
-    PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
-    ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
-  },
-  actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
-});
-
-// any number of components share ONE subscription:
-const status = useDeploy((s) => s.status);
-useDeploy.actions.start({ env: 'prod' });
-```
-
-Use the **store for shared or long-lived state** and **`useShenoraEvent` for a one-off reaction in a
-single component**. A failed `post` has no promise to reject, so it is reported through the bridge's
-`onPostError` rather than vanishing — it is bridge-wide, so wire it once at startup
-(`getBridge()` takes no options):
-
-```ts
-configureBridge({ onPostError: (failure) => log.error(failure.module, failure.type, failure.error) });
-```
-
-### Tracked operations: a ready-made progress store
-
-For work the host tracks with `Shenora.Ipc`'s operation registry (an `IModuleContext.Run`/`Start`
-route on the C# side), `useShenoraOperations()` is a `createShenoraStore` instance built the same
-way as the example above — no per-feature event wiring needed:
-
-```ts
-import { useShenoraOperations } from '@shenora/react';
-
-const running = useShenoraOperations((s) => s.running);         // every in-flight operation
-const waiting = useShenoraOperations((s) => s.waiting);          // stopped, awaiting a decision — "needs you", one bucket
-const importJob = useShenoraOperations((s) => s.byId[jobId]);   // one, by id
-
-useShenoraOperations.actions.cancel(jobId);       // only does anything if the op opted into Cancellable
-useShenoraOperations.actions.dismiss(jobId);      // decline a waiting offer — refuses a running one
-useShenoraOperations.actions.wait(jobId);         // ASK the host to wait running work — refuses anything not running
-useShenoraOperations.actions.clearFinished();
-```
-
-`operation.progress` is an exported `OperationProgress` (`{ value: number; total?: number; unit?:
-string }`) — import the type rather than re-declaring the shape — the APP's own unit
-(bytes-of-a-known-total, items-of-a-known-total, an absolute count with no known total, or a genuine
-percent), never a kit-assumed percentage: `total` is the denominator when one is known and `undefined`
-when there isn't one, and `unit` is app-defined and uninterpreted, exactly like `kind`. The kit ships
-no percent helper — render a ratio only when you have a `total`:
-
-```ts
-import type { OperationProgress } from '@shenora/react';
-
-function format(progress?: OperationProgress): string {
-  if (!progress) return 'starting…';
-  return progress.total
-    ? `${Math.round((progress.value / progress.total) * 100)}%`
-    : `${progress.value}${progress.unit ? ` ${progress.unit}` : ''}`;   // no known total
-}
-```
-
-That division is your own policy, not the kit's, which is why it lives here instead of in `src/`.
-
-For the two events the store deliberately does NOT subscribe to — `OPERATION_RESUME_REQUESTED` and
-`OPERATION_WAIT_REQUESTED`, which target the OWNING module's service rather than this generic store —
-the module name and the event vocabulary are exported too, so you match by symbol and stay inside the
-host↔client mirror the wire tests pin:
-
-```ts
-import { OperationEventTypes, OperationModuleName, useShenoraEvent } from '@shenora/react';
-
-useShenoraEvent(OperationModuleName, OperationEventTypes.ResumeRequested, (payload) => …);
-```
-
-It snapshots via `LIST` on first subscribe (so a progress strip that mounts mid-run isn't empty), then
-folds `OPERATION_UPDATED` by id — one subscription however many components read it. The client
-mirrors the host's three bands (design §5A.2): `running` (Active), `waiting` (Waiting), and `finished`
-(Terminal). All three are derived from `byId` on every read, never a second copy to keep in sync —
-`waiting` is a single-status filter, exactly like `running`. `OperationStatus` carries ONE waiting
-value reached ONE way — the host's `IOperation.Wait` on a live operation — so there is no sub-case to
-tell apart. Filtering by your own `module`/`kind` is a plain `Array.filter` over any of them. A
-`waiting` operation carries `waitReason` — an app-defined string, like `kind`, OPTIONAL on the host
-side — for your UI to branch on. The host never prunes a waiting entry on its own: it stays until
-someone resumes, dismisses, or finishes it. `resume`/`dismiss`/`wait` are all fire-and-forget client
-requests — the host's own `IOperation.Wait`/`Resume` (called by whoever owns the operation, hearing
-`OPERATION_WAIT_REQUESTED`/`OPERATION_RESUME_REQUESTED`) is what actually changes the state; asking
-is not acting. `clearFinished`/`resume`/`wait` do not touch local state themselves at all: the host's
-`OPERATION_REMOVED { operationIds }` is the ONE authoritative removal signal the store folds, deleting
-exactly the named ids — `MaxHistory` eviction and `clearFinished`
-publish it, so a long-lived store's mirror of bounded host history cannot drift from what the host
-actually did (this replaced two hand-written optimistic local prunes that a past release carried —
-one of which was this project's only Critical, a `resume` prune that dropped a still-waiting row).
-`dismiss` never needed one, since the host's `Dismiss` publishes an ordinary terminal snapshot over
-the wire, the same as a real cancel. Use `createOperationsStore({ module, scope })` instead of the
-default export if your host renamed `OperationRegistryOptions.ModuleName` or
-you need a scope-filtered instance (a secondary window, an auxiliary session) — `clearFinished`
-forwards that scope so clearing history in one window cannot wipe another's.
-
-### Observing the whole stream
-
-`useShenoraEvent` and `createShenoraStore` listen for an exact `(module, type)`. When the vocabulary
-isn't knowable up front — plug-in-contributed events, a diagnostics tap, or an adoption shim keeping
-a legacy "every host message" handler alive while features migrate one at a time — subscribe broadly
-instead. Both mirror the host's `IEventBus` and return an unsubscribe:
-
-```ts
-const off = eventBus.subscribeToAll((event) => log.debug(event.module, event.type, event.payload));
-eventBus.subscribeToModule('DEPLOY', (event) => audit(event));   // every type from one module
-```
-
-Delivery is narrowest-first — exact pair, then module, then catch-all — so a broad observer never
-runs ahead of the feature code it is observing. Prefer `subscribe` when you know the pair: a
-catch-all wakes for every event on the bus.
-
-Pure-UI development in a plain browser: pass a `fallback` to `configureBridge` (gated behind
-`import.meta.env.DEV`) to answer requests with canned data. Other shells (WebSocket,
-mobile/Capacitor) implement the small `ShenoraTransport` seam and speak the same envelopes.
-For CDP-driven testing, `installDevInterceptor()` records IPC/event traffic into ring buffers
-and exposes `window.__shenora.call()/waitEvent()`.
-
-MIT © Jiarong Gu
+# @shenora/react
+
+React client for [Shenora](https://github.com/JiarongGu/Shenora) desktop hosts (.NET + WinForms +
+WebView2). The typed bridge between a React frontend and the Shenora host: correlated `invoke`
+with timeouts and structured errors, the event hub host notifications stream into, typed module
+services, React hooks, and a pluggable transport with a browser fallback so the UI can be
+developed in a plain browser. Headless by design — no UI components, bring your own design
+system. Versioned in lockstep with the `Shenora.*` NuGet packages.
+
+```ts
+import {
+  getBridge, useShenoraEvent, useShenoraQuery, BaseModuleService, createShenoraStore,
+} from '@shenora/react';
+
+// Once at startup, after your listeners are attached: it starts notification delivery (anything the
+// host buffered arrives in the first batch). Drop zones need no particular ordering against it — the
+// host clears them when a new DOCUMENT loads, not on this handshake.
+await getBridge().notifyReady();
+
+// a typed service per backend module:
+interface NoteRequests { GET_ALL: void; ADD: { title: string } }
+class NoteService extends BaseModuleService<NoteRequests> {
+  constructor() { super('NOTES'); }
+  getAll() { return this.send<Note[]>('GET_ALL'); }
+  add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
+}
+
+// in components:
+const { data, loading, refetch } = useShenoraQuery<Note[]>('NOTES', 'GET_ALL');
+useShenoraEvent<Note>('NOTES', 'ADDED', (note) => refetch());
+```
+
+Failed calls reject with `ShenoraError` — a structured `code` (an i18n key: translate
+`errors.{code}`) plus interpolation `parameters`, never raw host exception text.
+
+### Long-running work: post, then read a store
+
+`invoke` awaits a correlated reply and carries a timeout, and its handler's synchronous segment runs
+on the host's **UI thread** — so it is for calls that are quick and UI-thread-safe. Everything else
+posts and streams results back as events:
+
+```ts
+const useDeploy = createShenoraStore('DEPLOY', {
+  initial: { status: 'idle', lines: [] as string[] },
+  // Loaded on the FIRST subscriber, so a component that mounts mid-run isn't empty:
+  // events it missed cannot be replayed.
+  snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
+  on: {
+    PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
+    ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
+  },
+  actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
+});
+
+// any number of components share ONE subscription:
+const status = useDeploy((s) => s.status);
+useDeploy.actions.start({ env: 'prod' });
+```
+
+Use the **store for shared or long-lived state** and **`useShenoraEvent` for a one-off reaction in a
+single component**. A failed `post` has no promise to reject, so it is reported through the bridge's
+`onPostError` rather than vanishing — it is bridge-wide, so wire it once at startup
+(`getBridge()` takes no options):
+
+```ts
+configureBridge({ onPostError: (failure) => log.error(failure.module, failure.type, failure.error) });
+```
+
+### Requests in flight: a ready-made progress store
+
+Every request the host handles is tracked automatically — there is nothing to declare on either side.
+`useShenoraRequests()` is a `createShenoraStore` instance built the same way as the example above:
+
+```ts
+import { useShenoraRequests } from '@shenora/react';
+
+const running = useShenoraRequests((s) => s.running);           // every request still in flight
+const finished = useShenoraRequests((s) => s.finished);         // retained history, newest first
+const importJob = useShenoraRequests((s) => s.byId[requestId]); // one, by id
+
+useShenoraRequests.actions.cancel(requestId);   // XMLHttpRequest.abort() — the id you sent with
+useShenoraRequests.actions.clearFinished();
+```
+
+🔴 **The id is the one you already have.** `requestId` is the `id` of the request you sent — there is no
+second identity to correlate. Cancelling it targets the token the route is running under.
+
+⚠ **Most requests never appear here, and that is the design.** The host stays SILENT for the first
+50 ms (`IpcRequestTrackerOptions.GracePeriod`): a request that finishes inside that window emits no
+event at all — no running snapshot, no completion, nothing retained. So this store is a list of work
+that is actually *taking a while*, not a log of every call your page made. Nobody wants a spinner for
+five milliseconds of work, and the clock decides that at run time rather than a module author guessing
+at authoring time.
+
+`request.progress` is an exported `IpcProgress` (`{ value: number; total?: number; unit?: string }`) —
+import the type rather than re-declaring the shape. It is the APP's own unit (bytes of a known total,
+items of a known total, an absolute count with no known total, or a genuine percent), never a
+kit-assumed percentage: `total` is the denominator when one is known and `undefined` when there is
+none, and `unit` is app-defined and uninterpreted. The kit ships no percent helper — render a ratio
+only when you have a `total`:
+
+```ts
+import type { IpcProgress } from '@shenora/react';
+
+function format(progress?: IpcProgress): string {
+  if (!progress) return 'starting…';
+  return progress.total
+    ? `${Math.round((progress.value / progress.total) * 100)}%`
+    : `${progress.value}${progress.unit ? ` ${progress.unit}` : ''}`;   // no known total
+}
+```
+
+That division is your own policy, not the kit's, which is why it lives here instead of in `src/`.
+
+The store snapshots via `LIST` on first subscribe (so a progress strip that mounts mid-run is not
+empty), then folds `REQUEST_UPDATED` by id — one subscription however many components read it. Two
+bands, both derived from `byId` on every read: `running` and `finished`. Filtering by your own
+`module`/`type` is a plain `Array.filter` over either.
+
+`clearFinished` does not touch local state itself: the host's `REQUEST_REMOVED { requestIds }` is the
+one authoritative removal signal the store folds, deleting exactly the named ids. History eviction and
+`clearFinished` both publish it, so a long-lived store's mirror of bounded host history cannot drift
+from what the host actually did.
+
+⚠ **Work nobody requested does not belong here.** A scheduled job, a background sync, anything the host
+starts on its own — those have no request behind them and no response to wait for, so they report on
+their own event stream via `useShenoraEvent`. Squeezing them in here is what the previous design did,
+and it is why it needed a "waiting" state nothing else could explain.
+
+### Observing the whole stream
+
+`useShenoraEvent` and `createShenoraStore` listen for an exact `(module, type)`. When the vocabulary
+isn't knowable up front — plug-in-contributed events, a diagnostics tap, or an adoption shim keeping
+a legacy "every host message" handler alive while features migrate one at a time — subscribe broadly
+instead. Both mirror the host's `IEventBus` and return an unsubscribe:
+
+```ts
+const off = eventBus.subscribeToAll((event) => log.debug(event.module, event.type, event.payload));
+eventBus.subscribeToModule('DEPLOY', (event) => audit(event));   // every type from one module
+```
+
+Delivery is narrowest-first — exact pair, then module, then catch-all — so a broad observer never
+runs ahead of the feature code it is observing. Prefer `subscribe` when you know the pair: a
+catch-all wakes for every event on the bus.
+
+Pure-UI development in a plain browser: pass a `fallback` to `configureBridge` (gated behind
+`import.meta.env.DEV`) to answer requests with canned data. Other shells (WebSocket,
+mobile/Capacitor) implement the small `ShenoraTransport` seam and speak the same envelopes.
+For CDP-driven testing, `installDevInterceptor()` records IPC/event traffic into ring buffers
+and exposes `window.__shenora.call()/waitEvent()`.
+
+MIT © Jiarong Gu

package/dist/bridge.d.ts

@@ -89,7 +89,7 @@ export declare class ShenoraBridge {
     get isAvailable(): boolean;
     /**
      * Send a request and await its typed response data. A failed response rejects with the
-     * structured {@link OperationError} (code + parameters); no response within the timeout
+     * structured {@link ShenoraError} (code + parameters); no response within the timeout
      * rejects with code `TIMEOUT`; no transport and no fallback rejects with `NO_TRANSPORT`.
      */
     invoke<TData = unknown, TPayload = unknown>(module: string, type: string, options?: InvokeOptions<TPayload>): Promise<TData>;
@@ -109,7 +109,9 @@ export declare class ShenoraBridge {
      *
      * Failures are not silent. There is no promise to reject, so a failed response is reported through
      * `onPostError` (default `console.error`) rather than being dropped the way an unmatched response
-     * otherwise is. Nothing is queued and no timer is set, so there is nothing to leak and no deadline.
+     * otherwise is. ⚠ Reporting it means the id IS remembered — see {@link ShenoraBridgeOptions.maxTrackedPosts},
+     * which caps the set drop-oldest so a host that never answers cannot grow it without bound. No TIMER is
+     * set, though, so there is no deadline and nothing to fire later.
      *
      * No transport (a plain browser tab) is a silent no-op, matching the fire-and-forget contract —
      * unlike `invoke`, there is no caller waiting to be told. **A DISPOSED bridge is the same silent

package/dist/bridge.js

@@ -1,4 +1,4 @@
-import { OperationError } from './errors.js';
+import { ShenoraError } from './errors.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { randomId } from './internal.js';
 import { createHostTransport } from './transport.js';
@@ -43,7 +43,7 @@ export class ShenoraBridge {
     }
     /**
      * Send a request and await its typed response data. A failed response rejects with the
-     * structured {@link OperationError} (code + parameters); no response within the timeout
+     * structured {@link ShenoraError} (code + parameters); no response within the timeout
      * rejects with code `TIMEOUT`; no transport and no fallback rejects with `NO_TRANSPORT`.
      */
     invoke(module, type, options = {}) {
@@ -51,7 +51,7 @@ export class ShenoraBridge {
             // Fail fast: the transport subscription is gone, so a response could never correlate —
             // without this the call would burn the full timeout (stale references after
             // configureBridge replaced the default are the typical way here).
-            return Promise.reject(new OperationError({
+            return Promise.reject(new ShenoraError({
                 code: IpcErrorCodes.noTransport,
                 message: `Bridge disposed — ${module}.${type} cannot be sent.`,
             }));
@@ -80,18 +80,25 @@ export class ShenoraBridge {
                 // value is already settled.
                 if (!isThenable(result))
                     return Promise.resolve(result);
+                // ⚠ The loser's timer must be CLEARED, as every other path in this file does — the real invoke's
+                // timeout handler, its transport-throw catch, its response path and `dispose`. Leaving it holds a
+                // live timer per call for the full timeout
+                // (30 s by default), each holding its closure. Harmless to a caller, because `race` has already
+                // settled and has a rejection handler attached either way, but it is the same "one site out of
+                // N" shape the rest of this file is careful about, and it keeps timers pending in a test run.
+                let timer;
                 return Promise.race([
                     Promise.resolve(result),
                     new Promise((_, reject) => {
-                        setTimeout(() => reject(new OperationError({
+                        timer = setTimeout(() => reject(new ShenoraError({
                             code: IpcErrorCodes.timeout,
                             message: `${module}.${type} timed out after ${timeoutMs} ms (in the configured fallback).`,
                             parameters: { module, type },
                         })), timeoutMs);
                     }),
-                ]);
+                ]).finally(() => clearTimeout(timer));
             }
-            return Promise.reject(new OperationError({
+            return Promise.reject(new ShenoraError({
                 code: IpcErrorCodes.noTransport,
                 message: `No transport for ${module}.${type} — not inside a Shenora host, and no fallback is configured.`,
             }));
@@ -99,7 +106,7 @@ export class ShenoraBridge {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(request.id);
-                reject(new OperationError({
+                reject(new ShenoraError({
                     code: IpcErrorCodes.timeout,
                     message: `${module}.${type} timed out after ${timeoutMs} ms.`,
                     parameters: { module, type },
@@ -136,7 +143,9 @@ export class ShenoraBridge {
      *
      * Failures are not silent. There is no promise to reject, so a failed response is reported through
      * `onPostError` (default `console.error`) rather than being dropped the way an unmatched response
-     * otherwise is. Nothing is queued and no timer is set, so there is nothing to leak and no deadline.
+     * otherwise is. ⚠ Reporting it means the id IS remembered — see {@link ShenoraBridgeOptions.maxTrackedPosts},
+     * which caps the set drop-oldest so a host that never answers cannot grow it without bound. No TIMER is
+     * set, though, so there is no deadline and nothing to fire later.
      *
      * No transport (a plain browser tab) is a silent no-op, matching the fire-and-forget contract —
      * unlike `invoke`, there is no caller waiting to be told. **A DISPOSED bridge is the same silent
@@ -232,7 +241,7 @@ export class ShenoraBridge {
         this.unsubscribe?.();
         for (const [id, entry] of this.pending) {
             clearTimeout(entry.timer);
-            entry.reject(new OperationError({ code: IpcErrorCodes.noTransport, message: 'Bridge disposed.' }));
+            entry.reject(new ShenoraError({ code: IpcErrorCodes.noTransport, message: 'Bridge disposed.' }));
             this.pending.delete(id);
         }
         // Unawaited ids are pure bookkeeping with nothing to settle — drop them so a disposed bridge
@@ -285,7 +294,7 @@ export class ShenoraBridge {
                 entry.resolve(response.data);
             }
             else {
-                entry.reject(new OperationError(response.error ?? { code: IpcErrorCodes.unknownError }));
+                entry.reject(new ShenoraError(response.error ?? { code: IpcErrorCodes.unknownError }));
             }
             return;
         }

package/dist/clipboard.d.ts

@@ -0,0 +1,94 @@
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** Media type for PNG bytes — the interchange image format every platform and browser reads. */
+export declare const PNG_IMAGE = "image/png";
+/** Media type for UTF-8 HTML, for a paste that keeps its formatting. */
+export declare const HTML = "text/html";
+/**
+ * One clipboard item and every representation it offers.
+ *
+ * `text` and `files` are named because every platform has a first-class API for them; everything else
+ * lives in `formats`, keyed by media type — {@link PNG_IMAGE}, {@link HTML}, or your own
+ * `application/…` type, which the host carries verbatim so a paste can round-trip it losslessly.
+ */
+export interface ClipboardContent {
+    /** The plain-text representation. */
+    text?: string;
+    /**
+     * Absolute paths, for the copy a file manager can paste.
+     * ⚠ DESKTOP only — gate on {@link ClipboardHandle.canCopyFiles}.
+     */
+    files?: string[];
+    /** Every other representation, as raw bytes keyed by media type. */
+    formats?: Record<string, Uint8Array>;
+}
+/** What actually crosses the wire: the same shape with the byte payloads base64-encoded. */
+interface ClipboardWire {
+    text?: string;
+    files?: string[];
+    formats?: Record<string, string>;
+}
+interface ClipboardRequests {
+    READ: undefined;
+    WRITE: {
+        content: ClipboardWire;
+    };
+    CLEAR: undefined;
+}
+/**
+ * Typed client for the host's `SHENORA.CLIPBOARD` module (`ClipboardModule`).
+ *
+ * ⚠ **`files` is a DESKTOP capability** and rejects with `IpcErrorCodes.capabilityNotSupported` on a
+ * phone. Do not catch that — ask first, via {@link useClipboard}, and do not render the control.
+ */
+export declare class ClipboardAccess extends BaseModuleService<ClipboardRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /**
+     * Everything the clipboard is offering — **no user gesture, no permission prompt, no focus
+     * requirement**, which is the half `navigator.clipboard.read()` cannot give you.
+     */
+    read(): Promise<ClipboardContent>;
+    /**
+     * Replace the clipboard with one item, every representation at once.
+     *
+     * ⚠ Bytes cross the IPC envelope as base64, so a large picture is a large message. A page copying
+     * something big should hand the host a path and let it read the file instead.
+     */
+    write(content: ClipboardContent): Promise<void>;
+    /** Leave the clipboard holding nothing. */
+    clear(): Promise<void>;
+}
+/** What {@link useClipboard} returns: the client, plus what this shell will actually honour. */
+export interface ClipboardHandle {
+    /** The typed client. Stable across renders. */
+    clipboard: ClipboardAccess;
+    /**
+     * This shell can put a FILE LIST on the clipboard — desktop only. Decide what to RENDER with it; a
+     * refused call rejects, which is the honest answer to a question that should not have been asked.
+     */
+    canCopyFiles: boolean;
+}
+/**
+ * The clipboard client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { clipboard, canCopyFiles } = useClipboard();
+ * return (
+ *   <>
+ *     <button onClick={() => navigator.clipboard.writeText(name)}>Copy name</button>
+ *     {canCopyFiles && (
+ *       <button onClick={() => clipboard.write({ text: name, files: [path] })}>Copy file</button>
+ *     )}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ Note the first button: plain text on a click is the browser's job and stays there. This hook is for
+ * the file copy beside it.
+ *
+ * ⚠ `canCopyFiles` is `false` until the handshake has landed, so await `bridge.notifyReady()` before
+ * rendering this tree — see {@link useShellInfo} for why the read is synchronous.
+ */
+export declare function useClipboard(clipboard?: ClipboardAccess): ClipboardHandle;
+export {};