@storystick/preview 0.0.0-stage → 0.2.0-rc.0

package/dist/runtime/emit-runtime-error.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ADR-134 §D4 + §9.T6 — SDK-side emitter for the iframe→Studio
+ * `storystick.preview.runtime-error` envelope.
+ *
+ * One-way iframe→Studio channel for D-category post-auth runtime
+ * failures (Layer1 cache unavailable, schema delivery failed, code
+ * version unknown — see boot.ts and schema-store.ts). Studio renders
+ * `severity:'warning'` as an inline band above the iframe (auto-
+ * dismissed) and `severity:'error'` as a full PreviewStageError panel
+ * takeover. The envelope rides the same validator as the auth
+ * envelopes ; no trust elevation.
+ *
+ * Two security properties enforced here :
+ *
+ *  1. **`runtime.*` prefix gate (§9.T6 defense in depth).** The helper
+ *     THROWS synchronously when `code` does not start with `runtime.`.
+ *     A customer-customized SDK shim that accidentally sends a
+ *     non-runtime code surfaces as a visible call-site error in the
+ *     customer's dev console instead of a silent drop. The transport
+ *     validator independently rejects unprefixed codes (defense in
+ *     depth — both layers needed).
+ *
+ *  2. **identity gate (§D4 chicken-and-egg).** Without a locked
+ *     `parentOrigin`, the envelope cannot target a sane recipient —
+ *     the caller has no proof anyone trusted is listening. We
+ *     short-circuit (no-op) under this condition. The chicken-and-egg
+ *     edge case is D4 itself : `identity_unresolved` cannot signal via
+ *     this channel and falls back to Studio's `T_handshake` deadline
+ *     observation ("iframe loaded but SDK never spoke").
+ *
+ * Pure — does not touch storage, network, or DOM. Only side effect is
+ * the `window.parent.postMessage` call on the happy path.
+ */
+import type { RuntimeErrorPayload } from '@storystick/transport-allowlist';
+export interface EmitRuntimeErrorOpts {
+    /** Must start with `runtime.` — emitter throws otherwise. */
+    code: string;
+    message: string;
+    severity: RuntimeErrorPayload['severity'];
+    retryable?: boolean;
+    retryNotBefore?: number;
+    persistence?: RuntimeErrorPayload['persistence'];
+}
+/**
+ * Build + dispatch a `storystick.preview.runtime-error` envelope to
+ * the locked parent origin. No-op when identity has not resolved yet
+ * (see §D4 chicken-and-egg). Throws synchronously on unprefixed `code`.
+ */
+export declare function emitRuntimeError(opts: EmitRuntimeErrorOpts): void;
+/** Clear one runtime diagnostic after the underlying authority recovered. */
+export declare function emitRuntimeRecovered(code: string): void;

package/dist/runtime/emit-runtime-error.js

@@ -0,0 +1,64 @@
+/**
+ * ADR-134 §D4 + §9.T6 — SDK-side emitter for the iframe→Studio
+ * `storystick.preview.runtime-error` envelope.
+ *
+ * One-way iframe→Studio channel for D-category post-auth runtime
+ * failures (Layer1 cache unavailable, schema delivery failed, code
+ * version unknown — see boot.ts and schema-store.ts). Studio renders
+ * `severity:'warning'` as an inline band above the iframe (auto-
+ * dismissed) and `severity:'error'` as a full PreviewStageError panel
+ * takeover. The envelope rides the same validator as the auth
+ * envelopes ; no trust elevation.
+ *
+ * Two security properties enforced here :
+ *
+ *  1. **`runtime.*` prefix gate (§9.T6 defense in depth).** The helper
+ *     THROWS synchronously when `code` does not start with `runtime.`.
+ *     A customer-customized SDK shim that accidentally sends a
+ *     non-runtime code surfaces as a visible call-site error in the
+ *     customer's dev console instead of a silent drop. The transport
+ *     validator independently rejects unprefixed codes (defense in
+ *     depth — both layers needed).
+ *
+ *  2. **identity gate (§D4 chicken-and-egg).** Without a locked
+ *     `parentOrigin`, the envelope cannot target a sane recipient —
+ *     the caller has no proof anyone trusted is listening. We
+ *     short-circuit (no-op) under this condition. The chicken-and-egg
+ *     edge case is D4 itself : `identity_unresolved` cannot signal via
+ *     this channel and falls back to Studio's `T_handshake` deadline
+ *     observation ("iframe loaded but SDK never spoke").
+ *
+ * Pure — does not touch storage, network, or DOM. Only side effect is
+ * the `window.parent.postMessage` call on the happy path.
+ */
+import { previewRuntime } from './store.js';
+import { dispatchRuntimeError, dispatchRuntimeRecovered, } from './runtime-error-dispatch.js';
+/**
+ * Build + dispatch a `storystick.preview.runtime-error` envelope to
+ * the locked parent origin. No-op when identity has not resolved yet
+ * (see §D4 chicken-and-egg). Throws synchronously on unprefixed `code`.
+ */
+export function emitRuntimeError(opts) {
+    const state = previewRuntime.getState();
+    const identity = state.identity;
+    dispatchRuntimeError({
+        ...opts,
+        retryable: opts.retryable ?? false,
+        persistence: opts.persistence ??
+            (opts.severity === 'warning' ? 'transient' : 'until-recovered'),
+    }, {
+        parentOrigin: identity?.parentOrigin ?? null,
+        sessionId: state.sessionId,
+        projectId: identity?.projectId ?? null,
+    });
+}
+/** Clear one runtime diagnostic after the underlying authority recovered. */
+export function emitRuntimeRecovered(code) {
+    const state = previewRuntime.getState();
+    const identity = state.identity;
+    dispatchRuntimeRecovered(code, {
+        parentOrigin: identity?.parentOrigin ?? null,
+        sessionId: state.sessionId,
+        projectId: identity?.projectId ?? null,
+    });
+}

package/dist/runtime/field-proxy.d.ts

@@ -0,0 +1,112 @@
+/**
+ * ADR-125 D3 — query-builder field Proxy + (path, value, docId) model.
+ *
+ * The parent overlay layer (PR1b) resolves a click to a field path +
+ * owning document. To do that **with zero developer annotation**
+ * (ADR-125 §6 rejects mandatory annotation / composite attrs) the SDK
+ * must learn, per rendered document, which canonical field path produced
+ * which value — and, crucially, propagate the *originating* docId across
+ * resolved references so a click on an author-bio fragment on an article
+ * page resolves to the AUTHOR document, not the article (ADR-125 §1.2 #3).
+ *
+ * `wrapWithProxy(data, docId, basePath)` returns a recursive Proxy over a
+ * query-builder result. Two views of the same structure are available:
+ *
+ *   1. **Lazy / precise** — the get-trap records every accessed leaf
+ *      `{ path, value, docId }` into the module accumulator. This is the
+ *      literal "Proxy records access" of ADR-125 D3 and is exactly the
+ *      set the customer's component touched (sharp for client-rendered
+ *      customers).
+ *   2. **Eager / structural** — `collectFieldModel()` walks registered
+ *      roots and enumerates every leaf. Conserved deliberately as the
+ *      field inventory primitive for the annotation model; it does not
+ *      mutate customer DOM.
+ *
+ * docId propagation (ADR-125 D3, reuse-don't-reinvent): a resolved
+ * reference materialises client-side as `QueryResult.resolved[field]` —
+ * a child `QueryResult` whose `documentId` IS the walker's `toTargetId`
+ * for that ref (the Convex `_refExtractors` server walker already
+ * populated it; we read it, we do not re-derive a ref graph client-side).
+ * Crossing into `.resolved[field]` opens a NEW scope: child docId =
+ * `child.documentId`, path RESET to `''` (canonical paths are relative
+ * to the nearest `data-ss-doc`, ADR-125 D2).
+ *
+ * Canonical path grammar = ADR-068 / `_fromFieldGrammar` walker-canonical
+ * (the SAME grammar `data-field-path` / `refs.fromField` use, so the
+ * arrival service resolves Proxy-recorded paths byte-for-byte): segments
+ * joined by `.`, array hops `[i]`, groups FLATTENED (no group marker —
+ * natural object recursion already yields `hero.title`), the `QueryResult`
+ * `.fields` container hop STRIPPED (content root is path `''`).
+ *
+ * Production posture (ADR-125 D3 / ADR-031): `@storystick/preview` is a
+ * `private` package, dynamic-imported only by preview-aware adapters and
+ * never bundled into a production customer app. Belt-and-braces, every
+ * entry point is also gated on `isFieldTrackingActive()` (embedded iframe
+ * or explicitly activated standalone preview, non-SSR) so even if reached
+ * from an ordinary page it is a referential no-op — wrap
+ * returns its argument by reference, zero allocation, zero traps. Lane G
+ * asserts this explicitly.
+ */
+/** A recorded leaf — `path` is walker-canonical, relative to `docId`'s
+ *  `data-ss-doc` scope. `docId` is the originating document (propagated
+ *  across resolved refs); `null` when the root carried no documentId. */
+export interface TrackedField {
+    path: string;
+    value: unknown;
+    docId: string | null;
+}
+export declare function __setFieldTrackingForcedForTests(v: boolean | null): void;
+export declare function isFieldTrackingActive(): boolean;
+export interface RegisteredRoot {
+    data: unknown;
+    docId: string | null;
+    basePath: string;
+}
+/**
+ * Wrap a query-builder result. Returns `data` unchanged (by reference,
+ * zero allocation) when tracking is inactive or `data` is a primitive.
+ * Registers the root for the eager `collectFieldModel()` walk and
+ * returns a recursive get-trap Proxy for the lazy accessed-leaf path.
+ *
+ * `docId` scopes recorded paths; pass the document's `documentId` (or
+ * omit — `collectFieldModel` re-derives it when the root is itself a
+ * `QueryResult`). `basePath` prefixes recorded paths (a sliceZone item
+ * wrap passes e.g. `sections[2]`); defaults to the content root `''`.
+ */
+export declare function wrapWithProxy<T>(data: T, docId?: string | null, basePath?: string): T;
+/**
+ * Walk every registered root and return all canonical leaves
+ * `{ path, value, docId }`, deduped + bounded. RSC-safe: does not depend
+ * on any get-trap having fired. Resolved-ref boundaries re-scope exactly
+ * like the lazy path (docId = child `documentId`, path reset).
+ */
+export declare function collectFieldModel(): TrackedField[];
+/**
+ * ADR-126 — pure extraction of the eager walk. No module singleton, no
+ * `window`: callable with any explicit `RegisteredRoot[]`. Behaviour for
+ * the module `roots` is byte-identical to the prior `collectFieldModel`
+ * (a strict no-behaviour-change extraction — pinned by a parity test).
+ */
+export declare function collectFieldModelFromRoots(rootsList: readonly RegisteredRoot[]): TrackedField[];
+/** ADR-126 — drop the whole island snapshot. It reflects ONE render;
+ *  callers replace it wholesale so a doc removed from the rendered
+ *  context on an RSC refresh cannot linger and
+ *  re-introduce the non-rendered-doc false-positive class γ′ exists to
+ *  kill (cross-model /review R1, codex #2). Also called by
+ *  `clearTrackedFields()` on the render-mode epoch bump. */
+export declare function clearIslandRoots(): void;
+export declare function registerIslandRoots(entries: readonly unknown[]): void;
+/** Accessed leaves (lazy path). The matcher prefers `collectFieldModel`
+ *  (RSC-safe) but this stays for client-render precision + tests. */
+export declare function getTrackedFields(): TrackedField[];
+/**
+ * Hard reset — clears the accessed set AND every registered root.
+ * NOT called per-publish (scope-keyed `registerRoot` already bounds
+ * `roots` and keeps it current; a per-publish clear would race the
+ * customer render that registers roots). It is the test reset and the
+ * teardown hook a future generation-scoped reset would call if the
+ * model ever needs hard isolation across a doc swap (today scope-keying
+ * makes the swap self-correct: the new doc replaces its scope entry,
+ * cross-model /review P1 fix).
+ */
+export declare function clearTrackedFields(): void;