@civitai/blocks-react 0.56.0 → 0.57.0

package/dist/transport/requestId.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The two — and only two — questions anyone asks about a `requestId`.
+ *
+ * Before #395 this file did not exist and both questions were open-coded at 64
+ * sites in five different spellings. Measured on `e993cf0`:
+ *
+ * ```
+ * 33 x  p.requestId !== undefined && typeof p.requestId !== 'string'   validate.ts
+ *  1 x  !isNonEmptyString(p.requestId)                                 validate.ts
+ * 26 x  typeof requestId !== 'string'                                  liveHost/mockHost
+ *  2 x  typeof <expr>.requestId === 'string'                           iframeTransport.ts
+ *  2 x  ...(requestId ? { requestId } : {})                            liveHost/mockHost
+ * ```
+ *
+ * (The issue's "~45 sites" undercounts: it was written before #378/#416 moved
+ * nine modules out of `internal/`, and it counted two TYPE ANNOTATIONS as if
+ * they were predicates. The 64 above are runtime decisions only.)
+ *
+ * ⚠️ NOT ROUTED THROUGH HERE, DELIBERATELY: the 37 `requestId ?? ''`
+ * expressions in `liveHost.ts`. They are nullish DEFAULTS on an EMIT path, not
+ * routability decisions — nobody branches on the result; it is written straight
+ * onto the wire. **MEASURED, not assumed: none of the 37 sits downstream of a
+ * routability guard** (checked by walking back to each one's enclosing `case`),
+ * so `liveHost` answers an id-less request with an unroutable `requestId: ''`
+ * reply where `mockHost` declines to answer at all. Both end the same way — the
+ * block cannot correlate either, and the request times out — and the arm is
+ * unreachable in practice, because only `sendRequest` produces a request that
+ * gets a reply and it always assigns an id (`nextRequestId()`); every `case`
+ * reachable by the id-less `sendMessage` path returns before replying.
+ *
+ * Unifying those 37 onto an early `return` would be a 37-site behaviour change
+ * on a dev-harness emit path, which is out of scope for a consolidation; they
+ * are instead an ASSERTED COUNT in the guard, so a 38th cannot appear without
+ * someone deciding. Filed as the follow-up in #395's PR, not fixed here.
+ *
+ * ## The two questions are NOT the same question, and collapsing them is a bug
+ *
+ * - **`isRoutableRequestId`** — "can this value correlate a reply to an entry in
+ *   the transport's `pending` table?" A **non-empty string**. This is the
+ *   decision every routing site makes.
+ * - **`isWireRequestIdShape`** — "is the `requestId` field on this inbound
+ *   payload well-formed?" **Absent, or any string — including `''`.** This is a
+ *   trust-boundary *shape* check, and it is DELIBERATELY LOOSER than routability.
+ *
+ * 🔴 DO NOT "SIMPLIFY" THE VALIDATORS ONTO `isRoutableRequestId`. A validator
+ * that returns `false` DROPS the whole message at the trust boundary, with
+ * nothing but a `console.warn`. `isValidTokenRefreshResponse`'s docblock spells
+ * out what that costs: a `TOKEN_REFRESH_RESPONSE` that cannot correlate still
+ * carries a token that `handleMessage` applies to the snapshot regardless of
+ * correlation, so dropping it converts a degraded path into a broken one. The
+ * looseness is the back-compat story for a new SDK against a pre-v2 host, not an
+ * oversight. Routability is decided LATER, by `isRoutableRequestId`, and an
+ * unroutable-but-well-formed reply is delivered to push listeners rather than
+ * discarded.
+ *
+ * The relationship is a strict containment and it is the whole contract:
+ *
+ * ```
+ * isRoutableRequestId(v)  =>  isWireRequestIdShape(v)      (always)
+ * isWireRequestIdShape(v) =/> isRoutableRequestId(v)       (v === undefined, v === '')
+ * ```
+ *
+ * ## `null` is not routable, and never was
+ *
+ * #395 was filed on the theory that the spellings disagreed about
+ * `requestId: null`. They do not — every one of the 64 sites above rejects
+ * `null` (`typeof null === 'object'`; `null` is falsy; `null ?? ''` is `''`).
+ * The two spellings the issue counted as differing on `null` were TYPE
+ * ANNOTATIONS on the *payload* (`{ requestId?: unknown } | undefined` vs
+ * `... | null | undefined`), not runtime predicates, and both sites runtime-guard
+ * the payload anyway. `null` is therefore pinned here as the behaviour that
+ * already held, not chosen: see `requestId.test.ts`.
+ *
+ * What the spellings DID disagree about is the EMPTY STRING — see
+ * `isRoutableRequestId` below.
+ *
+ * Enforced by `tests/guards/blocks-react-requestid-routability.test.mjs`, which
+ * fails when a routability or wire-shape decision is open-coded anywhere in
+ * `packages/civitai-blocks-react/src` outside this module.
+ */
+/**
+ * Can this value correlate a reply to a pending request?
+ *
+ * A **non-empty string**. Nothing else — not `null`, not `undefined`, not a
+ * number a buggy host echoed, not `''`.
+ *
+ * 🔴 WHY NON-EMPTY, WHEN THREE OF THE FOUR OLD SPELLINGS ACCEPTED `''`.
+ * `nextRequestId()` (transport.ts) returns `` `${base36}-${counter}` ``, which is
+ * never empty, so `''` can never be a key in the transport's `pending` table:
+ * `pending.get('')` was already a guaranteed miss at both routing sites. Making
+ * the emptiness explicit costs nothing there and makes this predicate agree with
+ * `isValidImageScanResolved`, the one site that already required non-empty. The
+ * sites where it does move behaviour — the dev/mock hosts, which used to answer
+ * a `requestId: ''` request with an equally unroutable `requestId: ''` reply, and
+ * now decline to answer at all — are enumerated and pinned in `requestId.test.ts`.
+ */
+export declare function isRoutableRequestId(v: unknown): v is string;
+/**
+ * Is the OPTIONAL `requestId` field of an inbound payload well-formed?
+ *
+ * `true` when the field is absent (`undefined`) or is any string, `''` included.
+ * `false` for every other type — a non-string cannot masquerade as a correlation
+ * id, which is the only thing these validators need to rule out.
+ *
+ * Pass the FIELD, not the payload: `isWireRequestIdShape(p.requestId)`.
+ *
+ * Exactly equivalent to the 33 open-coded copies it replaced —
+ * `!(v === undefined || typeof v === 'string')` is `v !== undefined &&
+ * typeof v !== 'string'` — so no validator's behaviour moved. Read the module
+ * docblock before tightening it.
+ */
+export declare function isWireRequestIdShape(v: unknown): boolean;
+//# sourceMappingURL=requestId.d.ts.map

package/dist/transport/requestId.js

@@ -0,0 +1,117 @@
+/**
+ * The two — and only two — questions anyone asks about a `requestId`.
+ *
+ * Before #395 this file did not exist and both questions were open-coded at 64
+ * sites in five different spellings. Measured on `e993cf0`:
+ *
+ * ```
+ * 33 x  p.requestId !== undefined && typeof p.requestId !== 'string'   validate.ts
+ *  1 x  !isNonEmptyString(p.requestId)                                 validate.ts
+ * 26 x  typeof requestId !== 'string'                                  liveHost/mockHost
+ *  2 x  typeof <expr>.requestId === 'string'                           iframeTransport.ts
+ *  2 x  ...(requestId ? { requestId } : {})                            liveHost/mockHost
+ * ```
+ *
+ * (The issue's "~45 sites" undercounts: it was written before #378/#416 moved
+ * nine modules out of `internal/`, and it counted two TYPE ANNOTATIONS as if
+ * they were predicates. The 64 above are runtime decisions only.)
+ *
+ * ⚠️ NOT ROUTED THROUGH HERE, DELIBERATELY: the 37 `requestId ?? ''`
+ * expressions in `liveHost.ts`. They are nullish DEFAULTS on an EMIT path, not
+ * routability decisions — nobody branches on the result; it is written straight
+ * onto the wire. **MEASURED, not assumed: none of the 37 sits downstream of a
+ * routability guard** (checked by walking back to each one's enclosing `case`),
+ * so `liveHost` answers an id-less request with an unroutable `requestId: ''`
+ * reply where `mockHost` declines to answer at all. Both end the same way — the
+ * block cannot correlate either, and the request times out — and the arm is
+ * unreachable in practice, because only `sendRequest` produces a request that
+ * gets a reply and it always assigns an id (`nextRequestId()`); every `case`
+ * reachable by the id-less `sendMessage` path returns before replying.
+ *
+ * Unifying those 37 onto an early `return` would be a 37-site behaviour change
+ * on a dev-harness emit path, which is out of scope for a consolidation; they
+ * are instead an ASSERTED COUNT in the guard, so a 38th cannot appear without
+ * someone deciding. Filed as the follow-up in #395's PR, not fixed here.
+ *
+ * ## The two questions are NOT the same question, and collapsing them is a bug
+ *
+ * - **`isRoutableRequestId`** — "can this value correlate a reply to an entry in
+ *   the transport's `pending` table?" A **non-empty string**. This is the
+ *   decision every routing site makes.
+ * - **`isWireRequestIdShape`** — "is the `requestId` field on this inbound
+ *   payload well-formed?" **Absent, or any string — including `''`.** This is a
+ *   trust-boundary *shape* check, and it is DELIBERATELY LOOSER than routability.
+ *
+ * 🔴 DO NOT "SIMPLIFY" THE VALIDATORS ONTO `isRoutableRequestId`. A validator
+ * that returns `false` DROPS the whole message at the trust boundary, with
+ * nothing but a `console.warn`. `isValidTokenRefreshResponse`'s docblock spells
+ * out what that costs: a `TOKEN_REFRESH_RESPONSE` that cannot correlate still
+ * carries a token that `handleMessage` applies to the snapshot regardless of
+ * correlation, so dropping it converts a degraded path into a broken one. The
+ * looseness is the back-compat story for a new SDK against a pre-v2 host, not an
+ * oversight. Routability is decided LATER, by `isRoutableRequestId`, and an
+ * unroutable-but-well-formed reply is delivered to push listeners rather than
+ * discarded.
+ *
+ * The relationship is a strict containment and it is the whole contract:
+ *
+ * ```
+ * isRoutableRequestId(v)  =>  isWireRequestIdShape(v)      (always)
+ * isWireRequestIdShape(v) =/> isRoutableRequestId(v)       (v === undefined, v === '')
+ * ```
+ *
+ * ## `null` is not routable, and never was
+ *
+ * #395 was filed on the theory that the spellings disagreed about
+ * `requestId: null`. They do not — every one of the 64 sites above rejects
+ * `null` (`typeof null === 'object'`; `null` is falsy; `null ?? ''` is `''`).
+ * The two spellings the issue counted as differing on `null` were TYPE
+ * ANNOTATIONS on the *payload* (`{ requestId?: unknown } | undefined` vs
+ * `... | null | undefined`), not runtime predicates, and both sites runtime-guard
+ * the payload anyway. `null` is therefore pinned here as the behaviour that
+ * already held, not chosen: see `requestId.test.ts`.
+ *
+ * What the spellings DID disagree about is the EMPTY STRING — see
+ * `isRoutableRequestId` below.
+ *
+ * Enforced by `tests/guards/blocks-react-requestid-routability.test.mjs`, which
+ * fails when a routability or wire-shape decision is open-coded anywhere in
+ * `packages/civitai-blocks-react/src` outside this module.
+ */
+/**
+ * Can this value correlate a reply to a pending request?
+ *
+ * A **non-empty string**. Nothing else — not `null`, not `undefined`, not a
+ * number a buggy host echoed, not `''`.
+ *
+ * 🔴 WHY NON-EMPTY, WHEN THREE OF THE FOUR OLD SPELLINGS ACCEPTED `''`.
+ * `nextRequestId()` (transport.ts) returns `` `${base36}-${counter}` ``, which is
+ * never empty, so `''` can never be a key in the transport's `pending` table:
+ * `pending.get('')` was already a guaranteed miss at both routing sites. Making
+ * the emptiness explicit costs nothing there and makes this predicate agree with
+ * `isValidImageScanResolved`, the one site that already required non-empty. The
+ * sites where it does move behaviour — the dev/mock hosts, which used to answer
+ * a `requestId: ''` request with an equally unroutable `requestId: ''` reply, and
+ * now decline to answer at all — are enumerated and pinned in `requestId.test.ts`.
+ */
+export function isRoutableRequestId(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Is the OPTIONAL `requestId` field of an inbound payload well-formed?
+ *
+ * `true` when the field is absent (`undefined`) or is any string, `''` included.
+ * `false` for every other type — a non-string cannot masquerade as a correlation
+ * id, which is the only thing these validators need to rule out.
+ *
+ * Pass the FIELD, not the payload: `isWireRequestIdShape(p.requestId)`.
+ *
+ * Exactly equivalent to the 33 open-coded copies it replaced —
+ * `!(v === undefined || typeof v === 'string')` is `v !== undefined &&
+ * typeof v !== 'string'` — so no validator's behaviour moved. Read the module
+ * docblock before tightening it.
+ */
+export function isWireRequestIdShape(v) {
+    return v === undefined || typeof v === 'string';
+}
+//# sourceMappingURL=requestId.js.map

package/dist/{internal → transport}/validate.d.ts

@@ -325,6 +325,10 @@ export declare function isValidPublishResult(p: unknown): boolean;
  * 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 declare function isValidImagesResult(p: unknown): boolean;
 /**
@@ -458,12 +462,42 @@ export declare function isValidResourcePickerResult(p: unknown): boolean;
  * (module header) — mirrors `isValidSharedUpdateResult`.
  */
 export declare function isValidUserCheckpointSetResult(p: unknown): boolean;
+/**
+ * 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 declare function projectInboundPayload(type: string, payload: unknown): unknown;
 /**
  * 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 declare function payloadValidatorFor(type: string): ((payload: unknown) => boolean) | null;
 //# sourceMappingURL=validate.d.ts.map