@shenora/react 0.9.0 → 0.10.0

package/dist/fileDialogs.d.ts

@@ -0,0 +1,153 @@
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** One dialog filter row (e.g. `{ name: 'Images', extensions: ['png', 'jpg'] }`). */
+export interface FileDialogFilter {
+    name: string;
+    /** Extensions WITHOUT the dot or wildcard — `'png'`, not `'*.png'`. */
+    extensions: string[];
+}
+/**
+ * What EVERY dialog call takes. The per-dialog shapes below add what only that dialog can honour —
+ * which is the point: a save-only field on a folder pick will not compile.
+ */
+export interface FileDialogOptions {
+    /** Dialog title. Omit for a neutral per-dialog default. */
+    title?: string;
+    /** Start location when nothing is remembered. */
+    defaultPath?: string;
+    /**
+     * Key under which the host remembers the last-used directory and restores it next time.
+     * Remembered PER KEY, so "import" and "export" stay separate. Omit for no memory.
+     */
+    rememberPathKey?: string;
+}
+/** Inputs for {@link FileDialogs.openFile}. */
+export interface OpenFileOptions extends FileDialogOptions {
+    /** Filter rows; omit/empty = "All Files". */
+    filters?: FileDialogFilter[];
+    /** Initial file name shown in the dialog. */
+    fileName?: string;
+    /** Require the picked file to exist. Default true. Desktop hint — a mobile picker ignores it. */
+    checkFileExists?: boolean;
+    /** Require the path to exist. Default true. Desktop hint. */
+    checkPathExists?: boolean;
+    /** Validate the host's file-name rules. Default true. Desktop hint. */
+    validateNames?: boolean;
+}
+/** Inputs for {@link FileDialogs.openFolder}. */
+export interface OpenFolderOptions extends FileDialogOptions {
+    /** Also allow picking a FILE. The host swaps in a file dialog with relaxed validation. */
+    allowFileSelection?: boolean;
+    /** Filter rows for the FILE half — ⚠ ignored unless {@link allowFileSelection} is set. */
+    filters?: FileDialogFilter[];
+}
+/** Inputs for {@link FileDialogs.saveFile} and {@link FileDialogs.saveText}. */
+export interface SaveFileOptions extends FileDialogOptions {
+    /** Filter rows; omit/empty = "All Files". */
+    filters?: FileDialogFilter[];
+    /** The name being suggested. */
+    fileName?: string;
+    /** Extension appended when the user omits one (no dot). */
+    defaultExtension?: string;
+    /** Prompt before overwriting. Default true. Desktop hint. */
+    overwritePrompt?: boolean;
+    /** Require the path to exist. Default true. Desktop hint. */
+    checkPathExists?: boolean;
+}
+/**
+ * A dialog outcome. ⚠ **THREE outcomes, not two** — and the third is the one that surprises people:
+ * cancelled (`success: false`); succeeded with an addressable location (`filePath` set); and
+ * **succeeded with NO location**, which is what {@link FileDialogs.saveText} returns on a phone,
+ * because the bytes went to a revocable grant rather than somewhere the app may reopen.
+ *
+ * So `success && filePath === undefined` is legitimate, and `result.filePath!` after checking
+ * `success` is a null-reference waiting for a mobile shell.
+ */
+export interface FileDialogResult {
+    success: boolean;
+    filePath?: string;
+}
+interface FileDialogRequests {
+    OPEN_FILE: {
+        options?: OpenFileOptions;
+    };
+    OPEN_FOLDER: {
+        options?: OpenFolderOptions;
+    };
+    SAVE_FILE: {
+        options?: SaveFileOptions;
+    };
+    SAVE_TEXT: {
+        text: string;
+        options?: SaveFileOptions;
+    };
+}
+/**
+ * Typed client for the host's `FILE_DIALOGS` module (`FileDialogFacade`).
+ *
+ * ⚠ **Two of these are DESKTOP capabilities.** `openFolder` and `saveFile` have no expression on a
+ * phone and reject with `IpcErrorCodes.capabilityNotSupported` there. Do not catch that — ask first,
+ * via {@link useFileDialogs}, and do not render the control at all. `openFile` and `saveText` work
+ * everywhere.
+ */
+export declare class FileDialogs extends BaseModuleService<FileDialogRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /** Pick an existing file. Available on every shell. */
+    openFile(options?: OpenFileOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}.
+     *
+     * On mobile "open folder" means the camera roll, the app's own space, or a scoped grant: the same
+     * word with a different guarantee, which is why there is no portable version of it.
+     */
+    openFolder(options?: OpenFolderOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a save destination and get the PATH back. ⚠ DESKTOP only — gate on
+     * {@link FileDialogsHandle.canPickSavePath}. "Give me somewhere to write later" has no mobile
+     * expression; use {@link saveText} in portable code, which also works on the desktop.
+     */
+    saveFile(options?: SaveFileOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a destination AND write `text` to it, in one call — the PORTABLE save, working everywhere
+     * because the HOST does the writing.
+     *
+     * ⚠ For text a page legitimately holds: an export, a report, a config. The content crosses the IPC
+     * envelope as JSON, so anything large or binary should be produced host-side and saved through the
+     * host's own `IFileDialogs.SaveAsync`, where it never enters a message.
+     */
+    saveText(text: string, options?: SaveFileOptions): Promise<FileDialogResult>;
+}
+/** What {@link useFileDialogs} returns: the client, plus what this shell will actually honour. */
+export interface FileDialogsHandle {
+    /** The typed client. Stable across renders. */
+    dialogs: FileDialogs;
+    /** This shell can pick an existing file. */
+    canPickFile: boolean;
+    /** This shell can pick a FOLDER — desktop only (see {@link FileDialogs.openFolder}). */
+    canPickFolder: boolean;
+    /** This shell can return a save PATH — desktop only (see {@link FileDialogs.saveFile}). */
+    canPickSavePath: boolean;
+}
+/**
+ * The dialogs client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { dialogs, canPickFolder } = useFileDialogs();
+ * return (
+ *   <>
+ *     <button onClick={() => dialogs.openFile()}>Choose a file</button>
+ *     {canPickFolder && <button onClick={() => dialogs.openFolder()}>Choose a folder</button>}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ **Use these to decide what to RENDER, not what to catch.** A refused call rejects with
+ * `IpcErrorCodes.capabilityNotSupported`, which is the honest answer to a question that should not
+ * have been asked — the button should not have been there.
+ *
+ * ⚠ Every flag 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 useFileDialogs(dialogs?: FileDialogs): FileDialogsHandle;
+export {};

package/dist/fileDialogs.js

@@ -0,0 +1,90 @@
+/**
+ * The page's half of the host's `FILE_DIALOGS` module — native file/folder/save dialogs, and the
+ * capability gating that lets ONE bundle ship to every shell.
+ *
+ * Mirrors `Shenora.Ipc.FileDialogFacade`. The wire names here are pinned against the host's own
+ * constants by `WireMirrorTests`, not by care.
+ */
+import { useMemo } from 'react';
+import { useShellInfo } from './hooks.js';
+import { BaseModuleService } from './moduleService.js';
+import { ShellCapabilities } from './types.js';
+/**
+ * Typed client for the host's `FILE_DIALOGS` module (`FileDialogFacade`).
+ *
+ * ⚠ **Two of these are DESKTOP capabilities.** `openFolder` and `saveFile` have no expression on a
+ * phone and reject with `IpcErrorCodes.capabilityNotSupported` there. Do not catch that — ask first,
+ * via {@link useFileDialogs}, and do not render the control at all. `openFile` and `saveText` work
+ * everywhere.
+ */
+export class FileDialogs extends BaseModuleService {
+    constructor(bridge) {
+        super('FILE_DIALOGS', bridge);
+    }
+    /** Pick an existing file. Available on every shell. */
+    openFile(options) {
+        return this.send('OPEN_FILE', { payload: { options } });
+    }
+    /**
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}.
+     *
+     * On mobile "open folder" means the camera roll, the app's own space, or a scoped grant: the same
+     * word with a different guarantee, which is why there is no portable version of it.
+     */
+    openFolder(options) {
+        return this.send('OPEN_FOLDER', { payload: { options } });
+    }
+    /**
+     * Pick a save destination and get the PATH back. ⚠ DESKTOP only — gate on
+     * {@link FileDialogsHandle.canPickSavePath}. "Give me somewhere to write later" has no mobile
+     * expression; use {@link saveText} in portable code, which also works on the desktop.
+     */
+    saveFile(options) {
+        return this.send('SAVE_FILE', { payload: { options } });
+    }
+    /**
+     * Pick a destination AND write `text` to it, in one call — the PORTABLE save, working everywhere
+     * because the HOST does the writing.
+     *
+     * ⚠ For text a page legitimately holds: an export, a report, a config. The content crosses the IPC
+     * envelope as JSON, so anything large or binary should be produced host-side and saved through the
+     * host's own `IFileDialogs.SaveAsync`, where it never enters a message.
+     */
+    saveText(text, options) {
+        return this.send('SAVE_TEXT', { payload: { text, options } });
+    }
+}
+/**
+ * The dialogs client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { dialogs, canPickFolder } = useFileDialogs();
+ * return (
+ *   <>
+ *     <button onClick={() => dialogs.openFile()}>Choose a file</button>
+ *     {canPickFolder && <button onClick={() => dialogs.openFolder()}>Choose a folder</button>}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ **Use these to decide what to RENDER, not what to catch.** A refused call rejects with
+ * `IpcErrorCodes.capabilityNotSupported`, which is the honest answer to a question that should not
+ * have been asked — the button should not have been there.
+ *
+ * ⚠ Every flag 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 function useFileDialogs(dialogs) {
+    const shell = useShellInfo();
+    // The service is stateless and holds only its module name, but a fresh instance per render would
+    // still make it useless as an effect dependency — the same reason useWindowMaximized caches one.
+    const client = useMemo(() => dialogs ?? new FileDialogs(), [dialogs]);
+    const capabilities = shell?.capabilities;
+    return useMemo(() => ({
+        dialogs: client,
+        canPickFile: capabilities?.includes(ShellCapabilities.filePicker) ?? false,
+        canPickFolder: capabilities?.includes(ShellCapabilities.folderPicker) ?? false,
+        canPickSavePath: capabilities?.includes(ShellCapabilities.savePicker) ?? false,
+    }), [client, capabilities]);
+}

package/dist/hooks.d.ts

@@ -1,11 +1,33 @@
 import { type ShenoraBridge } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
-import type { EventMessage } from './types.js';
+import type { EventMessage, ShellInfo } from './types.js';
 /** Host access for components: the (default) bridge and whether a host transport exists. */
 export declare function useShenora(): {
     isAvailable: boolean;
     bridge: ShenoraBridge;
 };
+/**
+ * What the host IS and what it can do — the way one bundle renders correctly on every shell.
+ * Branch on {@link ShellInfo.capabilities}, never on {@link ShellInfo.name}.
+ *
+ * ```tsx
+ * const shell = useShellInfo();
+ * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
+ * ```
+ *
+ * `undefined` means no host said anything — a plain browser tab, a host predating the handshake, or a
+ * handshake that has not finished. **Treat absent as "assume nothing", never as "assume desktop".**
+ *
+ * ⚠ **Await `bridge.notifyReady()` before rendering the tree that depends on this.** The value is read
+ * SYNCHRONOUSLY from the bridge's cache, deliberately — a capability learned after layout is a visible
+ * flash — which means this hook does not re-render when a handshake lands later. A component mounted
+ * mid-handshake sees `undefined` and keeps seeing it, which is the documented "assume nothing" tree
+ * rather than a wrong one, but it is not the tree you wanted.
+ *
+ * ⚠ This hook was referenced by two doc examples in this package for several releases before it
+ * existed — `bridge.shell` was the only way to read it. If you wrote that workaround, this replaces it.
+ */
+export declare function useShellInfo(bridge?: ShenoraBridge): ShellInfo | undefined;
 /**
  * Subscribe to one (module, type) event for the component's lifetime, ported from the primary
  * desktop sibling. The handler receives the unwrapped payload (plus the full event). DEVIATION

package/dist/hooks.js

@@ -6,6 +6,30 @@ export function useShenora() {
     const bridge = getBridge();
     return { isAvailable: bridge.isAvailable, bridge };
 }
+/**
+ * What the host IS and what it can do — the way one bundle renders correctly on every shell.
+ * Branch on {@link ShellInfo.capabilities}, never on {@link ShellInfo.name}.
+ *
+ * ```tsx
+ * const shell = useShellInfo();
+ * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
+ * ```
+ *
+ * `undefined` means no host said anything — a plain browser tab, a host predating the handshake, or a
+ * handshake that has not finished. **Treat absent as "assume nothing", never as "assume desktop".**
+ *
+ * ⚠ **Await `bridge.notifyReady()` before rendering the tree that depends on this.** The value is read
+ * SYNCHRONOUSLY from the bridge's cache, deliberately — a capability learned after layout is a visible
+ * flash — which means this hook does not re-render when a handshake lands later. A component mounted
+ * mid-handshake sees `undefined` and keeps seeing it, which is the documented "assume nothing" tree
+ * rather than a wrong one, but it is not the tree you wanted.
+ *
+ * ⚠ This hook was referenced by two doc examples in this package for several releases before it
+ * existed — `bridge.shell` was the only way to read it. If you wrote that workaround, this replaces it.
+ */
+export function useShellInfo(bridge) {
+    return (bridge ?? getBridge()).shell;
+}
 /**
  * Subscribe to one (module, type) event for the component's lifetime, ported from the primary
  * desktop sibling. The handler receives the unwrapped payload (plus the full event). DEVIATION

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, type IpcRequest, type IpcResponse, type IpcError, type IpcNotification, type IpcNotificationBatch, type EventMessage, ShellCapabilities, type ShellInfo, } from './types.js';
 export { OperationError } from './errors.js';
 export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, type ShenoraTransport, } from './transport.js';
-export { ShenoraEventBus, eventBus } from './eventBus.js';
+export { ShenoraEventBus, eventBus, type SubscribeOptions, } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, type ShenoraBridgeOptions, type InvokeOptions, type PostOptions, type PostFailure, } from './bridge.js';
 export { createShenoraStore, type ShenoraStore, type ShenoraStoreOptions, type ShenoraStoreIo, type ShenoraStoreSnapshot, } from './store.js';
 export { BaseModuleService } from './moduleService.js';
 export { OperationStatuses, OperationEventTypes, OperationModuleName, createOperationsStore, useShenoraOperations, type OperationStatus, type OperationLabel, type OperationProgress, type OperationInfo, type OperationsState, type OperationsActions, type OperationsStoreOptions, } from './operations.js';
 export { WindowCommands, useWindowMaximized, type WindowResizeEdge, type CaptionButtonKind, type CaptionButtonRect, } from './windowCommands.js';
 export { useDropZone, DROP_ZONE_MODULE, type DropZoneFileDrop, type UseDropZoneOptions, } from './useDropZone.js';
-export { useShenora, useShenoraEvent, useShenoraQuery, type ShenoraQueryResult } from './hooks.js';
+export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, type ShenoraQueryResult, } from './hooks.js';
+export { FileDialogs, useFileDialogs, type FileDialogFilter, type FileDialogOptions, type OpenFileOptions, type OpenFolderOptions, type SaveFileOptions, type FileDialogResult, type FileDialogsHandle, } from './fileDialogs.js';
 export { installDevInterceptor, type DevInterceptorOptions, type DevIpcEntry, type DevEventEntry, } from './devInterceptor.js';
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';

package/dist/index.js

@@ -5,7 +5,7 @@
 export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, ShellCapabilities, } from './types.js';
 export { OperationError } from './errors.js';
 export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, } from './transport.js';
-export { ShenoraEventBus, eventBus } from './eventBus.js';
+export { ShenoraEventBus, eventBus, } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
 export { createShenoraStore, } from './store.js';
 export { BaseModuleService } from './moduleService.js';
@@ -17,7 +17,9 @@ export { OperationStatuses,
 OperationEventTypes, OperationModuleName, createOperationsStore, useShenoraOperations, } from './operations.js';
 export { WindowCommands, useWindowMaximized, } from './windowCommands.js';
 export { useDropZone, DROP_ZONE_MODULE, } from './useDropZone.js';
-export { useShenora, useShenoraEvent, useShenoraQuery } from './hooks.js';
+export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, } from './hooks.js';
+// Native dialogs, capability-gated. The client half of the host's FILE_DIALOGS module.
+export { FileDialogs, useFileDialogs, } from './fileDialogs.js';
 export { installDevInterceptor, } from './devInterceptor.js';
 // Addressing local content the page cannot reach itself. A pure function, not a hook — building the URL
 // needs no React, and a `useMediaSource` can follow if an adopter wants load/error state.

package/dist/types.d.ts

@@ -37,6 +37,19 @@ export declare const IpcErrorCodes: {
      * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
      */
     readonly operationCancelled: "OPERATION_CANCELLED";
+    /**
+     * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
+     * Parameters: `capability` (a {@link ShellCapabilities} value).
+     *
+     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
+     * because the capability is absent by design on that platform (a folder picker on a phone, for
+     * instance) rather than broken.
+     *
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
+     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
+     * intended path. This is the honest answer when a page asks anyway.
+     */
+    readonly capabilityNotSupported: "CAPABILITY_NOT_SUPPORTED";
     /** Client-only: the request timed out waiting for a response. */
     readonly timeout: "TIMEOUT";
     /** Client-only: no transport is available and no fallback was configured. */

package/dist/types.js

@@ -37,6 +37,19 @@ export const IpcErrorCodes = {
      * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
      */
     operationCancelled: 'OPERATION_CANCELLED',
+    /**
+     * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
+     * Parameters: `capability` (a {@link ShellCapabilities} value).
+     *
+     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
+     * because the capability is absent by design on that platform (a folder picker on a phone, for
+     * instance) rather than broken.
+     *
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
+     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
+     * intended path. This is the honest answer when a page asks anyway.
+     */
+    capabilityNotSupported: 'CAPABILITY_NOT_SUPPORTED',
     /** Client-only: the request timed out waiting for a response. */
     timeout: 'TIMEOUT',
     /** Client-only: no transport is available and no fallback was configured. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenora/react",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "React client for Shenora desktop hosts: correlated invoke/send/subscribe over the WebView2 bridge, typed module services, hooks, and a browser fallback for pure-UI development.",
   "license": "MIT",
   "author": "Jiarong Gu",