@shenora/react 0.15.0 → 0.17.0

package/README.md

@@ -1,7 +1,7 @@
 # @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`
+React client for [Shenora](https://github.com/JiarongGu/Shenora) hosts: the Windows shell (WebView2 or
+Chromium), the Chromium shell, Android and iOS. 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
@@ -144,8 +144,9 @@ runs ahead of the feature code it is observing. Prefer `subscribe` when you know
 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.
+`import.meta.env.DEV`) to answer requests with canned data. The kit's own hosts are found by
+`createHostTransport()`; another host (a WebSocket, say) implements the small `ShenoraTransport` seam and
+speaks the same envelopes.
 For CDP-driven testing, `installDevInterceptor()` records IPC/event traffic into ring buffers
 and exposes `window.__shenora.call()/waitEvent()`.
 

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 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 { ShenoraError } from './errors.js';
-export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, type ShenoraTransport, } from './transport.js';
+export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, createChromiumTransport, type ShenoraTransport, } from './transport.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 { IpcRequestStates, IpcRequestEventTypes, IpcRequestRoutes, IpcRequestsModuleName, createRequestsStore, useShenoraRequests, type IpcRequestState, type IpcLabel, type IpcProgress, type IpcRequestStatus, type RequestsState, type RequestsActions, type RequestsStoreOptions, } from './requests.js';
-export { WindowCommands, useWindowMaximized, type WindowResizeEdge, type CaptionButtonKind, type CaptionButtonRect, } from './windowCommands.js';
+export { WindowCommands, WindowEventTypes, useCaptionButtonState, useWindowMaximized, type WindowResizeEdge, type CaptionButtonKind, type CaptionButtonRect, type CaptionButtonState, type CaptionButtonColors, } from './windowCommands.js';
+export { WindowOrientation, type WindowOrientationKind, } from './windowOrientation.js';
 export { useDropZone, DROP_ZONE_MODULE, type DropZoneFileDrop, type UseDropZoneOptions, } from './useDropZone.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';
@@ -20,3 +21,5 @@ export { bindSegmentStream, SegmentBinderError } from './segmentBinder.js';
 export type { SegmentBinderOptions, SegmentBinding } from './segmentBinder.js';
 export type { SegmentEntry, SegmentManifest, MediaSourceKind, MediaSourceGlobals, FetchState, FetchPolicy, } from './segmentStream.js';
 export { useMediaPlayer, MEDIA_PLAYER_MODULE, MEDIA_PLAYER_REPORT, MEDIA_PLAYER_STATUS, MediaPlayerCommands, MediaConversionEvents, MediaConversionErrorCodes, type MediaPlayerReport, type MediaPlayerReportState, type UseMediaPlayerOptions, } from './mediaPlayer.js';
+export { useMediaSurface, MediaSurfaceCommands, type UseMediaSurfaceOptions, } from './mediaSurface.js';
+export { useMediaTransport, type MediaTransport, type MediaTransportStatus, type UseMediaTransportOptions, } from './mediaTransport.js';

package/dist/index.js

@@ -4,7 +4,7 @@
 // components, no design-system dependency — apps bring their own.
 export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, ShellCapabilities, } from './types.js';
 export { ShenoraError } from './errors.js';
-export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, } from './transport.js';
+export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, createChromiumTransport, } from './transport.js';
 export { ShenoraEventBus, eventBus, } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
 export { createShenoraStore, } from './store.js';
@@ -13,7 +13,8 @@ export { IpcRequestStates,
 // The event and route vocabulary + the default module name, so an app handling or cancelling a
 // request without `useShenoraRequests` never types the wire literals by hand.
 IpcRequestEventTypes, IpcRequestRoutes, IpcRequestsModuleName, createRequestsStore, useShenoraRequests, } from './requests.js';
-export { WindowCommands, useWindowMaximized, } from './windowCommands.js';
+export { WindowCommands, WindowEventTypes, useCaptionButtonState, useWindowMaximized, } from './windowCommands.js';
+export { WindowOrientation, } from './windowOrientation.js';
 export { useDropZone, DROP_ZONE_MODULE, } from './useDropZone.js';
 export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, } from './hooks.js';
 // Native dialogs, capability-gated. The client half of the host's SHENORA.DIALOGS module.
@@ -34,3 +35,7 @@ export { parseManifest, pickMediaSource, nextSegment, segmentMimeType, codecsFro
 export { bindSegmentStream, SegmentBinderError } from './segmentBinder.js';
 // The HOST-owned player (D58): .NET holds the lifecycle, the page's element is the display and the sound.
 export { useMediaPlayer, MEDIA_PLAYER_MODULE, MEDIA_PLAYER_REPORT, MEDIA_PLAYER_STATUS, MediaPlayerCommands, MediaConversionEvents, MediaConversionErrorCodes, } from './mediaPlayer.js';
+// The SHELL-owned picture — the same player's second surface, for what the element cannot decode.
+export { useMediaSurface, MediaSurfaceCommands, } from './mediaSurface.js';
+// Driving and reading that same player, for when the shell owns the picture and the page owns the controls.
+export { useMediaTransport, } from './mediaTransport.js';

package/dist/internal.d.ts

@@ -1,6 +1,9 @@
 /**
  * Shared internals for `@shenora/react`. NOT exported from the barrel — nothing here is public
  * surface, and it must not become so by accident.
+ *
+ * ⚠ No React here: the bridge imports this module, and the bridge must load without React (a page importing
+ * `bridge.js` directly, a worker, a test). React-only internals live in `internalHooks.ts`.
  */
 /** A debounced void callback with a `cancel` for effect teardown. */
 export interface Debounced {

package/dist/internal.js

@@ -1,6 +1,9 @@
 /**
  * Shared internals for `@shenora/react`. NOT exported from the barrel — nothing here is public
  * surface, and it must not become so by accident.
+ *
+ * ⚠ No React here: the bridge imports this module, and the bridge must load without React (a page importing
+ * `bridge.js` directly, a worker, a test). React-only internals live in `internalHooks.ts`.
  */
 /**
  * Trailing-edge debounce: the callback runs `ms` after the LAST call. `cancel` must be called from a

package/dist/internalHooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * React-only internals for `@shenora/react`'s hooks, apart from `internal.ts`, which the React-free bridge
+ * imports. NOT exported from the barrel.
+ */
+import { type RefObject } from 'react';
+/**
+ * A ref's CONTENT, as state. A ref is a stable object, so an effect keyed on it runs once, and a target that
+ * is not there on that run (rendered conditionally, or attached after the first commit) is never seen: the
+ * hook is silently dead for the component's whole life. A ref mutation triggers no render, so this effect has
+ * NO dependency array; setting an unchanged value is a React no-op, so it cannot loop.
+ */
+export declare function useRefElement<T extends Element>(ref: RefObject<T | null>): T | null;

package/dist/internalHooks.js

@@ -0,0 +1,18 @@
+/**
+ * React-only internals for `@shenora/react`'s hooks, apart from `internal.ts`, which the React-free bridge
+ * imports. NOT exported from the barrel.
+ */
+import { useEffect, useState } from 'react';
+/**
+ * A ref's CONTENT, as state. A ref is a stable object, so an effect keyed on it runs once, and a target that
+ * is not there on that run (rendered conditionally, or attached after the first commit) is never seen: the
+ * hook is silently dead for the component's whole life. A ref mutation triggers no render, so this effect has
+ * NO dependency array; setting an unchanged value is a React no-op, so it cannot loop.
+ */
+export function useRefElement(ref) {
+    const [element, setElement] = useState(null);
+    useEffect(() => {
+        setElement(ref.current ?? null);
+    });
+    return element;
+}

package/dist/mediaSurface.d.ts

@@ -0,0 +1,62 @@
+import { type RefObject } from 'react';
+import { type ShenoraBridge } from './bridge.js';
+/**
+ * The routes that move the SHELL's picture. **A wire contract**: these strings are duplicated in C# as
+ * `MediaPlayerModule.SurfaceShowType` / `SurfaceHideType`, and the two halves agree by string or not at all.
+ */
+export declare const MediaSurfaceCommands: {
+    /** `{ x, y, width, height, onTop? }` in CSS pixels. */
+    readonly show: "SURFACE_SHOW";
+    /** No payload. */
+    readonly hide: "SURFACE_HIDE";
+};
+/** Inputs for {@link useMediaSurface}. */
+export interface UseMediaSurfaceOptions {
+    /**
+     * Draw the picture ABOVE the page instead of behind it. Default `false`, which is what lets you paint
+     * captions and controls over it.
+     */
+    onTop?: boolean;
+    /**
+     * Stop measuring and hide the picture. Use it to turn the surface off without unmounting — flipping this
+     * to `false` sends one `hide`.
+     */
+    enabled?: boolean;
+    /** Override the module. Must match the host's `MediaPlayerOptions.Access.Module`. */
+    module?: string;
+    /** Test seam. */
+    bridge?: ShenoraBridge;
+}
+/**
+ * Tell the shell where to draw the picture: this element's rectangle becomes a hole, and the host's own
+ * player fills it from underneath (D58's second surface).
+ *
+ * ```tsx
+ * const stage = useRef<HTMLDivElement>(null);
+ * useMediaSurface(stage);
+ * return <div ref={stage} style={{ background: 'transparent' }} />;
+ * ```
+ *
+ * **Use this instead of {@link useMediaPlayer} when the webview cannot decode the file** — the shell's
+ * player opens what a `<video>` element refuses. Everywhere else the element is the better answer, and
+ * both are the same `IMediaPlayer` underneath.
+ *
+ * 🔴 **The element must be genuinely TRANSPARENT, and so must everything behind it.** The picture is drawn
+ * BELOW the webview, so any opaque ancestor — most often a `body` background — hides it completely. That
+ * failure looks exactly like a player that never started, so check the backgrounds before the player.
+ * ⚠ **A transparent `body` is necessary and not sufficient for a full-bleed stage**: your own content is
+ * still painting over the picture. Hide it for the duration — `docs/guides/media.md` has the two rules.
+ *
+ * ⚠ **Gate it on the `mediaSurface` capability**, by rendering this component only on a shell that has one:
+ * a host without a surface answers every post with `MEDIA_SURFACE_UNAVAILABLE`. Read the capability from a
+ * source that RE-RENDERS when the handshake lands — a synchronous cache read taken during the first render
+ * is `false` for the whole session on a page that mounts before the host answers.
+ *
+ * ⚠ **The rectangle is in CSS pixels and crosses to the shell unconverted** — do not scale it by
+ * `devicePixelRatio`.
+ *
+ * ⚠ **It follows scroll and resize, coalesced to one post per animation frame**, and posts nothing when
+ * the rectangle has not moved. A collapsed or unmounted element measures zero, which the host reads as
+ * "hide" rather than drawing a dot at the origin.
+ */
+export declare function useMediaSurface(ref: RefObject<HTMLElement | null>, options?: UseMediaSurfaceOptions): void;

package/dist/mediaSurface.js

@@ -0,0 +1,133 @@
+import { useEffect, useRef } from 'react';
+import { getBridge } from './bridge.js';
+import { useRefElement } from './internalHooks.js';
+import { MEDIA_PLAYER_MODULE } from './mediaPlayer.js';
+/**
+ * The routes that move the SHELL's picture. **A wire contract**: these strings are duplicated in C# as
+ * `MediaPlayerModule.SurfaceShowType` / `SurfaceHideType`, and the two halves agree by string or not at all.
+ */
+export const MediaSurfaceCommands = {
+    /** `{ x, y, width, height, onTop? }` in CSS pixels. */
+    show: 'SURFACE_SHOW',
+    /** No payload. */
+    hide: 'SURFACE_HIDE',
+};
+/**
+ * Tell the shell where to draw the picture: this element's rectangle becomes a hole, and the host's own
+ * player fills it from underneath (D58's second surface).
+ *
+ * ```tsx
+ * const stage = useRef<HTMLDivElement>(null);
+ * useMediaSurface(stage);
+ * return <div ref={stage} style={{ background: 'transparent' }} />;
+ * ```
+ *
+ * **Use this instead of {@link useMediaPlayer} when the webview cannot decode the file** — the shell's
+ * player opens what a `<video>` element refuses. Everywhere else the element is the better answer, and
+ * both are the same `IMediaPlayer` underneath.
+ *
+ * 🔴 **The element must be genuinely TRANSPARENT, and so must everything behind it.** The picture is drawn
+ * BELOW the webview, so any opaque ancestor — most often a `body` background — hides it completely. That
+ * failure looks exactly like a player that never started, so check the backgrounds before the player.
+ * ⚠ **A transparent `body` is necessary and not sufficient for a full-bleed stage**: your own content is
+ * still painting over the picture. Hide it for the duration — `docs/guides/media.md` has the two rules.
+ *
+ * ⚠ **Gate it on the `mediaSurface` capability**, by rendering this component only on a shell that has one:
+ * a host without a surface answers every post with `MEDIA_SURFACE_UNAVAILABLE`. Read the capability from a
+ * source that RE-RENDERS when the handshake lands — a synchronous cache read taken during the first render
+ * is `false` for the whole session on a page that mounts before the host answers.
+ *
+ * ⚠ **The rectangle is in CSS pixels and crosses to the shell unconverted** — do not scale it by
+ * `devicePixelRatio`.
+ *
+ * ⚠ **It follows scroll and resize, coalesced to one post per animation frame**, and posts nothing when
+ * the rectangle has not moved. A collapsed or unmounted element measures zero, which the host reads as
+ * "hide" rather than drawing a dot at the origin.
+ */
+export function useMediaSurface(ref, options = {}) {
+    const { onTop = false, enabled = true, module = MEDIA_PLAYER_MODULE, bridge } = options;
+    // The ref's CONTENT: a stage rendered after the first commit (conditionally, say) would otherwise never bind.
+    const element = useRefElement(ref);
+    // Whether the shell is drawing for this hook now, so a stage that is not there yet posts no hide.
+    const shown = useRef(false);
+    useEffect(() => {
+        /* 🔴 NOTHING HERE MAY THROW AT THE PAGE, and the call sites are why.
+         *
+         * These run from a scroll handler, a ResizeObserver and an effect CLEANUP — three places where an
+         * exception is not a caught error but a broken render or a leaked observer. And the throw is reachable:
+         * a page rendering the same component in a browser has no host at all, which is exactly the fallback
+         * case the capability check is supposed to make safe.
+         */
+        const post = (type, payload) => {
+            try {
+                (bridge ?? getBridge()).post(module, type, payload ? { payload } : {});
+            }
+            catch { /* a picture is never worth taking the page down for */ }
+        };
+        const hide = () => {
+            if (!shown.current)
+                return;
+            shown.current = false;
+            post(MediaSurfaceCommands.hide);
+        };
+        if (!element || !enabled) {
+            // Not a no-op once shown: turning the surface off has to reach the shell, or the picture stays where it was.
+            hide();
+            return;
+        }
+        let frame = 0;
+        let pending = false;
+        let last = '';
+        const measure = () => {
+            pending = false;
+            const box = element.getBoundingClientRect();
+            // Rounded before the comparison, not after: sub-pixel jitter during a scroll otherwise makes every
+            // frame look like a move and posts one message per frame forever.
+            const payload = {
+                x: Math.round(box.left),
+                y: Math.round(box.top),
+                width: Math.round(box.width),
+                height: Math.round(box.height),
+                onTop,
+            };
+            // ⚠ `onTop` is part of the dedupe key, or a surface that changes ONLY its z-order is never told.
+            const key = JSON.stringify(payload);
+            if (key === last)
+                return;
+            last = key;
+            shown.current = true;
+            post(MediaSurfaceCommands.show, payload);
+        };
+        // Coalesced to a frame: scroll fires far more often than the compositor draws, and every post is a
+        // trip across the bridge.
+        //
+        // ⚠ The guard is a FLAG, not the frame id. Clearing `frame` inside the callback only works while the
+        // callback is asynchronous — and the id is assigned AFTER it returns — so a synchronous frame leaves
+        // the id set for good and the surface never moves again.
+        const schedule = () => {
+            if (pending)
+                return;
+            pending = true;
+            frame = requestAnimationFrame(measure);
+        };
+        measure();
+        // `capture: true` is what makes a NESTED scroller count — a scroll inside a div does not bubble, and
+        // without it the picture stays behind whenever the stage is inside its own scroll area.
+        window.addEventListener('scroll', schedule, { capture: true, passive: true });
+        window.addEventListener('resize', schedule, { passive: true });
+        // Size and layout changes that no scroll or resize event reports: a sibling collapsing, a font
+        // loading, the element itself being animated.
+        const observer = new ResizeObserver(schedule);
+        observer.observe(element);
+        return () => {
+            if (frame !== 0)
+                cancelAnimationFrame(frame);
+            window.removeEventListener('scroll', schedule, { capture: true });
+            window.removeEventListener('resize', schedule);
+            observer.disconnect();
+            // 🔴 The picture is the SHELL's and outlives this component. Without this, unmounting the stage
+            // leaves a native rectangle painted over whatever the page navigates to next.
+            hide();
+        };
+    }, [element, onTop, enabled, module, bridge]);
+}

package/dist/mediaTransport.d.ts

@@ -0,0 +1,92 @@
+import { type ShenoraBridge } from './bridge.js';
+import { type MediaPlayerReportState } from './mediaPlayer.js';
+/**
+ * What the HOST's player is doing. The same vocabulary `MediaPlayerStatus` uses on the other side, with
+ * seconds where C# has `TimeSpan`.
+ */
+export interface MediaTransportStatus {
+    state: MediaPlayerReportState;
+    /** Seconds. */
+    position: number;
+    /** Seconds, or null for a live stream and — briefly — while opening. */
+    duration: number | null;
+    /** The rate ASKED FOR; a platform may clamp it. */
+    rate: number;
+    /** A short reason when `state` is `Failed`; never the platform's raw text. */
+    error?: string | null;
+    /**
+     * Which player produced this reading — `AndroidMediaPlayer`, `IosMediaPlayer`, or an app's own.
+     *
+     * 🔴 **Log it before forming a theory about playback.** With a pluggable player behind the shell's
+     * surface, "which decoder ran" is not answerable from anywhere else, and assuming it wrong is the
+     * cheapest way to debug the wrong code.
+     *
+     * ⚠ **A diagnostic, not a branch** — it names an implementation, so anything conditional on it is
+     * coupled to a class name. Branch on the shell's capabilities instead.
+     */
+    engine?: string | null;
+}
+/** Inputs for {@link useMediaTransport}. */
+export interface UseMediaTransportOptions {
+    /** How often to sample the position, in ms. Default 250 — the rate a scrubber redraws at. */
+    intervalMs?: number;
+    /**
+     * Poll at all. Default `true`. Set it `false` while no player surface is on screen: a paused player's
+     * position does not move, and the host answers every ask.
+     */
+    enabled?: boolean;
+    /** Override the module. Must match the host's `MediaPlayerOptions.Access.Module`. */
+    module?: string;
+    /** Test seam. */
+    bridge?: ShenoraBridge;
+}
+/** What {@link useMediaTransport} gives you. */
+export interface MediaTransport {
+    /** The most recent trustworthy reading, or `null` before the first one lands. */
+    status: MediaTransportStatus | null;
+    /**
+     * The host has stopped answering: eight asks in a row failed. About 2 s at the default interval when the
+     * host refuses them, about 10 s when it has gone quiet (each ask waits up to a second).
+     *
+     * 🔴 **This exists because a dead poll has NO symptom of its own.** The callback simply stops running:
+     * the scrubber keeps its last value, the play button keeps whatever the last press set, and nothing
+     * anywhere says the transport is gone. Show it, or at least log it — the alternative is diagnosing it
+     * from an ABSENCE, which is the hardest evidence there is to notice.
+     */
+    unanswered: boolean;
+    /** Point the host's player at a source and prepare it. Does not start playback. */
+    load(uri: string): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    /** Move to an absolute position, in seconds. */
+    seek(position: number): Promise<void>;
+    /** Set the speed multiplier; 1 is normal. */
+    setRate(rate: number): Promise<void>;
+    /** Release the source and free the decoder. */
+    unload(): Promise<void>;
+}
+/**
+ * Drive the HOST's player and read what it is doing — the companion to {@link useMediaSurface}, for when
+ * the shell owns the picture and the page owns the controls.
+ *
+ * ```tsx
+ * const { status, unanswered, play, pause, seek } = useMediaTransport();
+ * ```
+ *
+ * **Use it when the shell is the player.** With the picture on the shell's surface the page's own element
+ * is not playing, so its `timeupdate` says nothing and the host is the only clock. Running both is two
+ * clocks that disagree.
+ *
+ * 🔴 **THE COMMANDS ARE HERE, AND NOT BY CONVENIENCE.** A status answer that was asked for BEFORE a
+ * command is stale in every field, not just in `state` — so this hook drops it, which it can only do if
+ * it knows when a command happened. Calling the routes directly instead re-opens exactly that hole:
+ * the poll returns the pre-command reading, the UI flips back to it, and the next poll flips it again.
+ *
+ * ⚠ **A command's own answer is applied at once.** The host's drive routes return the resulting status,
+ * so a press updates the UI without waiting up to `intervalMs` for the next sample.
+ *
+ * ⚠ **Failures are swallowed, deliberately.** A poll that cannot answer is not worth breaking playback
+ * over, and a refused command resolves quietly: it is the host's answer, not a reason to throw at the page.
+ * Watch {@link MediaTransport.unanswered} for the case that matters.
+ */
+export declare function useMediaTransport(options?: UseMediaTransportOptions): MediaTransport;

package/dist/mediaTransport.js

@@ -0,0 +1,135 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getBridge } from './bridge.js';
+import { MEDIA_PLAYER_MODULE, MEDIA_PLAYER_STATUS, MediaPlayerCommands, } from './mediaPlayer.js';
+/**
+ * Consecutive failed asks before {@link MediaTransport.unanswered} goes true.
+ *
+ * ⚠ Counted in TICKS rather than elapsed ms so the threshold means the same thing however fast a caller
+ * samples: ONE dropped reply is ordinary, eight in a row is a transport that has gone.
+ */
+const UNANSWERED_AFTER_TICKS = 8;
+/**
+ * How long one status ask waits: four intervals, and never under a second. Without its own bound an ask
+ * waits the bridge's default of 30 s, and eight of them made a host that went quiet take four minutes to
+ * notice.
+ */
+const askTimeoutMs = (intervalMs) => Math.max(1000, intervalMs * 4);
+/**
+ * Drive the HOST's player and read what it is doing — the companion to {@link useMediaSurface}, for when
+ * the shell owns the picture and the page owns the controls.
+ *
+ * ```tsx
+ * const { status, unanswered, play, pause, seek } = useMediaTransport();
+ * ```
+ *
+ * **Use it when the shell is the player.** With the picture on the shell's surface the page's own element
+ * is not playing, so its `timeupdate` says nothing and the host is the only clock. Running both is two
+ * clocks that disagree.
+ *
+ * 🔴 **THE COMMANDS ARE HERE, AND NOT BY CONVENIENCE.** A status answer that was asked for BEFORE a
+ * command is stale in every field, not just in `state` — so this hook drops it, which it can only do if
+ * it knows when a command happened. Calling the routes directly instead re-opens exactly that hole:
+ * the poll returns the pre-command reading, the UI flips back to it, and the next poll flips it again.
+ *
+ * ⚠ **A command's own answer is applied at once.** The host's drive routes return the resulting status,
+ * so a press updates the UI without waiting up to `intervalMs` for the next sample.
+ *
+ * ⚠ **Failures are swallowed, deliberately.** A poll that cannot answer is not worth breaking playback
+ * over, and a refused command resolves quietly: it is the host's answer, not a reason to throw at the page.
+ * Watch {@link MediaTransport.unanswered} for the case that matters.
+ */
+export function useMediaTransport(options = {}) {
+    const { intervalMs = 250, enabled = true, module = MEDIA_PLAYER_MODULE, bridge } = options;
+    const [status, setStatus] = useState(null);
+    const [unanswered, setUnanswered] = useState(false);
+    /**
+     * How many commands have been issued. A reading asked for while this was lower describes a player that
+     * has since been told to do something else.
+     *
+     * ⚠ A ref, not state: bumping it must not re-render, and every reader needs the value as of NOW rather
+     * than as of the render it closed over.
+     */
+    const commands = useRef(0);
+    const live = useRef(true);
+    useEffect(() => {
+        live.current = true;
+        return () => { live.current = false; };
+    }, []);
+    const send = useCallback(async (type, payload) => {
+        commands.current += 1;
+        try {
+            const answer = await (bridge ?? getBridge())
+                .invoke(module, type, payload ? { payload } : {});
+            // The host answers a drive command with the status it produced — apply it rather than waiting for
+            // the next sample. ⚠ Only if this component is still mounted; a resolve after unmount is ordinary.
+            if (live.current && answer)
+                setStatus(normalise(answer));
+        }
+        catch {
+            /* A refused command is the host's answer, not a reason to throw at the page. */
+        }
+    }, [module, bridge]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let stopped = false;
+        let timer;
+        let misses = 0;
+        const tick = async () => {
+            if (stopped)
+                return;
+            // Read BEFORE the ask goes out: everything after this point is a command the answer cannot have seen.
+            const asked = commands.current;
+            let answer = null;
+            try {
+                answer = await (bridge ?? getBridge())
+                    .invoke(module, MEDIA_PLAYER_STATUS, { timeoutMs: askTimeoutMs(intervalMs) });
+            }
+            catch {
+                answer = null;
+            }
+            if (stopped)
+                return;
+            if (answer) {
+                misses = 0;
+                setUnanswered(false);
+                // 🔴 DROPPED, not reported-with-a-caveat: a pre-command reading is stale in position as well as
+                // state, so there is nothing in it a caller could safely keep.
+                if (commands.current === asked)
+                    setStatus(normalise(answer));
+            }
+            else if (++misses >= UNANSWERED_AFTER_TICKS) {
+                setUnanswered(true);
+            }
+            // ⚠ Scheduled from the ANSWER, never on a bare interval: a slow host stretches the gap instead of
+            // queueing asks behind each other.
+            timer = setTimeout(() => { void tick(); }, intervalMs);
+        };
+        void tick();
+        return () => { stopped = true; if (timer)
+            clearTimeout(timer); };
+    }, [enabled, intervalMs, module, bridge]);
+    const load = useCallback((uri) => send(MediaPlayerCommands.load, { uri }), [send]);
+    const play = useCallback(() => send(MediaPlayerCommands.play), [send]);
+    const pause = useCallback(() => send(MediaPlayerCommands.pause), [send]);
+    const seek = useCallback((position) => send(MediaPlayerCommands.seek, { position }), [send]);
+    const setRate = useCallback((rate) => send(MediaPlayerCommands.rate, { rate }), [send]);
+    const unload = useCallback(() => send(MediaPlayerCommands.unload), [send]);
+    return { status, unanswered, load, play, pause, seek, setRate, unload };
+}
+/**
+ * A host answer, with every field given a safe shape.
+ *
+ * ⚠ `duration` is null for a live stream and while opening, and a UI that reads a missing one as 0 puts
+ * the playhead at the end of something that has just started.
+ */
+function normalise(answer) {
+    return {
+        state: (answer.state ?? 'Empty'),
+        position: Number.isFinite(answer.position) ? Number(answer.position) : 0,
+        duration: Number.isFinite(answer.duration) ? Number(answer.duration) : null,
+        rate: Number.isFinite(answer.rate) ? Number(answer.rate) : 1,
+        error: answer.error ?? null,
+        engine: answer.engine ?? null,
+    };
+}

package/dist/transport.d.ts

@@ -1,3 +1,18 @@
+/**
+ * The Chromium shell's marker. The shell writes it into every HTML document it serves, so its presence
+ * IS the host advertising itself (D36, D83), never a guess about the engine. The page posts to `ipc`, a
+ * same-origin route the shell answers; the shell pushes by calling `receive`, which the transport sets.
+ */
+export interface ChromiumHost {
+    ipc: string;
+    receive?: ChromiumReceive;
+}
+/** A named type, not inline: WireMirrorTests reads the interface's fields and would count a parameter. */
+type ChromiumReceive = (message: unknown) => void;
+/** The global the Chromium shell marks a document with. Mirrored by `ChromiumTransport.HostGlobal`. */
+export declare const CHROMIUM_HOST_GLOBAL = "__shenora_chromium";
+/** What the Chromium shell calls to push a message. Mirrored by `ChromiumTransport.ReceiveMember`. */
+export declare const CHROMIUM_RECEIVE = "receive";
 /**
  * A message channel the bridge speaks over — the transport-pluggable seam (design D16): WebView2
  * postMessage on desktop today; a WebSocket or a mobile shell's native channel speaks the same
@@ -10,8 +25,8 @@ export interface ShenoraTransport {
     subscribe(listener: (message: string) => void): () => void;
 }
 /**
- * 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
+ * True when running inside ANY Shenora host — a WebView2 desktop shell, the Chromium shell or a
+ * `ChromiumView`, 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. The question is "is there a host", never "is it WebView2".
  */
 export declare function isShenoraAvailable(): boolean;
@@ -26,10 +41,17 @@ export declare function createWebView2Transport(): ShenoraTransport | null;
  * `Shenora.Maui.MauiIpcBridge`.
  */
 export declare function createHybridWebViewTransport(): ShenoraTransport | null;
+/**
+ * The Chromium shell's transport, or null outside it. There is no code in the renderer: the page posts
+ * each envelope with `fetch` to the marker's same-origin `ipc` route, which the shell answers from its
+ * resource handler, and the shell pushes by calling the marker's `receive`.
+ */
+export declare function createChromiumTransport(): 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. A page is only ever in one of
- * them; WebView2 wins if both objects are somehow present.
+ * desktop shell, the MAUI shell and the Chromium shell without knowing which one it is. A page is only
+ * ever in one of them; the order decides only if several objects are somehow present.
  */
 export declare function createHostTransport(): ShenoraTransport | null;
+export {};