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

package/dist/runtime/field-proxy.js

@@ -0,0 +1,471 @@
+import { isPreviewBrowserContext } from '../identity/browser-context.js';
+// ─────────────────────────────────────────────
+// Activation gate (production zero-overhead — ADR-125 D3, Lane G)
+// ─────────────────────────────────────────────
+/**
+ * Field tracking is active inside the preview iframe or on a top-level page
+ * carrying the explicit scrubbed `_ss_session` selector. In a
+ * production customer app the package isn't even loaded; this is the
+ * belt-and-braces second line so `wrapWithProxy` is a referential
+ * identity no-op everywhere else. Overridable for tests.
+ */
+let trackingForced = null;
+export function __setFieldTrackingForcedForTests(v) {
+    trackingForced = v;
+}
+export function isFieldTrackingActive() {
+    if (trackingForced !== null)
+        return trackingForced;
+    return isPreviewBrowserContext();
+}
+// ─────────────────────────────────────────────
+// Module model — accessed leaves + registered roots
+// ─────────────────────────────────────────────
+/** Deduped accessed-leaf set (lazy path). Keyed `${docId}\x00${path}` so
+ *  the same path under two docs (cross-doc) is kept distinct and a
+ *  re-access overwrites rather than unbounded-grows. */
+const accessed = new Map();
+/**
+ * Roots registered by `wrapWithProxy`, keyed by `(docId, basePath)` —
+ * the LATEST `data` for a given scope REPLACES the prior one. This is
+ * the load-bearing leak fix (cross-model /review P1, Claude + Codex):
+ * `useStorystickQuery` produces a fresh `QueryResult` object on every
+ * Convex content revision, so an identity-keyed append-only list grows
+ * unbounded for the iframe's lifetime — memory leak AND, once the
+ * `COLLECT_MAX_LEAVES` cap is hit by stale earlier roots, the CURRENT
+ * doc's leaves stop being emitted → field overlays freeze/vanish
+ * mid-edit-session (the exact "feels broken" the ADR exists to
+ * prevent). Keying by scope bounds `roots` to the small, stable set of
+ * distinct (docId, basePath) scopes on the page and always reflects
+ * latest content. `MAX_ROOTS` is a hard belt-and-braces cap (a
+ * pathological page with thousands of distinct cross-doc scopes evicts
+ * oldest-first rather than growing without bound). `clearTrackedFields`
+ * is the per-generation / test reset, NOT a per-publish call (the
+ * matcher does NOT clear each pass — scope-keying makes that
+ * unnecessary and a per-publish clear would race the customer render
+ * that registers roots). */
+const MAX_ROOTS = 256;
+const roots = [];
+/**
+ * ADR-126 — roots sourced from the RSC render-path field-model island
+ * (`<script data-ss-model>` emitted server-side by `@storystick/react`'s
+ * `<SliceZone>`). Kept in a SEPARATE list from the Proxy `roots`, NOT
+ * merged into it, because both sources legitimately register the same
+ * `(docId, '')` scope on a hybrid page (RSC shell + client islands): a
+ * single scope-keyed list would let the lazy Proxy subset REPLACE the
+ * full server-resolved island root (or vice versa) — codex outside-voice
+ * #7, "poorer must not replace richer". `collectFieldModel()` walks the
+ * UNION (`roots` ∪ `islandRoots`); the per-leaf `out` Map dedupes
+ * identical leaves, so a leaf present in EITHER source survives and no
+ * source can erase another's coverage. Same `MAX_ROOTS` discipline. */
+const islandRoots = [];
+/** Proxy identity cache — same target ⇒ same Proxy, so wrapping a
+ *  reference-stable object (slice-zone hands the same `hydrated` ref
+ *  when nothing to hydrate) does not break `React.memo`. */
+const proxyCache = new WeakMap();
+function leafKey(docId, path) {
+    return `${docId ?? ''}\x00${path}`;
+}
+function recordLeaf(path, value, docId) {
+    // Only primitives are leaves; `path === ''` would be a root primitive
+    // (not a field) — never record it.
+    if (path === '')
+        return;
+    accessed.set(leafKey(docId, path), { path, value, docId });
+}
+// ─────────────────────────────────────────────
+// Shape predicates
+// ─────────────────────────────────────────────
+function isPlainPrimitive(v) {
+    return (v === null ||
+        v === undefined ||
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean');
+}
+/** A `QueryResult` document scope: `{ documentId, fields, ... }`. The
+ *  presence of a string `documentId` is the discriminator (mirrors
+ *  `@storystick/client` `QueryResult`). */
+function isQueryResult(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        typeof v.documentId === 'string' &&
+        v.documentId.length > 0);
+}
+/** Non-content `QueryResult` metadata keys — returned raw, never a
+ *  recordable content path, never recursed as content. `fields` and
+ *  `resolved` are handled specially (not here). */
+const QUERY_RESULT_META = new Set([
+    'documentId',
+    'storyType',
+    'snapshotId',
+    'publishedAt',
+    'resolvedPathname',
+    'slug',
+    'isRoutable',
+    '_zoneMappings',
+]);
+// ─────────────────────────────────────────────
+// Path grammar (ADR-068 walker-canonical)
+// ─────────────────────────────────────────────
+function joinKey(base, key) {
+    return base === '' ? key : `${base}.${key}`;
+}
+function joinIndex(base, index) {
+    return `${base}[${index}]`;
+}
+// ─────────────────────────────────────────────
+// Recursive wrap
+// ─────────────────────────────────────────────
+const MAX_DEPTH = 16;
+/**
+ * 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 function wrapWithProxy(data, docId = null, basePath = '') {
+    if (!isFieldTrackingActive())
+        return data;
+    if (data === null || typeof data !== 'object')
+        return data;
+    // Register the root once per (identity, docId, basePath) so the eager
+    // walk has it even when no get-trap ever fires (RSC).
+    registerRoot(data, docId, basePath);
+    return wrapNode(data, docId, basePath, 0);
+}
+function registerRoot(data, docId, basePath) {
+    for (const r of roots) {
+        if (r.docId === docId && r.basePath === basePath) {
+            // Same scope re-registered (new content revision → new object):
+            // REPLACE the data in place. No append → no unbounded growth,
+            // model always reflects latest content. Identity-equal is a
+            // no-op (the common stable-render case).
+            r.data = data;
+            return;
+        }
+    }
+    roots.push({ data, docId, basePath });
+    // Hard cap (pathological many-distinct-scope page) — evict oldest.
+    if (roots.length > MAX_ROOTS)
+        roots.shift();
+}
+/**
+ * Wrap one node. Objects/arrays return a recursive Proxy; primitives are
+ * returned raw (the parent's get-trap recorded them). A `QueryResult`
+ * boundary re-scopes: `.fields` stays in-doc with the content path,
+ * `.resolved[field]` opens the child doc scope (docId = child
+ * `documentId`, path reset), metadata keys pass through raw.
+ */
+function wrapNode(node, docId, path, depth) {
+    if (node === null || typeof node !== 'object')
+        return node;
+    if (depth >= MAX_DEPTH)
+        return node;
+    // Identity cache — same target+scope ⇒ same Proxy (memo-stable).
+    const cacheKey = `${docId ?? ''}\x00${path}\x00${depth >= MAX_DEPTH ? 'L' : ''}`;
+    let perTarget = proxyCache.get(node);
+    if (perTarget) {
+        const hit = perTarget.get(cacheKey);
+        if (hit !== undefined)
+            return hit;
+    }
+    else {
+        perTarget = new Map();
+        proxyCache.set(node, perTarget);
+    }
+    const isQR = isQueryResult(node);
+    const isArr = Array.isArray(node);
+    const proxy = new Proxy(node, {
+        get(target, prop, receiver) {
+            const raw = Reflect.get(target, prop, receiver);
+            if (typeof prop === 'symbol')
+                return raw;
+            if (typeof raw === 'function')
+                return raw;
+            // ── QueryResult boundary ──────────────────────────────
+            if (isQR) {
+                const childDocId = target.documentId;
+                if (prop === 'fields') {
+                    // Content root of THIS doc — path stays, docId becomes this
+                    // doc's id (the root may have been registered with a null
+                    // docId; the QueryResult is authoritative).
+                    return wrapNode(raw, childDocId, path, depth + 1);
+                }
+                if (prop === 'resolved') {
+                    // The resolved map itself is a traversal node; each key is a
+                    // resolved-ref boundary handled one level down.
+                    return wrapResolvedMap(raw, depth + 1);
+                }
+                if (QUERY_RESULT_META.has(prop))
+                    return raw;
+                // Any other key on a QueryResult: treat as content under the
+                // doc scope (defensive — schemas evolve).
+                return descend(raw, childDocId, joinKey(path, prop), depth);
+            }
+            // ── Array hop ─────────────────────────────────────────
+            if (isArr) {
+                const idx = typeof prop === 'string' ? Number(prop) : Number.NaN;
+                if (Number.isInteger(idx) && idx >= 0) {
+                    return descend(raw, docId, joinIndex(path, idx), depth);
+                }
+                return raw; // length, iterator helpers, etc.
+            }
+            // ── Plain content object ──────────────────────────────
+            return descend(raw, docId, joinKey(path, prop), depth);
+        },
+    });
+    perTarget.set(cacheKey, proxy);
+    return proxy;
+}
+/** Resolve one property value: record if primitive, recurse if not. */
+function descend(value, docId, childPath, depth) {
+    if (isPlainPrimitive(value)) {
+        recordLeaf(childPath, value, docId);
+        return value;
+    }
+    return wrapNode(value, docId, childPath, depth + 1);
+}
+/**
+ * The `.resolved` map. Each key is a resolved-ref boundary: the value is
+ * a child `QueryResult` (scalar ref / `.resolve()`) or an array of them
+ * (`.resolveSlices()` / `reference[]`). Crossing it opens the child doc
+ * scope with the path RESET — the child's fields are canonical relative
+ * to ITS own `data-ss-doc` (ADR-125 D2).
+ */
+function wrapResolvedMap(map, depth) {
+    if (map === null || typeof map !== 'object')
+        return map;
+    if (depth >= MAX_DEPTH)
+        return map;
+    return new Proxy(map, {
+        get(target, prop, receiver) {
+            const raw = Reflect.get(target, prop, receiver);
+            if (typeof prop === 'symbol' || typeof raw === 'function')
+                return raw;
+            if (raw === null || typeof raw !== 'object')
+                return raw;
+            if (Array.isArray(raw)) {
+                // Array of resolved children — wrap the array; each element is
+                // its own doc scope (handled by the QueryResult branch below).
+                return new Proxy(raw, {
+                    get(arrT, arrP, arrR) {
+                        const item = Reflect.get(arrT, arrP, arrR);
+                        if (isQueryResult(item)) {
+                            registerRoot(item, item.documentId, '');
+                            return wrapNode(item, item.documentId, '', depth + 1);
+                        }
+                        return item;
+                    },
+                });
+            }
+            if (isQueryResult(raw)) {
+                registerRoot(raw, raw.documentId, '');
+                return wrapNode(raw, raw.documentId, '', depth + 1);
+            }
+            return raw;
+        },
+    });
+}
+// ─────────────────────────────────────────────
+// Eager structural enumeration (RSC-safe; matcher consumes this)
+// ─────────────────────────────────────────────
+/** Defensive caps — a pathological doc (deep nesting / huge arrays)
+ *  must never let the per-rAF matcher walk blow the frame budget. */
+const COLLECT_MAX_LEAVES = 8000;
+/**
+ * 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 function collectFieldModel() {
+    // ADR-126 — walk the UNION of the RSC-island roots and the Proxy
+    // roots. `collectFieldModelFromRoots` is the pure, singleton-free,
+    // window-free core (RSC-safe): the SAME `walk()` both the client
+    // Proxy path and the server island path converge on, which is what
+    // makes the parity invariant hold by construction (one walker, two
+    // model sources — never a second path grammar).
+    //
+    // Two INDEPENDENT walks merged with explicit precedence (cross-model
+    // /review R2, codex #1): a single concatenated walk let whichever
+    // source came first fill the shared `COLLECT_MAX_LEAVES` budget and
+    // starve the other (R1 island-first only moved the starvation onto
+    // the Proxy on a huge hybrid page). Walking each source independently
+    // removes the order-vs-cap coupling entirely:
+    //
+    //   • island = the RSC / cross-doc BASELINE (the pure-RSC content +
+    //     the independently-queried `getPageContext()` docs the client
+    //     Proxy never wrapped),
+    //   • Proxy `roots` = the LIVE client render — AUTHORITATIVE on a
+    //     same-`(docId,path)` conflict (the island only refreshes on an
+    //     RSC re-render; the Proxy reflects the current client value).
+    //
+    // Build the island model first, then overlay the Proxy model so a
+    // conflicting key takes the Proxy (live) value. Union ⇒ a leaf in
+    // EITHER source survives; neither can erase the other (codex #7 /
+    // D-RECONCILE) and neither can starve the other at the cap. On the
+    // dominant pure-RSC path `roots` is empty so this is exactly the
+    // island model. Fast path: no island ⇒ the Proxy walk alone.
+    if (islandRoots.length === 0)
+        return collectFieldModelFromRoots(roots);
+    const merged = new Map();
+    for (const f of collectFieldModelFromRoots(islandRoots)) {
+        merged.set(`${f.docId ?? ''}\x00${f.path}`, f);
+    }
+    for (const f of collectFieldModelFromRoots(roots)) {
+        merged.set(`${f.docId ?? ''}\x00${f.path}`, f); // Proxy overrides
+    }
+    return [...merged.values()];
+}
+/**
+ * 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 function collectFieldModelFromRoots(rootsList) {
+    const out = new Map();
+    for (const r of rootsList) {
+        if (out.size >= COLLECT_MAX_LEAVES)
+            break;
+        walk(r.data, r.docId, r.basePath, 0, out, new Set());
+    }
+    return [...out.values()];
+}
+/**
+ * ADR-126 — register the documents the RSC render-path island reported.
+ * Each `entry` is a projected `QueryResult` (`{ documentId, fields,
+ * resolved? }`) the SDK's `<SliceZone>` deep-scanned out of its rendered
+ * `context` and serialized server-side. `isQueryResult` is satisfied by
+ * the string `documentId`, so the existing `walk()` re-scopes docId and
+ * resets path at every `QueryResult`/`.resolved` boundary EXACTLY like
+ * the Proxy path — zero downstream change. Scope-keyed `(documentId,'')`
+ * replace. Defensive: a non-object / no-`documentId` entry is skipped,
+ * never thrown on (the island is parsed from possibly-hostile page HTML).
+ *
+ * Cap is `MAX_ISLAND_ROOTS` (NOT the Proxy `MAX_ROOTS=256`): callers
+ * replace the per-render snapshot through `clearIslandRoots()` followed
+ * by `registerIslandRoots()`, so it cannot leak the way the
+ * identity-keyed Proxy `roots` could
+ * (the original 256 cap was that leak's belt-and-braces). Aligning it to
+ * the producer/reader `MAX_ISLAND_DOCS` (4096) stops a large context
+ * (>256 docs, e.g. a big blogIndex) from evicting the FIRST-registered
+ * root — which is the previewed page itself, scanned first — and
+ * silently dropping the main page's own field overlays (codex #6).
+ */
+const MAX_ISLAND_ROOTS = 4096;
+/** 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 function clearIslandRoots() {
+    islandRoots.length = 0;
+}
+export function registerIslandRoots(entries) {
+    for (const entry of entries) {
+        if (!isQueryResult(entry))
+            continue;
+        const docId = entry.documentId;
+        let replaced = false;
+        for (const r of islandRoots) {
+            if (r.docId === docId && r.basePath === '') {
+                r.data = entry;
+                replaced = true;
+                break;
+            }
+        }
+        if (replaced)
+            continue;
+        islandRoots.push({ data: entry, docId, basePath: '' });
+        if (islandRoots.length > MAX_ISLAND_ROOTS)
+            islandRoots.shift();
+    }
+}
+function walk(node, docId, path, depth, out, seen) {
+    if (out.size >= COLLECT_MAX_LEAVES)
+        return;
+    if (isPlainPrimitive(node)) {
+        if (path !== '')
+            out.set(leafKey(docId, path), { path, value: node, docId });
+        return;
+    }
+    if (typeof node !== 'object' || node === null)
+        return;
+    if (depth >= MAX_DEPTH)
+        return;
+    if (seen.has(node))
+        return; // cycle guard
+    seen.add(node);
+    if (isQueryResult(node)) {
+        const childDocId = node.documentId;
+        const fields = node.fields;
+        if (fields && typeof fields === 'object') {
+            walk(fields, childDocId, path, depth + 1, out, seen);
+        }
+        const resolved = node.resolved;
+        if (resolved && typeof resolved === 'object') {
+            for (const child of Object.values(resolved)) {
+                if (Array.isArray(child)) {
+                    for (const c of child) {
+                        if (isQueryResult(c)) {
+                            walk(c, c.documentId, '', depth + 1, out, seen);
+                        }
+                    }
+                }
+                else if (isQueryResult(child)) {
+                    walk(child, child.documentId, '', depth + 1, out, seen);
+                }
+            }
+        }
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            walk(node[i], docId, joinIndex(path, i), depth + 1, out, seen);
+        }
+        return;
+    }
+    for (const [k, v] of Object.entries(node)) {
+        walk(v, docId, joinKey(path, k), depth + 1, out, seen);
+    }
+}
+// ─────────────────────────────────────────────
+// Public accessors (preserve the index.ts surface contract)
+// ─────────────────────────────────────────────
+/** Accessed leaves (lazy path). The matcher prefers `collectFieldModel`
+ *  (RSC-safe) but this stays for client-render precision + tests. */
+export function getTrackedFields() {
+    return [...accessed.values()];
+}
+/**
+ * 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 function clearTrackedFields() {
+    accessed.clear();
+    roots.length = 0;
+    // ADR-126 — the island roots are generation-scoped too: a render-mode
+    // epoch BUMP (cross-doc / mode / Form-entry) must drop the prior doc's
+    // island so a stale cross-doc-switch field never overlays. The fresh
+    // RSC render emits a new `<script data-ss-model>`; the next publish's
+    // island read repopulates from the current DOM (the island reader's
+    // parse cache is keyed by script text, so a content change re-parses;
+    // `registerIslandRoots` is called every publish and is idempotent, so
+    // it re-fills `islandRoots` after this clear even if the script text
+    // is unchanged — overlays never get stuck empty post-epoch).
+    clearIslandRoots();
+}

package/dist/runtime/form-contract-reporter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * In-iframe SDK runtime — Form-preview viewport-contract reporter
+ * (ADR-119 D2/D3/D6).
+ *
+ * Form preview (render-mode `'navigation'`) is a live, SDK-cooperative
+ * editorial mini-map. This runtime is the SDK half of the ADR-119
+ * contract; the Studio half is the disciplined controller in
+ * `apps/studio/.../preview-surface.tsx`.
+ *
+ *   1. On `render-mode: 'navigation'` it sets
+ *      `data-storystick-form-preview` on the customer document's
+ *      `<html>`. The migrated starter routes viewport-relative
+ *      primitives (`body { min-height: var(--ss-screen-h, 100dvh) }`,
+ *      `min-h-dvh`/`h-screen` utilities, full-screen sections) through
+ *      `--ss-screen-h`, which `html[data-storystick-form-preview]`
+ *      pins to 800px. This neutralises the EXP-3 cross-doc viewport
+ *      ratchet **at the source**: the customer's own primitives
+ *      resolve to a real 800, never the tall measuring iframe.
+ *
+ *   2. It measures `documentElement.scrollHeight` **under the applied
+ *      contract** and reports it to the Studio parent as
+ *      `{type:'storystick.preview.form-contract', epoch, applied:true,
+ *      pageHeight, viewportHeight}`. The FIRST report after an `epoch`
+ *      change is the
+ *      controller's hard ACK gate (ADR-119 D3 — "NEVER take the first
+ *      measurement without a confirmed ack"). Subsequent same-`epoch`
+ *      reports (layout-observer driven) feed the controller's
+ *      debounced in-doc resize cadence.
+ *
+ *   3. On `render-mode: 'device'` it removes the attribute and reports
+ *      `{applied:false, pageHeight:0}`. Device is strict browser truth
+ *      (1280×800), never virtualised.
+ *
+ * `epoch` is the Studio controller's instance-scoped generation
+ * counter (ADR-119 D1), carried on `MsgRenderMode` and echoed back
+ * verbatim on every report so the controller can discard stale
+ * cross-doc async measurements soundly (the ratchet-class guard).
+ *
+ * Principle (ADR-119 D6 / no-customer-DOM-interference, relaxed for
+ * Form only, contractualised): the ONLY customer-DOM write is the
+ * single `data-storystick-form-preview` attribute on `<html>`, set by
+ * the SDK the customer already embeds — NOT Studio reaching across
+ * origins, NOT CSS injection (the retracted ADR-102/112 §D4 path).
+ * Reads are limited to `documentElement.scrollHeight` and the iframe's own
+ * `window.innerHeight`. No content mutation, no DOM-tree inspection. A site not using the starter
+ * primitives simply gets an honest, slightly-less-faithful overview;
+ * Device stays exact.
+ */
+export declare const FORM_PREVIEW_ATTR = "data-storystick-form-preview";
+export interface FormContractReporterOptions {
+    /** Document the contract attribute is written on. Defaults to `window.document`. */
+    doc?: Document;
+    /** Window to read `parent` / attach the listener on. Defaults to `window`. */
+    win?: Window;
+    /** Override `requestAnimationFrame` for deterministic tests. */
+    raf?: (cb: () => void) => number;
+    /** Pair with `raf` to cancel pending settle/observer ticks on stop. */
+    caf?: (handle: number) => void;
+}
+export interface FormContractReport {
+    epoch: number;
+    applied: boolean;
+    pageHeight: number;
+    viewportHeight: number;
+    windowedProjection?: 'pending' | 'active' | 'unsupported';
+    windowedProjectionReason?: string;
+    windowStart?: number;
+    renderSpan?: number;
+    compression?: number;
+}
+export interface FormContractReporterHandle {
+    /**
+     * Tear down observers + listener AND remove the contract attribute
+     * (a torn-down SDK must not leave the customer document virtualised).
+     * Idempotent.
+     */
+    stop(): void;
+    /**
+     * Force a synchronous measure+publish for the current mode — used by
+     * tests to assert post-rAF state without real animation frames.
+     * Returns the report that was posted (or `null` if nothing has been
+     * driven yet).
+     */
+    flush(): FormContractReport | null;
+}
+/**
+ * Conceptual viewport for customer JS that needs the Form-preview
+ * height (ADR-119 D5 — explicit helper, NOT a global `window.
+ * innerHeight` shim). When the contract is active the computed
+ * `--ss-screen-h` resolves to `800px` and that is returned as the
+ * height; otherwise the real `innerHeight` (Device / no contract /
+ * non-starter site). Width is always the real `innerWidth` (Form does
+ * not virtualise width — the iframe is a true 1280 logical box).
+ */
+export declare function getStorystickViewport(win?: Window): {
+    width: number;
+    height: number;
+};
+export declare function startFormContractReporter(options?: FormContractReporterOptions): FormContractReporterHandle;