@shenora/react 0.15.0 → 0.17.0

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

@@ -131,6 +131,31 @@ export declare const ShellCapabilities: {
      * and allowed roots are the app's, and it says nothing about the URL SCHEME.
      */
     readonly localFiles: "localFiles";
+    /**
+     * The shell can HOLD the window at an orientation — see `WindowOrientation`. Android only today; the
+     * desktop has nothing to hold, and iOS refuses rather than half-doing it.
+     *
+     * ⚠ Branch on it, because the page's own fallback is real but weaker: `screen.orientation.lock()` is
+     * honoured only while the document is FULLSCREEN, and not at all in WKWebView. Absent here means take
+     * 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

@@ -101,4 +101,29 @@ export const ShellCapabilities = {
      * and allowed roots are the app's, and it says nothing about the URL SCHEME.
      */
     localFiles: 'localFiles',
+    /**
+     * The shell can HOLD the window at an orientation — see `WindowOrientation`. Android only today; the
+     * desktop has nothing to hold, and iOS refuses rather than half-doing it.
+     *
+     * ⚠ Branch on it, because the page's own fallback is real but weaker: `screen.orientation.lock()` is
+     * honoured only while the document is FULLSCREEN, and not at all in WKWebView. Absent here means take
+     * 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/dist/windowOrientation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Hold the window at an orientation. Mirrors `Shenora.Modules.Platform.WindowOrientationModule`, pinned
+ * by `WireMirrorTests`.
+ *
+ * 🔴 **Try `screen.orientation.lock()` first — and know why it usually will not do.** The web API is
+ * honoured only while the document is FULLSCREEN, so a page can hold an orientation only by taking over
+ * the display; and WKWebView does not implement it at all. This route has neither limitation, because the
+ * host asks the platform directly. The common shape — portrait everywhere EXCEPT a media viewer — is
+ * exactly the one the web API cannot express.
+ *
+ * ⚠ **Branch on the `windowOrientation` capability**, which only a shell that can really hold an
+ * orientation advertises. Calling where it is absent is refused with `CAPABILITY_NOT_SUPPORTED` rather
+ * than silently ignored — but a page that checks first never shows a control that cannot work.
+ *
+ * ⚠ **There is no "what is it now".** The page already knows: `screen.orientation.type`, or a CSS media
+ * query that re-renders for it. An IPC answer would be the same fact, later.
+ */
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** The orientations a window can be held at — the host's `WindowOrientation` enum, serialized. */
+export type WindowOrientationKind = 'portrait' | 'landscape';
+interface WindowOrientationRequests {
+    LOCK: {
+        orientation: WindowOrientationKind;
+    };
+    UNLOCK: void;
+}
+/**
+ * Typed client for the host's `SHENORA.ORIENTATION` module. Two calls and no state: the app decides
+ * WHEN, the kit never rotates anything by itself.
+ *
+ * ```tsx
+ * const orientation = new WindowOrientation();
+ * useEffect(() => {
+ *   if (!capabilities.has('windowOrientation')) return;
+ *   orientation.lock('landscape');            // entering the viewer
+ *   return () => { void orientation.unlock(); };  // leaving it
+ * }, []);
+ * ```
+ */
+export declare class WindowOrientation extends BaseModuleService<WindowOrientationRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /** Hold the window at `orientation` until {@link unlock}. Idempotent; a second lock replaces the first. */
+    lock(orientation: WindowOrientationKind): Promise<void>;
+    /** Let the platform choose again — whatever the device's own rotation setting says. Idempotent. */
+    unlock(): Promise<void>;
+}
+export {};

package/dist/windowOrientation.js

@@ -0,0 +1,27 @@
+import { BaseModuleService } from './moduleService.js';
+/**
+ * Typed client for the host's `SHENORA.ORIENTATION` module. Two calls and no state: the app decides
+ * WHEN, the kit never rotates anything by itself.
+ *
+ * ```tsx
+ * const orientation = new WindowOrientation();
+ * useEffect(() => {
+ *   if (!capabilities.has('windowOrientation')) return;
+ *   orientation.lock('landscape');            // entering the viewer
+ *   return () => { void orientation.unlock(); };  // leaving it
+ * }, []);
+ * ```
+ */
+export class WindowOrientation extends BaseModuleService {
+    constructor(bridge) {
+        super('SHENORA.ORIENTATION', bridge);
+    }
+    /** Hold the window at `orientation` until {@link unlock}. Idempotent; a second lock replaces the first. */
+    lock(orientation) {
+        return this.send('LOCK', { payload: { orientation } });
+    }
+    /** Let the platform choose again — whatever the device's own rotation setting says. Idempotent. */
+    unlock() {
+        return this.send('UNLOCK');
+    }
+}