@shenora/react 0.9.1 → 0.11.0

package/dist/segmentStream.js

@@ -0,0 +1,248 @@
+/**
+ * The page half of the host's segment route (D71 piece 4) — reading the manifest it serves, choosing the
+ * MediaSource this browser actually has, and deciding what to fetch next.
+ *
+ * 🔴 **Everything in this module is PURE, and the split is deliberate.** The DECISIONS live here, where a
+ * test pins them exactly, and `segmentBinder.ts` holds the imperative half — creating a `SourceBuffer`,
+ * appending bytes, listening to element events. That is the same division `SegmentGrid` makes on the host
+ * side, for the same reason.
+ *
+ * ⚠ **"The imperative half cannot be verified anywhere this repo runs" was true and is no longer.** jsdom
+ * still has no MediaSource and both real implementations still live on devices — but the binder takes its
+ * source and its fetch as PARAMETERS, so a fake drives every branch of it. What a fake cannot say is
+ * whether a real implementation accepts the bytes; that is measured on hardware and recorded in
+ * `docs/design/media.md`.
+ */
+/**
+ * Parse the subset of HLS the host emits. Deliberately NOT a general playlist parser: this reads what
+ * `SegmentStream` writes, and anything it does not understand is ignored rather than guessed at.
+ *
+ * ⚠ Unknown tags are skipped silently BY DESIGN — a playlist gains tags over time and a parser that threw
+ * on the first one it had not met would break on a host newer than the page.
+ */
+export function parseManifest(text) {
+    const segments = [];
+    let initUri = null;
+    let targetSeconds = 0;
+    let pending = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#EXT-X-MAP:')) {
+            // URI="init.mp4" — quoted per the spec, and the quotes are not optional there.
+            initUri = /URI="([^"]*)"/.exec(line)?.[1] ?? null;
+            continue;
+        }
+        if (line.startsWith('#EXT-X-TARGETDURATION:')) {
+            targetSeconds = Number(line.slice('#EXT-X-TARGETDURATION:'.length)) || 0;
+            continue;
+        }
+        if (line.startsWith('#EXTINF:')) {
+            // `#EXTINF:6.000,` — the trailing comma introduces an optional title.
+            pending = Number(line.slice('#EXTINF:'.length).split(',')[0]) || 0;
+            continue;
+        }
+        if (line.startsWith('#'))
+            continue;
+        // A bare line is a URI, and it belongs to the EXTINF above it.
+        segments.push({ uri: line, seconds: pending ?? 0 });
+        pending = null;
+    }
+    return { initUri, targetSeconds, segments };
+}
+/**
+ * Which MediaSource to use — **`ManagedMediaSource` first where it exists**.
+ *
+ * 🔴 **The order is the decision, and it is not "newest wins".** iOS on iPhone has only
+ * `ManagedMediaSource`; Android has only `MediaSource`. Where BOTH exist the managed one is still preferred,
+ * because it is the one that tells the page when the platform actually wants data — a page that streams
+ * regardless is what the managed variant was introduced to stop.
+ *
+ * ✅ **Measured rather than assumed** (iPhone 16 Pro simulator, iOS 26, 2026-08-14): `window.MediaSource` is
+ * `false` there and `ManagedMediaSource` is `true`. So on iOS this is not a preference at all — **a binder
+ * that only knows `window.MediaSource` does nothing**, and the naming here is what makes one bundle work on
+ * both shells.
+ *
+ * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND rather than just a constructor.**
+ * A managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
+ * outside that window is the thing it exists to prevent. A caller that ignores the kind has not merely
+ * missed an optimisation.
+ */
+export function pickMediaSource(globals) {
+    if (typeof globals.ManagedMediaSource === 'function')
+        return 'managed';
+    if (typeof globals.MediaSource === 'function')
+        return 'standard';
+    return 'none';
+}
+/**
+ * The next segment index to fetch, or null for "nothing right now".
+ *
+ * 🔴 **Every branch here is a decision whose failure is SILENT in a browser**, which is why it is a pure
+ * function with a test rather than an `if` inside an event handler:
+ *
+ * - **Not streaming → null.** A managed source that is fetched while it said stop is the exact misuse it
+ *   exists to detect, and on iOS the penalty is the platform tearing the source down.
+ * - **Enough buffered → null.** Fetching further ahead than the policy asks does not make playback smoother;
+ *   it fills a quota, and a `QuotaExceededError` on append arrives as a stall with no obvious cause.
+ * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it.** Starting from
+ *   "the next index after the last one appended" instead is what breaks seeking: after a jump the last
+ *   append is nowhere near where the user is now.
+ */
+export function nextSegment(state, policy) {
+    if (!state.streaming)
+        return null;
+    if (state.bufferedAhead >= policy.targetAheadSeconds)
+        return null;
+    if (policy.segments.length === 0)
+        return null;
+    // Walk the playlist's own durations rather than assuming a fixed grid: the LAST segment is short, so
+    // dividing by the target duration puts the tail index past the end.
+    let at = 0;
+    let index = 0;
+    for (; index < policy.segments.length; index++) {
+        const end = at + policy.segments[index].seconds;
+        if (state.currentTime < end)
+            break;
+        at = end;
+    }
+    for (let i = Math.min(index, policy.segments.length - 1); i < policy.segments.length; i++) {
+        if (!state.appended.has(i))
+            return i;
+    }
+    return null;
+}
+/**
+ * The MIME type to open a `SourceBuffer` with.
+ *
+ * ⚠ **The codecs parameter is REQUIRED, not decorative.** `addSourceBuffer('video/mp4')` throws
+ * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed before the
+ * init segment arrives. The default is H.264 High 4.0 plus AAC-LC.
+ *
+ * 🔴 **And the default is a DEFAULT rather than a guarantee, because the host copies whatever the source
+ * already holds** (D76): a segment's picture keeps the profile and level the original encoder chose, and an
+ * HEVC source arrives as `hvc1` and not `avc1` at all. The family is what an implementation actually checks,
+ * so an H.264 source of any profile plays through the default — **an HEVC one needs its own string**, e.g.
+ * `segmentMimeType('hvc1.1.6.L93.B0,mp4a.40.2')`.
+ */
+export function segmentMimeType(codecs = 'avc1.640028,mp4a.40.2') {
+    return `video/mp4; codecs="${codecs}"`;
+}
+/**
+ * Read the codecs parameter out of an initialisation segment, so the `SourceBuffer` is opened for the
+ * tracks it will actually be fed.
+ *
+ * 🔴 **The TRACK SET is the part that must be right, and getting it wrong is fatal rather than
+ * degraded.** Measured against Chromium 151 on the kit's own segments: a video-only init segment
+ * appended to a buffer opened with the two-track default (`avc1.640028,mp4a.40.2`) fails the FIRST
+ * append and plays nothing at all — while the same bytes with `avc1.640015` play. A source with no
+ * soundtrack is ordinary, so a fixed default cannot serve both.
+ *
+ * ⚠ **The profile and level, by contrast, are barely checked.** The same measurement fed High 2.1
+ * content to a buffer opened as Baseline 3.0 (`avc1.42E01E`) and it played. That is why this returns a
+ * precise string when the configuration is there to read and a family default when it is not: precision
+ * where it is free, and never a guess about which tracks exist.
+ *
+ * @param init The bytes of the `#EXT-X-MAP` segment.
+ * @returns A codecs string for {@link segmentMimeType}, or null when no track could be read — the caller
+ *   should treat that as "do not open a SourceBuffer", not as "use the default".
+ */
+export function codecsFromInitSegment(init) {
+    const view = new DataView(init.buffer, init.byteOffset, init.byteLength);
+    const codecs = [];
+    /** Bytes are read through the view rather than by index: `noUncheckedIndexedAccess` types `init[i]`
+     * as possibly-undefined, and a `!` on every read would hide the one that IS out of range. */
+    const u8 = (at) => view.getUint8(at);
+    const fourcc = (at) => String.fromCharCode(u8(at), u8(at + 1), u8(at + 2), u8(at + 3));
+    const hex2 = (n) => n.toString(16).padStart(2, '0');
+    /** Walk the direct children of [start, end), calling `visit` with (type, contentStart, contentEnd). */
+    const children = (start, end, visit) => {
+        let at = start;
+        while (at + 8 <= end) {
+            let size = view.getUint32(at);
+            let header = 8;
+            if (size === 1) {
+                if (at + 16 > end)
+                    return;
+                size = Number(view.getBigUint64(at + 8));
+                header = 16;
+            }
+            if (size === 0)
+                size = end - at;
+            if (size < header || at + size > end)
+                return;
+            visit(fourcc(at + 4), at + header, at + size);
+            at += size;
+        }
+    };
+    /** The `avcC`/`hvcC`/`esds` inside a sample entry, whose own fields come first. */
+    const configuration = (format, start, end) => {
+        // Measured against the host's own init segment: an `avc1` entry holds 132 bytes of content and a
+        // 54-byte `avcC`, so the child boxes start 78 in — the 8-byte SampleEntry base (6 reserved + a data
+        // reference index) plus VisualSampleEntry's 70. An `mp4a` entry is that base plus 20.
+        const visual = format === 'avc1' || format === 'avc3' || format === 'hvc1' || format === 'hev1';
+        const at = start + (visual ? 78 : 28);
+        let derived = '';
+        children(at, end, (type, s) => {
+            if ((type === 'avcC') && s + 4 <= end) {
+                // configurationVersion, AVCProfileIndication, profile_compatibility, AVCLevelIndication
+                derived = `${format}.${hex2(u8(s + 1))}${hex2(u8(s + 2))}${hex2(u8(s + 3))}`;
+            }
+            else if (type === 'hvcC' && s + 13 <= end) {
+                // ISO 14496-15 §8.3.3: profile_space/tier/idc, then 4 compatibility bytes, 6 constraint bytes,
+                // then the level. Rendered in the form Chromium and Safari both accept.
+                const space = (u8(s + 1) >> 6) & 0x3;
+                const tier = (u8(s + 1) >> 5) & 0x1;
+                const idc = u8(s + 1) & 0x1f;
+                const compat = view.getUint32(s + 2);
+                const level = u8(s + 12);
+                const spaces = ['', 'A', 'B', 'C'][space];
+                // The compatibility flags travel REVERSED, as a bit string, per the spec's C.1.
+                let reversed = 0;
+                for (let bit = 0; bit < 32; bit++)
+                    reversed |= ((compat >>> bit) & 1) << (31 - bit);
+                derived = `${format}.${spaces}${idc}.${(reversed >>> 0).toString(16).toUpperCase()}.` +
+                    `${tier ? 'H' : 'L'}${level}`;
+            }
+            else if (type === 'esds' && s + 21 <= end) {
+                // The object type indication, then the audio object type from the DecoderSpecificInfo's first
+                // 5 bits. Only AAC is ever copied here, so the walk stays a search rather than a full parser.
+                for (let p = s; p + 2 < end; p++) {
+                    if (u8(p) === 0x04 && u8(p + 2) === 0x40) {
+                        derived = `mp4a.40.${u8(p + 3) || 2}`;
+                        break;
+                    }
+                }
+                if (!derived)
+                    derived = 'mp4a.40.2';
+            }
+        });
+        if (derived)
+            return derived;
+        // No configuration to read: name the FAMILY, which is what an implementation actually checks.
+        return format === 'mp4a' ? 'mp4a.40.2' : format;
+    };
+    const stsd = (start, end) => {
+        // FullBox header (4) + entry_count (4), then the entries.
+        let at = start + 8;
+        while (at + 8 <= end) {
+            const size = view.getUint32(at);
+            if (size < 8 || at + size > end)
+                return;
+            codecs.push(configuration(fourcc(at + 4), at + 8, at + size));
+            at += size;
+        }
+    };
+    const descend = (start, end) => {
+        children(start, end, (type, s, e) => {
+            if (type === 'stsd')
+                stsd(s, e);
+            else if (type === 'moov' || type === 'trak' || type === 'mdia' || type === 'minf' || type === 'stbl') {
+                descend(s, e);
+            }
+        });
+    };
+    descend(0, init.byteLength);
+    return codecs.length > 0 ? codecs.join(',') : null;
+}

package/dist/store.d.ts

@@ -13,12 +13,16 @@ export interface ShenoraStoreIo<TState = unknown> {
     /** Current state — for an action that needs to compute an OPTIMISTIC update from it. */
     getState: () => TState;
     /**
-     * Apply a local state change with NO host round trip and NO wire event — the seam for an
-     * optimistic update an action can fully decide by itself (e.g. dropping the rows a
-     * `CLEAR_FINISHED`-style action just told the host to drop). The host stays authoritative for
-     * everything a `snapshot`/`on` reducer already covers; this exists for the narrow case where the
-     * action already knows the answer and a host round trip would only be a delivery delay, not new
-     * information.
+     * Apply a local state change with NO host round trip and NO wire event — an optimistic update an
+     * action can fully decide by itself. The host stays authoritative for everything a `snapshot`/`on`
+     * reducer covers; this is for state the ACTION already knows and the host would only echo back.
+     *
+     * 🔴 **Reach for it only when the host has no event to tell you.** This used to be documented with
+     * the kit's own `clearFinished` doing an optimistic prune, and that example was WITHDRAWN: the
+     * moment `REQUEST_REMOVED` existed, the local prune became a second thing deciding which rows are
+     * gone, able to disagree with the host about it. If the host emits an event for the change, let the
+     * reducer own it — an optimistic path beside a wire event is a divergence waiting to happen, not a
+     * latency win.
      */
     setState: (reduce: (state: TState) => TState) => void;
 }
@@ -30,7 +34,6 @@ export interface ShenoraStoreSnapshot<TState> {
     /** Fold the response into state. */
     apply: (state: TState, data: unknown) => TState;
 }
-/** Inputs for {@link createShenoraStore}. */
 export interface ShenoraStoreOptions<TState, TActions> {
     /** State before anything has arrived. */
     initial: TState;

package/dist/store.js

@@ -1,6 +1,32 @@
 import { useCallback, useDebugValue, useRef, useSyncExternalStore } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
+/** Inputs for {@link createShenoraStore}. */
+/**
+ * Is the fresh selector result the same VALUE as the previous one, for re-render purposes?
+ *
+ * `Object.is` plus ONE level of own-key comparison. The shallow step is what lets an inline selector
+ * that derives a new object work — `s => ({ count: s.lines.length })` builds a different object every
+ * call, and without this every call would look like a change and loop.
+ *
+ * ⚠ Deliberately one level. Deep equality would make an unchanged NESTED value hide a changed outer
+ * one only by cost, and a store whose selectors need deep comparison is selecting too much.
+ */
+function equivalent(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    // Arrays and plain objects only — anything exotic (Map, Date, a class) falls back to identity above.
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(b, k)
+        && Object.is(a[k], b[k]));
+}
 /**
  * A store fed by one module's host event stream, shared by every component that reads it.
  *
@@ -46,6 +72,10 @@ export function createShenoraStore(module, options) {
         ?? ((error, context) => console.error(`[shenora] store ${context.module}.${context.type} failed:`, error));
     let state = initial;
     let snapshotLoaded = false;
+    // Bumped on detach. A snapshot response from an earlier subscriber epoch resolving late must be
+    // DROPPED: the current epoch has (or will have) its own, fresher request, and applying the old
+    // body after the new one is a lost update wearing a success path.
+    let snapshotEpoch = 0;
     const listeners = new Set();
     let unsubscribes = [];
     const bridge = () => options.bridge ?? getBridge();
@@ -66,7 +96,7 @@ export function createShenoraStore(module, options) {
         }
         catch (error) {
             // A throwing reducer must not corrupt shared state or break the other subscribers — the same
-            // guarded-callback rule the host applies to app code (Shenora.Core.AppCallback).
+            // guarded-callback rule the host applies to app code (Shenora.AppCallback).
             report(error, { module, type });
         }
     };
@@ -75,9 +105,12 @@ export function createShenoraStore(module, options) {
             return;
         snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick must not
         // both fire the request (React StrictMode double-invokes effects, which is precisely this case).
+        const epoch = snapshotEpoch;
         bridge()
             .invoke(module, snapshot.type, { payload: snapshot.payload, scope })
             .then((data) => {
+            if (epoch !== snapshotEpoch)
+                return; // a previous epoch's answer — the live one owns state
             try {
                 setState(snapshot.apply(state, data));
             }
@@ -85,6 +118,8 @@ export function createShenoraStore(module, options) {
                 report(error, { module, type: snapshot.type });
             }
         }, (error) => {
+            if (epoch !== snapshotEpoch)
+                return;
             // Allow a later retry: a snapshot that failed because the host was not ready yet should not
             // leave the store permanently empty for the rest of the session.
             snapshotLoaded = false;
@@ -99,6 +134,13 @@ export function createShenoraStore(module, options) {
         for (const off of unsubscribes)
             off();
         unsubscribes = [];
+        // The next mount must RE-LOAD: with no bus subscription live, everything the host emits from
+        // here on is missed, so the snapshot the flag was guarding is stale the moment this returns.
+        // The flag exists to dedupe same-tick double-mounts (StrictMode), not to span subscriber epochs —
+        // and the epoch bump orphans any request still in flight, so its late answer cannot clobber the
+        // next epoch's fresher one.
+        snapshotLoaded = false;
+        snapshotEpoch++;
     };
     const subscribe = (listener) => {
         // ONE subscription per event type for the whole store — the property that makes this worth
@@ -119,23 +161,42 @@ export function createShenoraStore(module, options) {
         getState,
         setState: (reduce) => setState(reduce(getState())),
     };
+    /**
+     * Subscribe to the store, optionally through a selector.
+     *
+     * 🔴 **The selector is RE-RUN every time and the previous RESULT is reused when equivalent.** It used
+     * to be memoized against STATE identity alone, which looked like the careful thing and was wrong: a
+     * selector whose closure changed while the state did not returned the PREVIOUS selector's value. A
+     * list row doing `useShenoraRequests(s => s.byId[id])` whose `id` prop changes — virtualised reuse, a
+     * route change — rendered the previous row's data until some unrelated event replaced the state.
+     *
+     * ⚠ <b>Two requirements pull against each other and both are met by comparing RESULTS rather than
+     * inputs.</b> `useSyncExternalStore` re-renders whenever `getSnapshot` returns something new by
+     * `Object.is`, so:
+     * <list type="bullet">
+     * <item>keying the cache on STATE alone gives stale values when the selector changes — the bug above;</item>
+     * <item>keying it on the SELECTOR too loops forever for an inline selector that derives a new object
+     * (`s => ({ count: s.lines.length })`) — a fresh identity each render, a fresh object each call.
+     * zustand v5 has exactly that behaviour and answers it with an opt-in `useShallow`.</item>
+     * </list>
+     * Comparing the RESULT shallowly gives both: a derived object that is field-for-field the same reuses
+     * the previous reference and does not re-render, while a genuinely different row does.
+     */
     function useStore(selector) {
-        // getSnapshot must return a STABLE value for an unchanged store, or React throws
-        // "The result of getSnapshot should be cached" and can loop. So the selector result is memoized
-        // against the state identity: recomputed only when state actually changed.
-        const cache = useRef(null);
-        const selectorRef = useRef(selector);
-        selectorRef.current = selector;
+        // The last result handed to React. Reused whenever the fresh one is equivalent, which is what keeps
+        // getSnapshot stable without pinning it to an input that can go stale.
+        const previous = useRef(null);
         const getSelected = useCallback(() => {
             const current = getState();
-            const select = selectorRef.current;
-            if (!select)
+            if (!selector)
                 return current;
-            if (cache.current === null || !Object.is(cache.current.state, current)) {
-                cache.current = { state: current, selected: select(current) };
+            const next = selector(current);
+            if (previous.current !== null && equivalent(previous.current.value, next)) {
+                return previous.current.value;
             }
-            return cache.current.selected;
-        }, []);
+            previous.current = { value: next };
+            return next;
+        }, [selector]);
         const value = useSyncExternalStore(subscribe, getSelected, getSelected);
         useDebugValue(value);
         return value;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Shenora IPC wire contract — the TS mirror of the `Shenora.Ipc` C# envelopes (names are
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.Core.Ipc` C# envelopes (names are
  * pinned on both sides; the host serializes camelCase). Transport-neutral: the same envelopes
  * travel over WebView2 postMessage, a WebSocket, or a mobile shell's channel.
  */
@@ -21,7 +21,23 @@ export declare const HANDSHAKE_TYPE = "READY";
  */
 export declare const IpcErrorCodes: {
     readonly unknownError: "UNKNOWN_ERROR";
+    /**
+     * **No MODULE claimed the request** — nothing on the host answers that name. Parameters:
+     * `module`, `type`.
+     *
+     * ⚠ Distinct from {@link noRoute}, and the split is what makes it actionable: this means the module
+     * was never registered host-side, while `noRoute` means it WAS and does not know that type. Opposite
+     * fixes — wire the module up, versus correct a route name — so collapsing both into `NO_HANDLER` with
+     * identical parameters leaves a dead page undiagnosable from the wire.
+     */
     readonly noHandler: "NO_HANDLER";
+    /**
+     * **The module answered but has no route of that type.** Parameters: `module`, `type`.
+     *
+     * Seeing this is proof the module IS registered and mapped, which is exactly what {@link noHandler}
+     * cannot tell you — so this is a route-name problem, not a composition problem.
+     */
+    readonly noRoute: "NO_ROUTE";
     /**
      * A scope-routed module was called without a `scope`. Parameters: `module`.
      *
@@ -37,6 +53,19 @@ export declare const IpcErrorCodes: {
      * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
      */
     readonly operationCancelled: "OPERATION_CANCELLED";
+    /**
+     * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
+     * Parameters: `capability` (a {@link ShellCapabilities} value).
+     *
+     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
+     * because the capability is absent by design on that platform (a folder picker on a phone, for
+     * instance) rather than broken.
+     *
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
+     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
+     * intended path. This is the honest answer when a page asks anyway.
+     */
+    readonly capabilityNotSupported: "CAPABILITY_NOT_SUPPORTED";
     /** Client-only: the request timed out waiting for a response. */
     readonly timeout: "TIMEOUT";
     /** Client-only: no transport is available and no fallback was configured. */
@@ -105,6 +134,15 @@ export declare const ShellCapabilities: {
     readonly savePicker: "savePicker";
     readonly secondaryWindows: "secondaryWindows";
     readonly tray: "tray";
+    /**
+     * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
+     * file manager. No web API expresses this, and a phone's pasteboard has none — so it is the one part
+     * of the clipboard worth branching on.
+     *
+     * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
+     * `navigator.clipboard`'s job, not the host's.
+     */
+    readonly clipboardFiles: "clipboardFiles";
     /**
      * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
      * interceptor. Pair it with {@link mediaUrl}.

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * The Shenora IPC wire contract — the TS mirror of the `Shenora.Ipc` C# envelopes (names are
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.Core.Ipc` C# envelopes (names are
  * pinned on both sides; the host serializes camelCase). Transport-neutral: the same envelopes
  * travel over WebView2 postMessage, a WebSocket, or a mobile shell's channel.
  */
@@ -21,7 +21,23 @@ export const HANDSHAKE_TYPE = 'READY';
  */
 export const IpcErrorCodes = {
     unknownError: 'UNKNOWN_ERROR',
+    /**
+     * **No MODULE claimed the request** — nothing on the host answers that name. Parameters:
+     * `module`, `type`.
+     *
+     * ⚠ Distinct from {@link noRoute}, and the split is what makes it actionable: this means the module
+     * was never registered host-side, while `noRoute` means it WAS and does not know that type. Opposite
+     * fixes — wire the module up, versus correct a route name — so collapsing both into `NO_HANDLER` with
+     * identical parameters leaves a dead page undiagnosable from the wire.
+     */
     noHandler: 'NO_HANDLER',
+    /**
+     * **The module answered but has no route of that type.** Parameters: `module`, `type`.
+     *
+     * Seeing this is proof the module IS registered and mapped, which is exactly what {@link noHandler}
+     * cannot tell you — so this is a route-name problem, not a composition problem.
+     */
+    noRoute: 'NO_ROUTE',
     /**
      * A scope-routed module was called without a `scope`. Parameters: `module`.
      *
@@ -37,6 +53,19 @@ export const IpcErrorCodes = {
      * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
      */
     operationCancelled: 'OPERATION_CANCELLED',
+    /**
+     * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
+     * Parameters: `capability` (a {@link ShellCapabilities} value).
+     *
+     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
+     * because the capability is absent by design on that platform (a folder picker on a phone, for
+     * instance) rather than broken.
+     *
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
+     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
+     * intended path. This is the honest answer when a page asks anyway.
+     */
+    capabilityNotSupported: 'CAPABILITY_NOT_SUPPORTED',
     /** Client-only: the request timed out waiting for a response. */
     timeout: 'TIMEOUT',
     /** Client-only: no transport is available and no fallback was configured. */
@@ -63,6 +92,15 @@ export const ShellCapabilities = {
     savePicker: 'savePicker',
     secondaryWindows: 'secondaryWindows',
     tray: 'tray',
+    /**
+     * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
+     * file manager. No web API expresses this, and a phone's pasteboard has none — so it is the one part
+     * of the clipboard worth branching on.
+     *
+     * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
+     * `navigator.clipboard`'s job, not the host's.
+     */
+    clipboardFiles: 'clipboardFiles',
     /**
      * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
      * interceptor. Pair it with {@link mediaUrl}.

package/dist/useDropZone.d.ts

@@ -1,8 +1,8 @@
 import { type RefObject } from 'react';
 import { type ShenoraBridge } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
-/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneFacade`). */
-export declare const DROP_ZONE_MODULE = "DROP_ZONE";
+/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneModule`). */
+export declare const DROP_ZONE_MODULE = "SHENORA.DROPZONE";
 /** A native file drop delivered to a zone. */
 export interface DropZoneFileDrop {
     zoneId: string;
@@ -29,17 +29,30 @@ export interface UseDropZoneOptions {
     onDrop: (files: string[], drop: DropZoneFileDrop) => void;
     /** False = zone torn down (same as unmount). Default true. */
     enabled?: boolean;
-    /** Stable zone id; default: generated per mount. */
+    /** Stable zone id; default: generated per mount. ⚠ Read on the FIRST render only — changing it later
+     * does not re-register the zone, which is what "stable" means here. */
     zoneId?: string;
     /**
      * Class toggled on the element while a file drag hovers the zone. UNSTYLED — headless (D13):
      * the library ships no CSS; style it in the app. Default `"shenora-drop-hover"`.
+     * ⚠ Read on the FIRST render only, like {@link UseDropZoneOptions.zoneId}: the hover effect
+     * captures it for its cleanup while the drop path reads it live, so a mid-hover change would add one
+     * class and remove another, leaving the first stuck on the element. Switch it by remounting.
      */
     dropClassName?: string;
     /** The bridge to speak over. Default: the shared default bridge. */
     bridge?: ShenoraBridge;
     /** The event bus host notifications arrive on. Default: the shared bus. */
     bus?: ShenoraEventBus;
+    /**
+     * Where a failed REGISTER / UPDATE / SHOW / UNREGISTER is reported. Default: `console.error`.
+     *
+     * ⚠ Worth routing somewhere real, because a failure here is INVISIBLE in the UI: the page renders
+     * exactly as it should and files simply do not drop. This hook was the last error path in the package
+     * that could only ever reach the console — `bridge.ts`'s `onPostError`, `store.ts`'s `onError` and
+     * `segmentBinder.ts`'s `onDiagnostic` all take an app sink.
+     */
+    onError?: (error: unknown, route: string) => void;
 }
 /**
  * **The file-drop API for a Shenora page. Do not use the DOM's own drop event for files —