@civitai/blocks-react 0.56.0 → 0.57.0

package/dist/{internal → transport}/validate.js

@@ -53,6 +53,7 @@
  * helpers. Do not open-code the test again: the two spellings coexisted in one
  * file for a release precisely because it was inline at every call site.
  */
+import { isRoutableRequestId, isWireRequestIdShape } from './requestId.js';
 const isObject = (v) => v !== null && typeof v === 'object';
 const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 /** Accepts an ISO 8601 string that `new Date()` can parse to a finite timestamp. */
@@ -358,7 +359,7 @@ export function isValidTokenRefreshResponse(p) {
         return false;
     if (!isValidWrappedToken(p.token))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     return true;
 }
@@ -367,7 +368,7 @@ export function isValidWorkflowReply(p) {
         return false;
     if (!isValidWorkflowSnapshot(p.snapshot))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     return true;
 }
@@ -378,7 +379,7 @@ export function isValidBuzzPurchaseResult(p) {
         return false;
     if (p.newBalance !== undefined && typeof p.newBalance !== 'number')
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     return true;
 }
@@ -392,7 +393,7 @@ const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
 export function isValidBuzzBalanceResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -428,7 +429,7 @@ const VIEWER_STATUSES = new Set(['active', 'muted']);
 export function isValidViewerResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -513,7 +514,7 @@ function isPendingUpload(s) {
 export function isValidImageUploadResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     // `selected` absent → cancelled upload (valid). When present, it must match
     // one of the purpose-keyed shapes (moderated / generationSource / pending).
@@ -541,7 +542,7 @@ export function isValidImageUploadResult(p) {
 export function isValidImageScanResolved(p) {
     if (!isObject(p))
         return false;
-    if (!isNonEmptyString(p.requestId))
+    if (!isRoutableRequestId(p.requestId))
         return false;
     if (typeof p.imageId !== 'number' || !Number.isInteger(p.imageId) || p.imageId <= 0)
         return false;
@@ -569,7 +570,7 @@ export function isValidImageScanResolved(p) {
 export function isValidSharedUpdateResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -604,7 +605,7 @@ function isDateLike(v) {
 export function isValidBuzzTransactionsResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -644,7 +645,7 @@ export function isValidBuzzTransactionsResult(p) {
 export function isValidBuzzAccountsResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -675,7 +676,7 @@ export function isValidBuzzAccountsResult(p) {
 export function isValidDailyCompensationResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -711,7 +712,7 @@ const WILDCARD_PACK_ERROR_CODES = new Set([
 export function isValidWildcardPackResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined) {
         if (typeof p.error !== 'string' || !WILDCARD_PACK_ERROR_CODES.has(p.error))
@@ -806,7 +807,7 @@ function isValidAppWorkflow(w) {
 export function isValidAppWorkflowsResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -835,7 +836,7 @@ export function isValidAppWorkflowsResult(p) {
 export function isValidCancelAppWorkflowResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -867,7 +868,7 @@ export function isValidCancelAppWorkflowResult(p) {
 export function isValidPublishResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -892,9 +893,18 @@ const GATED_IMAGE_STATUSES = new Set(['visible', 'hidden']);
  * `imageId` is always a finite number and `status` one of `visible`/`hidden`.
  *  - `visible` → `url` a non-empty string and `width`/`height` each
  *    `number | null`, PLUS exactly one of two rating shapes (below).
- *  - `hidden`  → ONLY `imageId` + `status`. A `hidden` entry carrying a `url` is
- *    REJECTED — defense in depth against a buggy/hostile host leaking an
- *    unclamped url on an image the viewer isn't allowed to see.
+ *  - `hidden`  → `imageId` + `status`, and a `url` on one is REJECTED — defense
+ *    in depth against a buggy/hostile host leaking an unclamped url on an image
+ *    the viewer isn't allowed to see.
+ *
+ * 🔴 THIS PREDICATE DOES **NOT** ENFORCE AN ALLOWLIST ON A `hidden` ENTRY, AND AN
+ * EARLIER VERSION OF THIS DOCBLOCK CLAIMED IT DID ("ONLY imageId + status").
+ * It bans exactly one SPELLING — the literal key `url`. `previewUrl`, `src`,
+ * `imageUrl` or any other key sails through here. The allowlist is real, but it
+ * lives one step later, in {@link projectGatedImage}: every `hidden` entry is
+ * narrowed to `{ imageId, status }` at the transport boundary, so no extra key
+ * can reach a consumer. See that function for why the split is PROJECTION for
+ * unknown keys and REJECTION for `url`.
  *
  * 🔴 THE TWO `visible` SHAPES ARE MUTUALLY EXCLUSIVE, AND THAT IS ENFORCED.
  * A RATED entry carries `nsfwLevel` + `contentRating` and NO `ratingPending`; an
@@ -946,23 +956,72 @@ function isValidGatedImage(img) {
         }
         return true;
     }
-    // status === 'hidden': ONLY imageId + status. A leaked `url` on a hidden entry
-    // is the exact cross-user moderation-boundary breach this guard exists to catch.
+    // status === 'hidden'. A leaked `url` is the exact cross-user moderation-
+    // boundary breach this guard exists to catch, and the contract forbids the key
+    // outright, so it is fatal here. Every OTHER key is left to
+    // `projectGatedImage`, which drops it — see that function's docblock for why
+    // the two cases are handled differently. This line is NOT an allowlist.
     if ('url' in img)
         return false;
     return true;
 }
+/**
+ * Narrow ONE already-validated gated-image entry to the keys its `status`
+ * permits: a `hidden` entry becomes exactly `{ imageId, status }`; a `visible`
+ * entry is returned unchanged.
+ *
+ * 🔴 THIS IS WHERE THE `hidden` ALLOWLIST ACTUALLY LIVES. `isValidGatedImage`
+ * bans one spelling (`url`); this drops every key that is not `imageId` or
+ * `status`, so `previewUrl` / `src` / `imageUrl` / anything a future host adds
+ * cannot reach a consumer of `IMAGES_RESULT`.
+ *
+ * 🔴 WHY PROJECTION AND NOT REJECTION, for everything except `url`. A `false`
+ * from `isValidGatedImage` fails the WHOLE batch: `isValidImagesResult` returns
+ * false for one bad entry, `handleMessage` drops the entire `IMAGES_RESULT`
+ * before the pending-request lookup, and `useGatedImages().getImages()` then
+ * hangs to its transport timeout rather than rejecting. That failure mode is
+ * already documented in `useGatedImages.test.tsx` — it is what the
+ * `ratingPending` shape had to be admitted to avoid. The host is
+ * `civitai/civitai`, a separate repo on a separate release cadence, so an
+ * allowlist-by-rejection would convert ANY future host-side field addition into
+ * a block-wide hang. Dropping the key delivers the same moderation guarantee
+ * (nothing extra reaches a consumer) and costs a forward-compatible host
+ * nothing.
+ *
+ * `url` stays fatal because it is the one key the contract explicitly forbids on
+ * a `hidden` entry: a host can never legitimately add it, so it carries no
+ * forward-compat risk, and its presence is a live moderation breach worth
+ * surfacing loudly (`console.warn` + a `BLOCK_MESSAGE_REJECTED` report) rather
+ * than silently papering over.
+ *
+ * Identity-preserving: an entry that already satisfies the allowlist is returned
+ * as-is, so the common path allocates nothing.
+ */
+function projectGatedImage(img) {
+    if (!isObject(img))
+        return img;
+    if (img.status !== 'hidden')
+        return img;
+    const keys = Object.keys(img);
+    if (keys.length === 2 && 'imageId' in img && 'status' in img)
+        return img;
+    return { imageId: img.imageId, status: img.status };
+}
 /**
  * Reply to a block-initiated `GET_IMAGES_BY_IDS`. A well-formed reply carries
  * EITHER a `result` ({ images: BlockGatedImage[] }) OR a free-text `error`; one
  * with neither is malformed and dropped. Each image is shape-checked via
  * {@link isValidGatedImage} — a `hidden` entry that carries a `url` DROPS the whole
  * reply (defense in depth against a leaked unclamped url).
+ *
+ * Validation only. The `hidden` ALLOWLIST is applied separately, by
+ * {@link projectInboundPayload} → {@link projectGatedImage}, after this returns
+ * true.
  */
 export function isValidImagesResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1003,7 +1062,7 @@ export function isValidImagesResult(p) {
 export function isValidCollectionFollowResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1047,7 +1106,7 @@ export function isValidCollectionFollowResult(p) {
 export function isValidCreatePostResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1094,7 +1153,7 @@ export function isValidCreatePostResult(p) {
 export function isValidAppStorageGetResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1111,7 +1170,7 @@ export function isValidAppStorageGetResult(p) {
 export function isValidAppStorageSetResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1130,7 +1189,7 @@ export function isValidAppStorageSetResult(p) {
 export function isValidAppStorageDeleteResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1150,7 +1209,7 @@ export function isValidAppStorageDeleteResult(p) {
 export function isValidAppStorageListResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1174,7 +1233,7 @@ export function isValidAppStorageListResult(p) {
 export function isValidAppStorageQuotaResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1221,7 +1280,7 @@ function isValidSharedValue(v) {
 export function isValidSharedListResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1282,7 +1341,7 @@ function isValidSharedItemWire(it) {
 export function isValidSharedGetResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1301,7 +1360,7 @@ export function isValidSharedGetResult(p) {
 export function isValidSharedReportResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1320,7 +1379,7 @@ export function isValidSharedReportResult(p) {
 export function isValidSaveImageResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1338,7 +1397,7 @@ export function isValidSaveImageResult(p) {
 export function isValidSharedCountResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1352,7 +1411,7 @@ export function isValidSharedCountResult(p) {
 export function isValidSharedCountsResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1370,7 +1429,7 @@ export function isValidSharedCountsResult(p) {
 export function isValidSharedAppendResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1387,7 +1446,7 @@ export function isValidSharedAppendResult(p) {
 export function isValidSharedWithdrawResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1435,7 +1494,7 @@ function isValidPickerResourceBase(s) {
 export function isValidCheckpointPickerResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.selected !== undefined) {
         if (!isObject(p.selected))
@@ -1455,7 +1514,7 @@ export function isValidCheckpointPickerResult(p) {
 export function isValidResourcePickerResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.selected !== undefined) {
         const s = p.selected;
@@ -1494,7 +1553,7 @@ export function isValidResourcePickerResult(p) {
 export function isValidUserCheckpointSetResult(p) {
     if (!isObject(p))
         return false;
-    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+    if (!isWireRequestIdShape(p.requestId))
         return false;
     if (p.error !== undefined && typeof p.error !== 'string')
         return false;
@@ -1504,15 +1563,70 @@ export function isValidUserCheckpointSetResult(p) {
         return false;
     return true;
 }
+/**
+ * Narrow an already-VALIDATED inbound payload to the fields a consumer is
+ * allowed to see, immediately before `iframeTransport` hands it to a pending
+ * request or a push listener.
+ *
+ * Validation answers "may this message be delivered at all"; projection answers
+ * "which of its fields may cross". They are deliberately separate steps: a
+ * predicate can only ever say yes/no about the WHOLE reply, so expressing an
+ * allowlist as a predicate makes one unexpected key fatal to every entry in the
+ * batch. See {@link projectGatedImage} for the concrete case and the hang it
+ * avoids.
+ *
+ * 🔴 SCOPE, STATED HONESTLY: `IMAGES_RESULT` is the ONLY type projected today.
+ * Every other type is returned by identity — this is not a general sanitizer and
+ * must not be read as one. Add a case here (and say so in the type's validator
+ * docblock) if another message ever needs one.
+ */
+export function projectInboundPayload(type, payload) {
+    if (type !== 'IMAGES_RESULT')
+        return payload;
+    if (!isObject(payload))
+        return payload;
+    const result = payload.result;
+    if (!isObject(result) || !Array.isArray(result.images))
+        return payload;
+    let changed = false;
+    const images = result.images.map((img) => {
+        const projected = projectGatedImage(img);
+        if (projected !== img)
+            changed = true;
+        return projected;
+    });
+    // Identity when nothing was dropped, so the overwhelmingly common path neither
+    // allocates nor perturbs object identity for anything downstream.
+    if (!changed)
+        return payload;
+    return { ...payload, result: { ...result, images } };
+}
 /**
  * Returns the validator for an inbound message type, or `null` for types
  * that don't carry a payload requiring shape checks (SUSPEND/RESUME).
  *
  * Falsy result from the validator means "drop the message"; `iframeTransport`
  * pairs that with a `console.warn` carrying the type name.
+ *
+ * 🔴 EXHAUSTIVE OVER `ParentToBlockMessage` AT COMPILE TIME. The `default:` arm
+ * binds the switch subject to `never`, so a union member with no `case` above
+ * fails `tsc` with `Type '"NEW_TYPE"' is not assignable to type 'never'`. Adding
+ * a message type to the protocol and forgetting its validator is therefore a
+ * BUILD error, not a silent unvalidated path.
+ *
+ * ⚠️ The gate proves the type is MAPPED, not that it is mapped to the RIGHT
+ * validator, and not that it is mapped to a validator at all rather than to
+ * `null` — `case 'NEW_TYPE': return null;` satisfies it. `validate.test.ts`
+ * covers that residual by asserting a validator (not `null`) for every
+ * payload-carrying type, plus identity for the highest-stakes few.
  */
 export function payloadValidatorFor(type) {
-    switch (type) {
+    // Widened to `string` on the parameter so a JavaScript caller — and a block
+    // running under a NEWER host than it was built against — reaches the
+    // `default:` arm rather than bypassing the lookup. Narrowed here so the switch
+    // has a union subject for the exhaustiveness check to bind.
+    const messageType = type;
+    switch (messageType) {
         case 'BLOCK_INIT':
             return isValidBlockInitPayload;
         case 'TOKEN_REFRESH':
@@ -1552,11 +1666,10 @@ export function payloadValidatorFor(type) {
             return isValidImagesResult;
         case 'COLLECTION_FOLLOW_RESULT':
             return isValidCollectionFollowResult;
-        // 🔴 THIS ENTRY IS NOT COMPILER-ENFORCED — the `default:` arm below returns
-        // `null`, which is a STRUCTURAL PASS. Omitting it would not fail the build
-        // and would not fail typecheck; it would ship an UNVALIDATED path, and
-        // there is a test (`payloadValidatorFor` mapping pin) that exists only
-        // because that failure is otherwise invisible.
+        // 🔴 PRESENCE of this entry IS compiler-enforced (the `never` bind in
+        // `default:`); WHICH validator it names is not. This reply settles a PUBLIC
+        // POST, so the identity is pinned by test as well — see the mapping pin in
+        // `validate.test.ts`.
         case 'CREATE_POST_RESULT':
             return isValidCreatePostResult;
         case 'IMAGE_UPLOAD_RESULT':
@@ -1602,10 +1715,38 @@ export function payloadValidatorFor(type) {
         case 'SUSPEND':
         case 'RESUME':
             return null;
-        default:
-            // Unknown type names get a structural pass; handleMessage's earlier
-            // `isMessage` branches won't match them anyway.
+        default: {
+            // ── COMPILE-TIME TOTALITY GATE ─────────────────────────────────────────
+            // Every `ParentToBlockMessage` member is handled above, so the subject
+            // narrows to `never` here. Add a member to the union without a `case` and
+            // this assignment fails:
+            //   Type '"NEW_TYPE"' is not assignable to type 'never'.
+            // Do NOT "fix" that by widening this binding — the error IS the gate.
+            const exhaustive = messageType;
+            void exhaustive;
+            // ── RUNTIME: a type the union does not declare ─────────────────────────
+            // 🔴 THIS ARM IS A STRUCTURAL PASS, AND THAT IS A DELIBERATE CHOICE
+            // RATHER THAN AN OVERSIGHT — an earlier comment here justified it with
+            // "handleMessage's earlier `isMessage` branches won't match them anyway",
+            // which is true but is only a third of the reason and reads as if the
+            // other paths had been checked. They have been, so state it: a type
+            // outside the union cannot reach `pending.resolve` (`sendRequest`'s
+            // `responseType` is keyed to the union), cannot reach a push listener
+            // (`onMessage`'s `type` is too), and matches none of the three `isMessage`
+            // branches. It is a no-op in `handleMessage` either way, so returning a
+            // rejecting validator would protect nothing and would cost real
+            // forward-compatibility: a host that has shipped a new message type ahead
+            // of this package would make every older block in the fleet emit a
+            // `console.warn` reading "dropping malformed …" (it is not malformed, it
+            // is unrecognised) plus an unbudgeted `BLOCK_MESSAGE_REJECTED` beacon
+            // labelled `other` on every delivery.
+            //
+            // The residual hole this leaves is narrow and worth naming: an UNTYPED
+            // JavaScript consumer that registers `onMessage('SOME_FUTURE_TYPE', …)`
+            // receives that payload unvalidated. Nothing in this package can validate
+            // a type it does not know; such a consumer must validate for itself.
             return null;
+        }
     }
 }
 //# sourceMappingURL=validate.js.map

package/dist/ui/BlockGate.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
-import { hostToRunUrl } from '../internal/directLoad.js';
+import { hostToRunUrl } from '../transport/directLoad.js';
 import { useDirectLoad } from '../hooks/useDirectLoad.js';
 import { Card } from './Card.js';
 import { Stack } from './Stack.js';

package/dist/ui/SettingsForm.d.ts

@@ -30,8 +30,14 @@ export interface SettingsFormProps {
     /** Which slice of fields to render. */
     forScope: SettingScope;
     /**
-     * Initial values keyed by field name. Missing keys fall back to the
-     * manifest field's `default`. Unknown keys are ignored.
+     * Values keyed by field name. Missing keys fall back to the manifest
+     * field's `default`. Unknown keys are ignored.
+     *
+     * LIVE, not mount-only (#396): passing a different object after mount
+     * re-seeds every visible field the user has not yet edited, so values that
+     * arrive from an in-flight fetch land in the form instead of being dropped.
+     * Fields the user HAS edited keep the edit. The name is kept for API
+     * compatibility.
      */
     initialValues: Record<string, unknown>;
     /**

package/dist/ui/SettingsForm.js

@@ -26,7 +26,30 @@ export function isFieldVisible(field, forScope, declaredScopes) {
 }
 export function SettingsForm(props) {
     const visibleFields = useMemo(() => Object.entries(props.manifestSettings).filter(([, def]) => isFieldVisible(def, props.forScope, props.declaredScopes)), [props.manifestSettings, props.forScope, props.declaredScopes]);
-    const [values, setValues] = useState(() => {
+    /**
+     * The seed for the CURRENTLY visible fields: `initialValues` where present,
+     * otherwise the manifest `default`, otherwise `null`.
+     *
+     * 🔴 DERIVED, NOT SEEDED-ONCE STATE (#396). This used to be a `useState` lazy
+     * initializer, which runs exactly once — while `visibleFields` above is a
+     * `useMemo` that recomputes. The two drifted, in two ways that both reached
+     * the user:
+     *
+     *   1. `initialValues` that arrive ASYNCHRONOUSLY (the normal case: `{}`
+     *      while a fetch is in flight, then the stored row) were ignored. The
+     *      form rendered manifest defaults for ever, and Save wrote those
+     *      defaults back OVER the user's stored value.
+     *   2. A `forScope` flip on a mounted form recomputed `visibleFields` to the
+     *      new slice while `values` still held the OLD slice's keys — so the
+     *      viewer-scope form rendered blank inputs and `onSubmit` posted the
+     *      PUBLISHER slice's keys under a viewer-scope save.
+     *
+     * Recomputing instead of seeding closes both, and closes (2) STRUCTURALLY
+     * rather than by remembering to clear: `values` below is built by walking
+     * `seeded`'s keys, so a key outside the current `visibleFields` has no way
+     * into the submitted object at all.
+     */
+    const seeded = useMemo(() => {
         const seed = {};
         for (const [key, def] of visibleFields) {
             if (Object.prototype.hasOwnProperty.call(props.initialValues, key)) {
@@ -40,12 +63,35 @@ export function SettingsForm(props) {
             }
         }
         return seed;
-    });
+    }, [visibleFields, props.initialValues]);
+    /**
+     * The user's own edits, keyed by field. Kept SEPARATE from the seed so that
+     * a later `initialValues`/`forScope` change re-seeds without discarding what
+     * the user typed, and so that an edit can never outlive its field's
+     * visibility (see `values`).
+     */
+    const [edits, setEdits] = useState({});
+    /**
+     * Seed overlaid with edits — the rendered AND submitted value set.
+     *
+     * 🔴 The iteration order is load-bearing: this walks `seeded`'s keys, NOT
+     * `edits`'. An edit to a field that is no longer visible (a `forScope` flip,
+     * or a manifest change) is therefore simply not present here, so it cannot
+     * be rendered and cannot be submitted. Spreading `edits` in wholesale would
+     * reintroduce exactly the cross-scope leak this fix exists to close.
+     */
+    const values = useMemo(() => {
+        const merged = {};
+        for (const key of Object.keys(seeded)) {
+            merged[key] = Object.prototype.hasOwnProperty.call(edits, key) ? edits[key] : seeded[key];
+        }
+        return merged;
+    }, [seeded, edits]);
     const [errors, setErrors] = useState({});
     const [submitting, setSubmitting] = useState(false);
     const [submitError, setSubmitError] = useState(null);
     const setFieldValue = useCallback((key, value) => {
-        setValues((prev) => ({ ...prev, [key]: value }));
+        setEdits((prev) => ({ ...prev, [key]: value }));
         setErrors((prev) => {
             if (!prev[key])
                 return prev;