@shenora/react 0.16.0 → 0.17.1

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,12 @@
 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';
@@ -21,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,7 @@ 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';
@@ -35,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 {};

package/dist/transport.js

@@ -1,12 +1,16 @@
+/** The global the Chromium shell marks a document with. Mirrored by `ChromiumTransport.HostGlobal`. */
+export const CHROMIUM_HOST_GLOBAL = '__shenora_chromium';
+/** What the Chromium shell calls to push a message. Mirrored by `ChromiumTransport.ReceiveMember`. */
+export const CHROMIUM_RECEIVE = 'receive';
 const webViewWindow = () => typeof window === 'undefined' ? undefined : window;
 /**
- * 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 function isShenoraAvailable() {
     const host = webViewWindow();
-    return !!host?.chrome?.webview || !!host?.HybridWebView;
+    return !!host?.chrome?.webview || !!host?.HybridWebView || !!chromiumHost(host);
 }
 /** The WebView2 postMessage transport, or null outside a WebView2 host. */
 export function createWebView2Transport() {
@@ -55,12 +59,59 @@ export function createHybridWebViewTransport() {
         },
     };
 }
+/** The marker, when it is well-formed; anything else on that global is not ours. */
+function chromiumHost(host) {
+    const marker = host?.[CHROMIUM_HOST_GLOBAL];
+    return marker && typeof marker === 'object' && typeof marker.ipc === 'string' ? marker : undefined;
+}
+/**
+ * Everyone listening on one marker. The host calls ONE function, so it fans out here: a second
+ * transport (a bridge replaced by `configureBridge`, say) must not silence the first, which is how two
+ * WebView2 listeners behave too.
+ */
+const chromiumListeners = new WeakMap();
+/**
+ * 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 function createChromiumTransport() {
+    const marker = chromiumHost(webViewWindow());
+    if (!marker)
+        return null;
+    let listeners = chromiumListeners.get(marker);
+    if (!listeners) {
+        const set = new Set();
+        chromiumListeners.set(marker, set);
+        marker[CHROMIUM_RECEIVE] = (message) => {
+            // Narrow first: anything on the page can call this, and only strings are ours.
+            if (typeof message === 'string')
+                for (const listener of [...set])
+                    listener(message);
+        };
+        listeners = set;
+    }
+    const own = listeners;
+    return {
+        // Each message is a request of its own. They reach the host in the order they were posted: measured,
+        // 1,500 of 1,500 one-way posts in order, though no spec promises it. A failed post is swallowed, since an
+        // unhandled rejection here would name nothing: an `invoke` then fails at the bridge's request timeout,
+        // which names the call, and a one-way `post` is lost.
+        post: (message) => {
+            void fetch(marker.ipc, { method: 'POST', body: message }).catch(() => undefined);
+        },
+        subscribe: (listener) => {
+            own.add(listener);
+            return () => { own.delete(listener); };
+        },
+    };
+}
 /**
  * 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 function createHostTransport() {
-    return createWebView2Transport() ?? createHybridWebViewTransport();
+    return createWebView2Transport() ?? createHybridWebViewTransport() ?? createChromiumTransport();
 }

package/dist/types.d.ts

@@ -140,6 +140,22 @@ export declare const ShellCapabilities: {
      * fullscreen first or leave rotation alone.
      */
     readonly windowOrientation: "windowOrientation";
+    /**
+     * The shell can draw the PICTURE itself, under a transparent region the page leaves — see
+     * `useMediaSurface`. The mobile shells; the desktop has none and does not need one.
+     *
+     * ⚠ Branch on it, but the fallback is a real player rather than a degraded one: absent, a `<video>`
+     * element is the picture, which is the right answer wherever the webview can decode the file. Present,
+     * the shell's own player opens what that element refuses.
+     *
+     * 🔴 It asserts TWO things: a surface exists AND a player is attached to draw into it. A host that
+     * advertises it on the strength of the surface alone gives you a hole with no decoder behind it — the
+     * controls render, nothing ever appears, and it is indistinguishable from a refused file.
+     *
+     * ⚠ It still says nothing about a GIVEN file — what the platform decodes is a per-stream question the
+     * host answers.
+     */
+    readonly mediaSurface: "mediaSurface";
 };
 /** The response envelope the host returns for an {@link IpcRequest}. */
 export interface IpcResponse<TData = unknown> {

package/dist/types.js

@@ -110,4 +110,20 @@ export const ShellCapabilities = {
      * fullscreen first or leave rotation alone.
      */
     windowOrientation: 'windowOrientation',
+    /**
+     * The shell can draw the PICTURE itself, under a transparent region the page leaves — see
+     * `useMediaSurface`. The mobile shells; the desktop has none and does not need one.
+     *
+     * ⚠ Branch on it, but the fallback is a real player rather than a degraded one: absent, a `<video>`
+     * element is the picture, which is the right answer wherever the webview can decode the file. Present,
+     * the shell's own player opens what that element refuses.
+     *
+     * 🔴 It asserts TWO things: a surface exists AND a player is attached to draw into it. A host that
+     * advertises it on the strength of the surface alone gives you a hole with no decoder behind it — the
+     * controls render, nothing ever appears, and it is indistinguishable from a refused file.
+     *
+     * ⚠ It still says nothing about a GIVEN file — what the platform decodes is a per-stream question the
+     * host answers.
+     */
+    mediaSurface: 'mediaSurface',
 };

package/dist/useDropZone.d.ts

@@ -56,13 +56,16 @@ export interface UseDropZoneOptions {
  * across the IPC boundary before the app knows whether it wants any of them. This gives you `string[]`
  * OS paths instead — open lazily, stream, hash incrementally, move or link without copying.
  *
- * The host positions a transparent native overlay over the element to capture those paths, including
- * for drags started while the app is in the background. Bounds re-sync (debounced) on
- * resize/scroll/intersection changes; the host converts the CSS rect to physical pixels per-monitor.
+ * **On the WebView2 shell** the host positions a transparent native overlay over the element to capture
+ * those paths, including for drags started while the app is in the background. Bounds re-sync
+ * (debounced) on resize/scroll/intersection changes; the host converts the CSS rect to physical pixels
+ * per-monitor. How the visibility dance works: mouse leaves the element → SHOW (overlay up, ready to
+ * catch a drag); mouse enters → the host hides the overlay (hover effects keep working); an inactive
+ * window always shows overlays (background drag-drop); while the overlay is visible the host emits
+ * DRAG_ENTER/DRAG_LEAVE for CSS feedback.
  *
- * How the visibility dance works: mouse leaves the element → SHOW (overlay up, ready to catch a
- * drag); mouse enters → the host hides the overlay (hover effects keep working); an inactive
- * window always shows overlays (background drag-drop); while the overlay is visible the host
- * emits DRAG_ENTER/DRAG_LEAVE for CSS feedback.
+ * **On the Chromium shell there is no overlay.** The engine hands the host the drag's real paths as it
+ * enters, so the host answers REGISTER with `pageDrop`, this hook takes the page's own drag events on the
+ * element, and a drop there asks the host for the paths. Your code is the same on both.
  */
 export declare function useDropZone(options: UseDropZoneOptions): void;

package/dist/useDropZone.js

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { debounce, randomId } from './internal.js';
+import { useRefElement } from './internalHooks.js';
 /** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneModule`). */
 export const DROP_ZONE_MODULE = 'SHENORA.DROPZONE';
 const newZoneId = () => randomId('drop-zone-');
@@ -12,14 +13,17 @@ const newZoneId = () => randomId('drop-zone-');
  * across the IPC boundary before the app knows whether it wants any of them. This gives you `string[]`
  * OS paths instead — open lazily, stream, hash incrementally, move or link without copying.
  *
- * The host positions a transparent native overlay over the element to capture those paths, including
- * for drags started while the app is in the background. Bounds re-sync (debounced) on
- * resize/scroll/intersection changes; the host converts the CSS rect to physical pixels per-monitor.
+ * **On the WebView2 shell** the host positions a transparent native overlay over the element to capture
+ * those paths, including for drags started while the app is in the background. Bounds re-sync
+ * (debounced) on resize/scroll/intersection changes; the host converts the CSS rect to physical pixels
+ * per-monitor. How the visibility dance works: mouse leaves the element → SHOW (overlay up, ready to
+ * catch a drag); mouse enters → the host hides the overlay (hover effects keep working); an inactive
+ * window always shows overlays (background drag-drop); while the overlay is visible the host emits
+ * DRAG_ENTER/DRAG_LEAVE for CSS feedback.
  *
- * How the visibility dance works: mouse leaves the element → SHOW (overlay up, ready to catch a
- * drag); mouse enters → the host hides the overlay (hover effects keep working); an inactive
- * window always shows overlays (background drag-drop); while the overlay is visible the host
- * emits DRAG_ENTER/DRAG_LEAVE for CSS feedback.
+ * **On the Chromium shell there is no overlay.** The engine hands the host the drag's real paths as it
+ * enters, so the host answers REGISTER with `pageDrop`, this hook takes the page's own drag events on the
+ * element, and a drop there asks the host for the paths. Your code is the same on both.
  */
 export function useDropZone(options) {
     const { targetRef, enabled = true } = options;
@@ -44,16 +48,8 @@ export function useDropZone(options) {
     reportRef.current = (error, route) => onErrorRef.current
         ? onErrorRef.current(error, route)
         : console.error(`[shenora] drop-zone ${route} failed:`, error);
-    // 🔴 Make the ref's CONTENT reactive. `targetRef` is a stable object, so an effect keyed on it runs
-    // exactly once — and if `targetRef.current` is null on that run (a conditionally-rendered target, or
-    // any order where the ref is attached after the first commit) the effect bails out and NEVER re-runs:
-    // the zone is silently dead for the component's whole life, with no error anywhere. A ref mutation
-    // triggers no render, so this effect has NO dependency array; `setElement` with an unchanged value is
-    // a React no-op, so it cannot loop.
-    const [element, setElement] = useState(null);
-    useEffect(() => {
-        setElement(targetRef.current ?? null);
-    });
+    // 🔴 The ref's CONTENT, reactive: a target rendered after the first commit would otherwise never register.
+    const element = useRefElement(targetRef);
     const isRegisteredRef = useRef(false);
     // Whether a REGISTER has ever been SENT for this zone (even if not yet acked). The cleanup
     // unregisters on THIS (not on the ack) so a fast unmount before REGISTER resolves still tears
@@ -66,6 +62,9 @@ export function useDropZone(options) {
     // never exists again. Cleanup bumps the epoch; acks from an older epoch are ignored.
     const epochRef = useRef(0);
     const lastBoundsRef = useRef({ x: 0, y: 0, width: 0, height: 0 });
+    // The host said the PAGE delivers drops (the Chromium shell). Read by the DOM listeners at event time,
+    // so they do nothing until REGISTER is answered, and nothing at all on the WebView2 shell.
+    const pageDropRef = useRef(false);
     const syncBoundsRef = useRef(() => { });
     syncBoundsRef.current = () => {
         const element = targetRef.current;
@@ -93,9 +92,11 @@ export function useDropZone(options) {
             const epoch = epochRef.current;
             bridge
                 .invoke(DROP_ZONE_MODULE, 'REGISTER', { payload: { zoneId: zoneIdRef.current, ...bounds } })
-                .then(() => {
-                if (epochRef.current === epoch)
-                    isRegisteredRef.current = true;
+                .then((registration) => {
+                if (epochRef.current !== epoch)
+                    return;
+                isRegisteredRef.current = true;
+                pageDropRef.current = registration?.pageDrop === true;
             }, (error) => reportRef.current(error, 'REGISTER'))
                 .finally(() => {
                 if (epochRef.current === epoch)
@@ -118,6 +119,8 @@ export function useDropZone(options) {
         const syncBounds = debounce(() => syncBoundsRef.current(), 100);
         syncBoundsRef.current();
         const sendShow = debounce(() => {
+            if (pageDropRef.current)
+                return; // no overlay to raise
             (bridgeRef.current ?? getBridge())
                 .invoke(DROP_ZONE_MODULE, 'SHOW', { payload: { zoneId: zoneIdRef.current } })
                 .catch((error) => reportRef.current(error, 'SHOW'));
@@ -161,20 +164,85 @@ export function useDropZone(options) {
                 isRegisteredRef.current = false;
                 registeringRef.current = false; // a remount must re-send immediately
                 attemptedRef.current = false;
+                pageDropRef.current = false;
             }
         };
     }, [enabled, element]);
-    // Drag-hover CSS feedback.
+    // The Chromium shell's drops: the page's own drag events on the element, acted on only once the host
+    // answered REGISTER with `pageDrop`. Claiming `dragover` is what makes the element a drop target at all.
+    useEffect(() => {
+        if (!enabled || !element)
+            return;
+        const dropClass = dropClassRef.current;
+        const carriesFiles = (event) => [...(event.dataTransfer?.types ?? [])].includes('Files');
+        // dragenter/dragleave fire for every child the pointer crosses, so count them rather than trusting one.
+        let depth = 0;
+        const onDragEnter = (event) => {
+            if (!pageDropRef.current || !carriesFiles(event))
+                return;
+            event.preventDefault();
+            depth++;
+            element.classList.add(dropClass);
+        };
+        const onDragOver = (event) => {
+            if (!pageDropRef.current || !carriesFiles(event))
+                return;
+            event.preventDefault();
+            if (event.dataTransfer)
+                event.dataTransfer.dropEffect = 'copy';
+        };
+        const onDragLeave = () => {
+            if (!pageDropRef.current)
+                return;
+            depth = Math.max(0, depth - 1);
+            if (depth === 0)
+                element.classList.remove(dropClass);
+        };
+        const onDrop = (event) => {
+            if (!pageDropRef.current || !carriesFiles(event))
+                return;
+            event.preventDefault();
+            depth = 0;
+            element.classList.remove(dropClass);
+            const rect = element.getBoundingClientRect();
+            const position = {
+                x: Math.round((event.clientX - rect.left) * devicePixelRatio),
+                y: Math.round((event.clientY - rect.top) * devicePixelRatio),
+            };
+            const zoneId = zoneIdRef.current;
+            (bridgeRef.current ?? getBridge())
+                .invoke(DROP_ZONE_MODULE, 'DROP', { payload: { zoneId } })
+                .then((answer) => {
+                const files = answer?.files ?? [];
+                if (files.length > 0)
+                    onDropRef.current(files, { zoneId, files, position });
+            }, (error) => reportRef.current(error, 'DROP'));
+        };
+        element.addEventListener('dragenter', onDragEnter);
+        element.addEventListener('dragover', onDragOver);
+        element.addEventListener('dragleave', onDragLeave);
+        element.addEventListener('drop', onDrop);
+        return () => {
+            element.removeEventListener('dragenter', onDragEnter);
+            element.removeEventListener('dragover', onDragOver);
+            element.removeEventListener('dragleave', onDragLeave);
+            element.removeEventListener('drop', onDrop);
+            element.classList.remove(dropClass);
+        };
+    }, [enabled, element]);
+    // Drag-hover CSS feedback, from the WebView2 shell's overlay. Where the page delivers drops itself, these bus events
+    // are some OTHER page's: an app with both engines has a WebView2 page announcing its drags to every page, and a zone
+    // of the same id there would otherwise light this one, or drop its files here.
     useEffect(() => {
         if (!enabled || !element)
             return;
         const dropClass = dropClassRef.current;
         const offEnter = bus.subscribe(DROP_ZONE_MODULE, 'DRAG_ENTER', (event) => {
-            if (event.payload?.zoneId === zoneIdRef.current)
+            if (!pageDropRef.current && event.payload?.zoneId === zoneIdRef.current)
                 element.classList.add(dropClass);
         });
         const offLeave = bus.subscribe(DROP_ZONE_MODULE, 'DRAG_LEAVE', (event) => {
-            if (event.payload?.zoneId === zoneIdRef.current)
+            if (!pageDropRef.current && event.payload?.zoneId === zoneIdRef.current)
                 element.classList.remove(dropClass);
         });
         return () => {
@@ -189,8 +257,8 @@ export function useDropZone(options) {
             return;
         return bus.subscribe(DROP_ZONE_MODULE, 'FILE_DROP', (event) => {
             const drop = event.payload;
-            if (!drop || drop.zoneId !== zoneIdRef.current)
-                return;
+            if (pageDropRef.current || !drop || drop.zoneId !== zoneIdRef.current)
+                return; // see the hover feedback above
             targetRef.current?.classList.remove(dropClassRef.current);
             onDropRef.current(drop.files, drop);
         });

package/dist/windowCommands.d.ts

@@ -1,4 +1,5 @@
 import type { ShenoraBridge } from './bridge.js';
+import type { ShenoraEventBus } from './eventBus.js';
 import { BaseModuleService } from './moduleService.js';
 /** The top resize edges — the only ones that exist: the frameless technique keeps the native
  * side/bottom resize borders, so only the top (covered by the WebView) needs page-side help. */
@@ -6,8 +7,8 @@ export type WindowResizeEdge = 'top' | 'topLeft' | 'topRight';
 /** Which system caption button a page-drawn region stands in for (mirrors the host's enum). */
 export type CaptionButtonKind = 'minimize' | 'maximize' | 'close';
 /**
- * Where the page drew one caption button, in CSS px relative to the WebView2 — i.e. straight out of
- * `getBoundingClientRect()`. The host converts to physical px using the control's DeviceDpi.
+ * Where the page drew one caption button, in CSS px relative to the page — i.e. straight out of
+ * `getBoundingClientRect()`. The host converts to physical px at the window's DPI.
  */
 export interface CaptionButtonRect {
     kind: CaptionButtonKind;
@@ -16,6 +17,42 @@ export interface CaptionButtonRect {
     width: number;
     height: number;
 }
+/**
+ * What the OS is doing to the page's caption buttons: the one the pointer is over, and the one being pressed.
+ * Absent means none.
+ */
+export interface CaptionButtonState {
+    hot?: CaptionButtonKind;
+    pressed?: CaptionButtonKind;
+}
+/**
+ * The colours of the caption buttons the window paints (`NativeCaptionButtons`), each a CSS hex colour: `#rgb`,
+ * `#rgba`, `#rrggbb` or `#rrggbbaa`. Mirrors the host's `CaptionButtonColors`.
+ */
+export interface CaptionButtonColors {
+    /** The title bar's own colour. The WebView2 shell paints it behind its buttons; the Chromium shell's idle buttons
+     * show the page through them, so it is unused there. */
+    surface: string;
+    /** A hovered minimize or maximize button's background. */
+    hover: string;
+    /** A pressed minimize or maximize button's background. */
+    pressed: string;
+    /** The glyphs. */
+    glyph: string;
+    /** A hovered close button's background, red by the platform's convention. */
+    closeHover: string;
+    /** A pressed close button's background. */
+    closePressed: string;
+    /** The close glyph while close is hovered or pressed. Absent: `glyph`. */
+    closeGlyphHot?: string;
+    /** The idle glyphs while the window is inactive. Absent: `glyph` at about a third of its opacity. */
+    inactiveGlyph?: string;
+}
+/** The host's `SHENORA.WINDOW` event names, pinned against it by `WireMirrorTests`. */
+export declare const WindowEventTypes: {
+    /** A {@link CaptionButtonState}, sent to the window's own page. See {@link useCaptionButtonState}. */
+    readonly CaptionButtonState: "CAPTION_BUTTON_STATE";
+};
 interface WindowRequests {
     MINIMIZE: void;
     TOGGLE_MAXIMIZE: void;
@@ -25,12 +62,16 @@ interface WindowRequests {
     START_RESIZE: {
         edge: WindowResizeEdge;
     };
+    SHOW_SYSTEM_MENU: void;
     SET_THEME: {
         dark: boolean;
     };
     SET_CAPTION_BUTTONS: {
         buttons: CaptionButtonRect[];
     };
+    SET_CAPTION_BUTTON_COLORS: {
+        colors?: CaptionButtonColors;
+    };
 }
 /**
  * Typed client for the host's `SHENORA.WINDOW` module (`WindowCommandModule` in Shenora.Windows) —
@@ -51,6 +92,13 @@ export declare class WindowCommands extends BaseModuleService<WindowRequests> {
     startDrag(): Promise<void>;
     /** Call from the top strip's `onMouseDown` — hands off to the OS size loop. */
     startResize(edge?: WindowResizeEdge): Promise<void>;
+    /**
+     * Open the window's system menu at the pointer, as a right click on a real caption does. Call from the header's
+     * `onContextMenu`, and `preventDefault()` there so the browser's own menu does not open too. It resolves as the
+     * menu opens, not when it closes. A Chromium page's `-webkit-app-region: drag` area opens the menu on a right click
+     * without it.
+     */
+    showSystemMenu(): Promise<void>;
     /** Resync the native chrome to the app theme (host `WindowCommandOptions.ApplyTheme`). */
     setTheme(dark: boolean): Promise<void>;
     /**
@@ -58,15 +106,41 @@ export declare class WindowCommands extends BaseModuleService<WindowRequests> {
      * chiefly so Windows 11 offers **Snap Layouts** on the maximize button.
      *
      * ⚠ The host then takes over CLICKS in those rects and performs minimize/maximize/close itself, so
-     * your `onClick` handlers stop firing there. CSS `:hover` stops firing too — subscribe to the host's
-     * caption-button state to render hot/pressed, which is also the only way to stay hot while the
-     * pointer is over the snap flyout, a different window.
+     * your `onClick` handlers stop firing there. CSS `:hover` stops firing too: render hot and pressed from
+     * {@link useCaptionButtonState}.
+     *
+     * ⚠ The Chromium shell forgets the rects when a new document loads, so send them from the page on
+     * every load as well as on every layout change.
+     *
+     * On either shell the window can paint the buttons itself instead (`NativeCaptionButtons` on
+     * `OptimizedFormOptions` or `ChromiumWindowOptions`): then the page reserves the rects and draws nothing
+     * there. The Chromium shell's painted buttons follow {@link WindowCommands.setTheme}.
      *
      * ⚠ Re-send on every layout change: the rectangles are a snapshot, and a stale one moves the
      * hit-test off the button the user can see. Pass an empty array to hand the pixels back to the page.
      */
     setCaptionButtons(buttons: CaptionButtonRect[]): Promise<void>;
+    /**
+     * Colour the caption buttons the window paints, to match the page's title bar; send them again when the page's
+     * theme changes. `null` goes back to the default: on the Chromium shell the colours of {@link WindowCommands.setTheme},
+     * on the WebView2 shell a fallback from the form's own colour (it replaces `OptimizedForm.CaptionButtonColors`).
+     * The row's height is the page's: the rects sent to {@link WindowCommands.setCaptionButtons}.
+     *
+     * ⚠ Rejects with `NO_ROUTE` where the window does not paint its buttons, and with `INVALID_PAYLOAD_VALUE` for a
+     * colour that is not CSS hex.
+     */
+    setCaptionButtonColors(colors: CaptionButtonColors | null): Promise<void>;
 }
+/**
+ * Which caption button to render hot or pressed, for buttons registered with
+ * {@link WindowCommands.setCaptionButtons}, where CSS `:hover` no longer fires. The Chromium shell sends it to
+ * the window's own page as the pointer moves. The WebView2 shell sends nothing by itself: with
+ * `NativeCaptionButtons` it paints the caption buttons itself, and an app drawing its own there can emit this
+ * event from `OptimizedForm.CaptionButtonStateChanged`.
+ */
+export declare function useCaptionButtonState(options?: {
+    bus?: ShenoraEventBus;
+}): CaptionButtonState;
 /**
  * The authoritative maximize state, re-queried when a resize SETTLES — a maximize/restore always
  * resizes the window, and the DOM has no other signal for the manual work-area maximize. Failures

package/dist/windowCommands.js

@@ -1,6 +1,12 @@
 import { useEffect, useRef, useState } from 'react';
+import { useShenoraEvent } from './hooks.js';
 import { debounce } from './internal.js';
 import { BaseModuleService } from './moduleService.js';
+/** The host's `SHENORA.WINDOW` event names, pinned against it by `WireMirrorTests`. */
+export const WindowEventTypes = {
+    /** A {@link CaptionButtonState}, sent to the window's own page. See {@link useCaptionButtonState}. */
+    CaptionButtonState: 'CAPTION_BUTTON_STATE',
+};
 /**
  * Typed client for the host's `SHENORA.WINDOW` module (`WindowCommandModule` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
@@ -35,6 +41,15 @@ export class WindowCommands extends BaseModuleService {
     startResize(edge = 'top') {
         return this.send('START_RESIZE', { payload: { edge } });
     }
+    /**
+     * Open the window's system menu at the pointer, as a right click on a real caption does. Call from the header's
+     * `onContextMenu`, and `preventDefault()` there so the browser's own menu does not open too. It resolves as the
+     * menu opens, not when it closes. A Chromium page's `-webkit-app-region: drag` area opens the menu on a right click
+     * without it.
+     */
+    showSystemMenu() {
+        return this.send('SHOW_SYSTEM_MENU');
+    }
     /** Resync the native chrome to the app theme (host `WindowCommandOptions.ApplyTheme`). */
     setTheme(dark) {
         return this.send('SET_THEME', { payload: { dark } });
@@ -44,9 +59,15 @@ export class WindowCommands extends BaseModuleService {
      * chiefly so Windows 11 offers **Snap Layouts** on the maximize button.
      *
      * ⚠ The host then takes over CLICKS in those rects and performs minimize/maximize/close itself, so
-     * your `onClick` handlers stop firing there. CSS `:hover` stops firing too — subscribe to the host's
-     * caption-button state to render hot/pressed, which is also the only way to stay hot while the
-     * pointer is over the snap flyout, a different window.
+     * your `onClick` handlers stop firing there. CSS `:hover` stops firing too: render hot and pressed from
+     * {@link useCaptionButtonState}.
+     *
+     * ⚠ The Chromium shell forgets the rects when a new document loads, so send them from the page on
+     * every load as well as on every layout change.
+     *
+     * On either shell the window can paint the buttons itself instead (`NativeCaptionButtons` on
+     * `OptimizedFormOptions` or `ChromiumWindowOptions`): then the page reserves the rects and draws nothing
+     * there. The Chromium shell's painted buttons follow {@link WindowCommands.setTheme}.
      *
      * ⚠ Re-send on every layout change: the rectangles are a snapshot, and a stale one moves the
      * hit-test off the button the user can see. Pass an empty array to hand the pixels back to the page.
@@ -54,6 +75,30 @@ export class WindowCommands extends BaseModuleService {
     setCaptionButtons(buttons) {
         return this.send('SET_CAPTION_BUTTONS', { payload: { buttons } });
     }
+    /**
+     * Colour the caption buttons the window paints, to match the page's title bar; send them again when the page's
+     * theme changes. `null` goes back to the default: on the Chromium shell the colours of {@link WindowCommands.setTheme},
+     * on the WebView2 shell a fallback from the form's own colour (it replaces `OptimizedForm.CaptionButtonColors`).
+     * The row's height is the page's: the rects sent to {@link WindowCommands.setCaptionButtons}.
+     *
+     * ⚠ Rejects with `NO_ROUTE` where the window does not paint its buttons, and with `INVALID_PAYLOAD_VALUE` for a
+     * colour that is not CSS hex.
+     */
+    setCaptionButtonColors(colors) {
+        return this.send('SET_CAPTION_BUTTON_COLORS', { payload: colors ? { colors } : {} });
+    }
+}
+/**
+ * Which caption button to render hot or pressed, for buttons registered with
+ * {@link WindowCommands.setCaptionButtons}, where CSS `:hover` no longer fires. The Chromium shell sends it to
+ * the window's own page as the pointer moves. The WebView2 shell sends nothing by itself: with
+ * `NativeCaptionButtons` it paints the caption buttons itself, and an app drawing its own there can emit this
+ * event from `OptimizedForm.CaptionButtonStateChanged`.
+ */
+export function useCaptionButtonState(options = {}) {
+    const [state, setState] = useState({});
+    useShenoraEvent('SHENORA.WINDOW', WindowEventTypes.CaptionButtonState, (payload) => setState(payload ?? {}), { bus: options.bus });
+    return state;
 }
 /**
  * The authoritative maximize state, re-queried when a resize SETTLES — a maximize/restore always

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shenora/react",
-  "version": "0.16.0",
-  "description": "React client for Shenora hosts on Windows, Android and iOS: correlated invoke/send/subscribe over the desktop postMessage bridge or the MAUI HybridWebView transport, typed module services, host-backed stores, and hooks for request tracking and media playback. Drop zones and window commands are desktop-only, because the capabilities are. Ships a browser fallback for pure-UI development.",
+  "version": "0.17.1",
+  "description": "React client for Shenora hosts on Windows, macOS, Android and iOS: correlated invoke/send/subscribe over whichever host transport the page is in (WebView2 postMessage, the Chromium hosts' same-origin route, or MAUI HybridWebView), typed module services, host-backed stores, and hooks for request tracking and media playback. Drop zones and window commands are desktop-only, because the capabilities are. Ships a browser fallback for pure-UI development.",
   "license": "MIT",
   "author": "Jiarong Gu",
   "repository": {
@@ -13,6 +13,8 @@
   "keywords": [
     "shenora",
     "webview2",
+    "chromium",
+    "cef",
     "desktop",
     "android",
     "ios",