@shenora/react 0.4.0 → 0.5.1

package/dist/bridge.d.ts

@@ -1,12 +1,12 @@
 import { type ShenoraEventBus } from './eventBus.js';
 import { type ShenoraTransport } from './transport.js';
-import { type IpcError, type IpcRequest } from './types.js';
+import { type IpcError, type IpcRequest, type ShellInfo } from './types.js';
 /** Inputs for {@link ShenoraBridge}. */
 export interface ShenoraBridgeOptions {
     /**
-     * The channel to the host. Default: the WebView2 postMessage transport when running inside a
-     * host, else null (browser). Supply your own for other shells — a WebSocket, a mobile shell's
-     * native channel (D16) — or a scripted fake for tests/preview harnesses.
+     * The channel to the host. Default: whichever Shenora host this page is in — WebView2 postMessage
+     * on the desktop shell, `HybridWebView` on the MAUI shell — else null (plain browser). Supply your
+     * own for another shell (a WebSocket, D16) or a scripted fake for tests/preview harnesses.
      */
     transport?: ShenoraTransport | null;
     /** The event bus host notifications are unbundled into. Default: the shared bus. */
@@ -78,6 +78,7 @@ export declare class ShenoraBridge {
     private readonly onPostError;
     private readonly unsubscribe?;
     private disposed;
+    private shellInfo;
     constructor(options?: ShenoraBridgeOptions);
     /**
      * True when this bridge can actually send: a transport to a host exists AND the bridge has not been
@@ -135,7 +136,13 @@ export declare class ShenoraBridge {
      * `void bridge.notifyReady()` turns that into an unhandled rejection, which in a WebView2 page is
      * a silent console error.
      */
-    notifyReady<TPayload = unknown>(payload?: TPayload): Promise<void>;
+    notifyReady<TPayload = unknown>(payload?: TPayload): Promise<ShellInfo | undefined>;
+    /**
+     * What the host said it was during {@link notifyReady} — undefined before the handshake, or when
+     * the host advertised nothing. Cached so components can read it synchronously while rendering,
+     * which is the whole point: a capability learned after layout is a flash.
+     */
+    get shell(): ShellInfo | undefined;
     /** Reject everything in flight and detach from the transport. */
     dispose(): void;
     private onHostMessage;

package/dist/bridge.js

@@ -1,7 +1,7 @@
 import { OperationError } from './errors.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { randomId } from './internal.js';
-import { createWebView2Transport } from './transport.js';
+import { createHostTransport } from './transport.js';
 import { HANDSHAKE_MODULE, HANDSHAKE_TYPE, IpcCategories, IpcErrorCodes, } from './types.js';
 const newId = () => randomId();
 /** A promise-like: only these need racing against a timeout — a plain value has already settled. */
@@ -23,7 +23,7 @@ export class ShenoraBridge {
         // Insertion-ordered and capped: a Map is used for its ordered keys, not for the values.
         this.unawaited = new Map();
         this.disposed = false;
-        this.transport = options.transport !== undefined ? options.transport : createWebView2Transport();
+        this.transport = options.transport !== undefined ? options.transport : createHostTransport();
         this.eventBus = options.eventBus ?? defaultEventBus;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
         this.fallback = options.fallback;
@@ -200,8 +200,29 @@ export class ShenoraBridge {
      */
     async notifyReady(payload) {
         if (!this.transport)
-            return;
-        await this.invoke(HANDSHAKE_MODULE, HANDSHAKE_TYPE, { payload });
+            return undefined;
+        // The host answers with what it IS and what it can do, so a page can render one tree on every
+        // shell instead of sniffing the platform. A host that says nothing (no descriptor configured, or
+        // one predating this) leaves it UNDEFINED — absent means "assume nothing", never "assume
+        // desktop".
+        //
+        // undefined rather than null on purpose: JSON null means absent on this wire and the client
+        // convention is undefined (see .claude/knowledge/ipc-contracts.md). Returning null broke two
+        // existing tests that assert this resolves to undefined, which is the convention catching a
+        // deviation exactly where it should.
+        const shell = await this.invoke(HANDSHAKE_MODULE, HANDSHAKE_TYPE, { payload });
+        this.shellInfo = shell && typeof shell === 'object' && typeof shell.name === 'string'
+            ? { name: shell.name, capabilities: Array.isArray(shell.capabilities) ? shell.capabilities : [] }
+            : undefined;
+        return this.shellInfo;
+    }
+    /**
+     * What the host said it was during {@link notifyReady} — undefined before the handshake, or when
+     * the host advertised nothing. Cached so components can read it synchronously while rendering,
+     * which is the whole point: a capability learned after layout is a flash.
+     */
+    get shell() {
+        return this.shellInfo;
     }
     /** Reject everything in flight and detach from the transport. */
     dispose() {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, type IpcRequest, type IpcResponse, type IpcError, type IpcNotification, type IpcNotificationBatch, type EventMessage, } from './types.js';
+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, createWebView2Transport, type ShenoraTransport } from './transport.js';
+export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, type ShenoraTransport, } from './transport.js';
 export { ShenoraEventBus, eventBus } 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';

package/dist/index.js

@@ -2,9 +2,9 @@
 // pluggable transport, the event hub host notifications unbundle into, typed module services,
 // React hooks, and the dev interceptor for CDP-driven testing. Headless by design (D13): no UI
 // components, no design-system dependency — apps bring their own.
-export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, } from './types.js';
+export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, ShellCapabilities, } from './types.js';
 export { OperationError } from './errors.js';
-export { isShenoraAvailable, createWebView2Transport } from './transport.js';
+export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, } from './transport.js';
 export { ShenoraEventBus, eventBus } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
 export { createShenoraStore, } from './store.js';

package/dist/transport.d.ts

@@ -10,9 +10,35 @@ export interface ShenoraTransport {
     subscribe(listener: (message: string) => void): () => void;
 }
 /**
- * True when running inside a WebView2 desktop host (the bridge transport exists).
- * In a plain browser this is false — callers should fall back to browser-only behavior.
+ * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI
+ * `HybridWebView` — i.e. when a transport to the host exists. In a plain browser this is false and
+ * callers should fall back to browser-only behavior.
+ *
+ * It used to test WebView2 alone, which answered FALSE on the MAUI shell: an app would have
+ * concluded it was in a plain browser tab while a perfectly good host sat on the other side of the
+ * channel. Widened when the second shell arrived — the question this function is asked is "is there
+ * a host", never "is it WebView2".
  */
 export declare function isShenoraAvailable(): boolean;
 /** The WebView2 postMessage transport, or null outside a WebView2 host. */
 export declare function createWebView2Transport(): ShenoraTransport | null;
+/**
+ * The MAUI `HybridWebView` transport, or null outside a MAUI host.
+ *
+ * Asymmetric by the platform's design, which is the only thing interesting here: sending goes
+ * through `window.HybridWebView.SendRawMessage`, while receiving is a `HybridWebViewMessageReceived`
+ * CustomEvent dispatched on `window`. Both directions carry the same JSON envelopes the desktop
+ * shell speaks — the host side is `Shenora.Maui.MauiIpcBridge`, and the envelope itself never
+ * changed, which is the whole point of the transport seam (D16).
+ */
+export declare function createHybridWebViewTransport(): ShenoraTransport | null;
+/**
+ * The transport for whichever Shenora host this page is running in, or null in a plain browser.
+ * This is what the bridge uses by default, so an app that simply calls `invoke`/`post` works on the
+ * desktop shell and the MAUI shell without knowing which one it is.
+ *
+ * WebView2 is probed FIRST for no deeper reason than that it is the older shell and a page can only
+ * ever be in one of them; if both objects were somehow present, preferring the one the desktop host
+ * injects keeps existing behaviour byte-identical.
+ */
+export declare function createHostTransport(): ShenoraTransport | null;

package/dist/transport.js

@@ -1,10 +1,17 @@
 const webViewWindow = () => typeof window === 'undefined' ? undefined : window;
 /**
- * True when running inside a WebView2 desktop host (the bridge transport exists).
- * In a plain browser this is false — callers should fall back to browser-only behavior.
+ * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI
+ * `HybridWebView` — i.e. when a transport to the host exists. In a plain browser this is false and
+ * callers should fall back to browser-only behavior.
+ *
+ * It used to test WebView2 alone, which answered FALSE on the MAUI shell: an app would have
+ * concluded it was in a plain browser tab while a perfectly good host sat on the other side of the
+ * channel. Widened when the second shell arrived — the question this function is asked is "is there
+ * a host", never "is it WebView2".
  */
 export function isShenoraAvailable() {
-    return !!webViewWindow()?.chrome?.webview;
+    const host = webViewWindow();
+    return !!host?.chrome?.webview || !!host?.HybridWebView;
 }
 /** The WebView2 postMessage transport, or null outside a WebView2 host. */
 export function createWebView2Transport() {
@@ -24,3 +31,45 @@ export function createWebView2Transport() {
         },
     };
 }
+/**
+ * The MAUI `HybridWebView` transport, or null outside a MAUI host.
+ *
+ * Asymmetric by the platform's design, which is the only thing interesting here: sending goes
+ * through `window.HybridWebView.SendRawMessage`, while receiving is a `HybridWebViewMessageReceived`
+ * CustomEvent dispatched on `window`. Both directions carry the same JSON envelopes the desktop
+ * shell speaks — the host side is `Shenora.Maui.MauiIpcBridge`, and the envelope itself never
+ * changed, which is the whole point of the transport seam (D16).
+ */
+export function createHybridWebViewTransport() {
+    const host = webViewWindow();
+    const hybrid = host?.HybridWebView;
+    if (!hybrid)
+        return null;
+    return {
+        post: (message) => hybrid.SendRawMessage(message),
+        subscribe: (listener) => {
+            const handler = (event) => {
+                // Narrow before reading: any code on the page can dispatch an event with this name, and a
+                // non-string detail must be ignored rather than handed to JSON.parse. Same rule the inbound
+                // WebView2 path follows.
+                const message = event.detail?.message;
+                if (typeof message === 'string')
+                    listener(message);
+            };
+            window.addEventListener('HybridWebViewMessageReceived', handler);
+            return () => window.removeEventListener('HybridWebViewMessageReceived', handler);
+        },
+    };
+}
+/**
+ * The transport for whichever Shenora host this page is running in, or null in a plain browser.
+ * This is what the bridge uses by default, so an app that simply calls `invoke`/`post` works on the
+ * desktop shell and the MAUI shell without knowing which one it is.
+ *
+ * WebView2 is probed FIRST for no deeper reason than that it is the older shell and a page can only
+ * ever be in one of them; if both objects were somehow present, preferring the one the desktop host
+ * injects keeps existing behaviour byte-identical.
+ */
+export function createHostTransport() {
+    return createWebView2Transport() ?? createHybridWebViewTransport();
+}

package/dist/types.d.ts

@@ -70,6 +70,42 @@ export interface IpcError {
     /** Values interpolated into the translated message. */
     parameters?: Record<string, string>;
 }
+/**
+ * What the host is and what it can do — the handshake's response data (mirror of the host's
+ * `ShellInfo`).
+ *
+ * This is what lets ONE page ship to every shell. Render on the data rather than sniffing the
+ * platform:
+ *
+ * ```tsx
+ * const shell = useShellInfo();
+ * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
+ * ```
+ *
+ * A desktop shell that draws its own chrome advertises `windowChrome` and `dropZones`; a mobile one
+ * has neither, and the same bundle renders correctly on both. Undefined means no host said
+ * anything — a plain browser tab, or a host predating this — so treat absent as "assume nothing",
+ * never as "assume desktop".
+ */
+export interface ShellInfo {
+    /** Short host identifier, for diagnostics (`"winforms"`, `"maui"`). Never branch on this — branch on the capabilities. */
+    name: string;
+    /** The capabilities this host offers; see {@link ShellCapabilities}. */
+    capabilities: string[];
+}
+/**
+ * The well-known capability names, mirroring the host's `ShellCapability` constants. Apps may
+ * advertise their own strings too — this is the shared vocabulary, not the whole set.
+ */
+export declare const ShellCapabilities: {
+    readonly windowChrome: "windowChrome";
+    readonly dropZones: "dropZones";
+    readonly filePicker: "filePicker";
+    readonly folderPicker: "folderPicker";
+    readonly savePicker: "savePicker";
+    readonly secondaryWindows: "secondaryWindows";
+    readonly tray: "tray";
+};
 /** The response envelope the host returns for an {@link IpcRequest}. */
 export interface IpcResponse<TData = unknown> {
     category: typeof IpcCategories.ipc;

package/dist/types.js

@@ -51,3 +51,16 @@ export const ClientOnlyIpcErrorCodes = [
     IpcErrorCodes.timeout,
     IpcErrorCodes.noTransport,
 ];
+/**
+ * The well-known capability names, mirroring the host's `ShellCapability` constants. Apps may
+ * advertise their own strings too — this is the shared vocabulary, not the whole set.
+ */
+export const ShellCapabilities = {
+    windowChrome: 'windowChrome',
+    dropZones: 'dropZones',
+    filePicker: 'filePicker',
+    folderPicker: 'folderPicker',
+    savePicker: 'savePicker',
+    secondaryWindows: 'secondaryWindows',
+    tray: 'tray',
+};

package/dist/windowCommands.d.ts

@@ -33,7 +33,7 @@ interface WindowRequests {
     };
 }
 /**
- * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.WebView2) —
+ * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
  * `minimize`/`toggleMaximize`/`close`, the header's `onMouseDown` calls `startDrag` (the window
  * then drags natively — snap and multi-monitor included), and a thin strip at the very top

package/dist/windowCommands.js

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { debounce } from './internal.js';
 import { BaseModuleService } from './moduleService.js';
 /**
- * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.WebView2) —
+ * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
  * `minimize`/`toggleMaximize`/`close`, the header's `onMouseDown` calls `startDrag` (the window
  * then drags natively — snap and multi-monitor included), and a thin strip at the very top

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenora/react",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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",