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

package/dist/runtime/live-query-overlay.js

@@ -0,0 +1,345 @@
+import { PREVIEW_LIVE_QUERY_MAX_QUERIES, PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, validatePreviewEnvelope, } from '@storystick/transport-allowlist';
+import { estimatePreviewPayloadBytes, recordPreviewPerfMetric, } from './perf-metrics.js';
+import { createPreviewRequestId } from './request-id.js';
+const NOOP_HANDLE = Object.freeze({
+    queryInstanceId: null,
+    getSnapshot: () => null,
+    subscribe: () => () => { },
+    updateReceipt: () => { },
+    release: () => { },
+});
+export function createPreviewLiveQueryOverlayRuntime(options = {}) {
+    const randomHex = options.randomHex ?? createPreviewRequestId;
+    const now = options.now ?? Date.now;
+    const slotsByIdentity = new Map();
+    const slotsByInstance = new Map();
+    let configuration = {
+        enabled: false,
+        projectId: null,
+        sessionId: null,
+        parentOrigin: null,
+    };
+    let sourceEpoch = null;
+    let observedCapability = null;
+    let installedView = null;
+    const onMessage = (event) => {
+        const validated = validatePreviewEnvelope(event.data);
+        if (!validated.ok)
+            return;
+        acceptStudioEnvelope(validated.message, event.origin, installedView !== null && event.source === installedView.parent);
+    };
+    function configure(next) {
+        const previousIdentity = [
+            configuration.projectId,
+            configuration.sessionId,
+            configuration.parentOrigin,
+        ].join('|');
+        const nextIdentity = [
+            next.projectId,
+            next.sessionId,
+            next.parentOrigin,
+        ].join('|');
+        configuration = next;
+        const nextView = next.enabled
+            ? next.view ?? (typeof window === 'undefined' ? null : window)
+            : null;
+        if (installedView !== nextView) {
+            installedView?.removeEventListener('message', onMessage);
+            installedView = nextView;
+            installedView?.addEventListener('message', onMessage);
+        }
+        if (!next.enabled || previousIdentity !== nextIdentity) {
+            if (!next.enabled)
+                observedCapability = null;
+            sourceEpoch = capabilityMatchesConfiguration(observedCapability, next)
+                ? observedCapability.sourceEpoch
+                : null;
+            clearProjections();
+            if (sourceEpoch !== null) {
+                for (const slot of slotsByIdentity.values())
+                    sendRegister(slot);
+            }
+        }
+    }
+    function retain(queryIdentity) {
+        let slot = slotsByIdentity.get(queryIdentity);
+        if (!slot) {
+            if (slotsByIdentity.size >= PREVIEW_LIVE_QUERY_MAX_QUERIES) {
+                return NOOP_HANDLE;
+            }
+            slot = {
+                queryIdentity,
+                queryInstanceId: `lq_${randomHex()}`,
+                listeners: new Set(),
+                retainCount: 0,
+                receiptId: null,
+                projection: null,
+            };
+            slotsByIdentity.set(queryIdentity, slot);
+            slotsByInstance.set(slot.queryInstanceId, slot);
+        }
+        slot.retainCount += 1;
+        let released = false;
+        return {
+            queryInstanceId: slot.queryInstanceId,
+            getSnapshot: () => released ? null : slot.projection,
+            subscribe(listener) {
+                if (released)
+                    return () => { };
+                slot.listeners.add(listener);
+                return () => slot.listeners.delete(listener);
+            },
+            updateReceipt(receiptId) {
+                if (released || slot.receiptId === receiptId)
+                    return;
+                const hadProjection = slot.projection !== null;
+                slot.receiptId = receiptId;
+                slot.projection = null;
+                if (hadProjection)
+                    notify(slot);
+                if (receiptId !== null)
+                    sendRegister(slot);
+            },
+            release() {
+                if (released)
+                    return;
+                released = true;
+                slot.retainCount -= 1;
+                if (slot.retainCount > 0)
+                    return;
+                sendUnregister(slot);
+                slotsByIdentity.delete(slot.queryIdentity);
+                slotsByInstance.delete(slot.queryInstanceId);
+                slot.listeners.clear();
+                slot.projection = null;
+            },
+        };
+    }
+    function acceptStudioEnvelope(message, eventOrigin, sourceIsParent) {
+        if (!configuration.enabled || !sourceIsParent)
+            return;
+        if (message.type === 'storystick.preview.session-broadcast') {
+            if (message.projectId !== configuration.projectId)
+                return;
+            if (configuration.sessionId !== null &&
+                message.sessionId !== configuration.sessionId)
+                return;
+            if (message.payload.parentOrigin !== eventOrigin)
+                return;
+            if (configuration.parentOrigin !== null &&
+                configuration.parentOrigin !== eventOrigin)
+                return;
+            const nextEpoch = message.payload.liveQueryOverlay?.sourceEpoch ?? null;
+            observedCapability = nextEpoch === null
+                ? null
+                : {
+                    projectId: message.projectId,
+                    sessionId: message.sessionId,
+                    parentOrigin: eventOrigin,
+                    sourceEpoch: nextEpoch,
+                };
+            if (nextEpoch === sourceEpoch)
+                return;
+            sourceEpoch = nextEpoch;
+            clearProjections();
+            if (sourceEpoch !== null) {
+                for (const slot of slotsByIdentity.values())
+                    sendRegister(slot);
+            }
+            return;
+        }
+        if (message.type !== 'storystick.preview.live-query.projection')
+            return;
+        if (sourceEpoch === null)
+            return;
+        if (configuration.sessionId === null ||
+            configuration.parentOrigin === null ||
+            message.sessionId !== configuration.sessionId ||
+            message.projectId !== configuration.projectId ||
+            eventOrigin !== configuration.parentOrigin ||
+            message.payload.sourceEpoch !== sourceEpoch)
+            return;
+        const slot = slotsByInstance.get(message.payload.queryInstanceId);
+        if (!slot || slot.receiptId === null)
+            return;
+        if (slot.projection !== null &&
+            message.payload.sourceRevision <= slot.projection.sourceRevision)
+            return;
+        slot.projection = message.payload;
+        if (installedView !== null) {
+            const editorMutationAt = message.payload.editorMutationAt;
+            recordPreviewPerfMetric(installedView, {
+                name: 'preview.liveQuery.projectionReceived',
+                ...(editorMutationAt === undefined
+                    ? {}
+                    : {
+                        durationMs: Math.max(0, epochNow(installedView) - editorMutationAt),
+                    }),
+                detail: {
+                    queryInstanceId: message.payload.queryInstanceId,
+                    sourceRevision: message.payload.sourceRevision,
+                    payloadBytes: estimatePreviewPayloadBytes(installedView, message.payload),
+                },
+            });
+        }
+        notify(slot);
+    }
+    function clear() {
+        sourceEpoch = null;
+        clearProjections();
+    }
+    function clearProjections() {
+        for (const slot of slotsByIdentity.values()) {
+            if (slot.projection === null)
+                continue;
+            slot.projection = null;
+            notify(slot);
+        }
+    }
+    function notify(slot) {
+        for (const listener of slot.listeners)
+            listener();
+    }
+    function sendRegister(slot) {
+        if (slot.receiptId === null || sourceEpoch === null)
+            return;
+        const identity = outboundIdentity();
+        if (identity === null)
+            return;
+        send({
+            namespace: PREVIEW_NAMESPACE,
+            version: PREVIEW_PROTOCOL_VERSION,
+            type: 'storystick.preview.live-query.register',
+            ...identity.envelope,
+            payload: {
+                queryInstanceId: slot.queryInstanceId,
+                sourceEpoch,
+                receiptId: slot.receiptId,
+            },
+        }, identity.parentOrigin);
+    }
+    function sendUnregister(slot) {
+        if (sourceEpoch === null)
+            return;
+        const identity = outboundIdentity();
+        if (identity === null)
+            return;
+        send({
+            namespace: PREVIEW_NAMESPACE,
+            version: PREVIEW_PROTOCOL_VERSION,
+            type: 'storystick.preview.live-query.unregister',
+            ...identity.envelope,
+            payload: {
+                queryInstanceId: slot.queryInstanceId,
+                sourceEpoch,
+            },
+        }, identity.parentOrigin);
+    }
+    function outboundIdentity() {
+        if (!configuration.enabled ||
+            configuration.projectId === null ||
+            configuration.sessionId === null ||
+            configuration.parentOrigin === null)
+            return null;
+        return {
+            parentOrigin: configuration.parentOrigin,
+            envelope: {
+                sessionId: configuration.sessionId,
+                projectId: configuration.projectId,
+                requestId: randomHex(),
+                nonce: randomHex(),
+                sentAt: now(),
+            },
+        };
+    }
+    function send(envelope, targetOrigin) {
+        if (options.send)
+            options.send(envelope, targetOrigin);
+        else
+            installedView?.parent.postMessage(envelope, targetOrigin);
+    }
+    return {
+        configure,
+        retain,
+        clear,
+        acceptStudioEnvelope,
+        activeQueryCount: () => slotsByIdentity.size,
+    };
+}
+function capabilityMatchesConfiguration(capability, configuration) {
+    return capability !== null &&
+        capability.projectId === configuration.projectId &&
+        (configuration.sessionId === null ||
+            capability.sessionId === configuration.sessionId) &&
+        (configuration.parentOrigin === null ||
+            capability.parentOrigin === configuration.parentOrigin);
+}
+function epochNow(view) {
+    return view.performance.timeOrigin + view.performance.now();
+}
+export const previewLiveQueryOverlay = createPreviewLiveQueryOverlayRuntime();
+/**
+ * Derive a render-only QueryResult. The confirmed object is never mutated and
+ * neither membership, order, pageInfo nor metadata can change.
+ */
+export function applyPreviewLiveQueryProjection(confirmed, projection) {
+    if (confirmed === undefined ||
+        confirmed.exactness === 'blocked' ||
+        projection === null)
+        return confirmed;
+    const data = confirmed.data;
+    if (Array.isArray(data)) {
+        let changed = false;
+        const visible = data.map((document) => {
+            const next = overlayDocument(document, projection);
+            if (next !== document)
+                changed = true;
+            return next;
+        });
+        if (!changed)
+            return confirmed;
+        return { ...confirmed, data: visible };
+    }
+    const visible = overlayDocument(data, projection);
+    if (visible === data)
+        return confirmed;
+    return { ...confirmed, data: visible };
+}
+function overlayDocument(document, projection) {
+    if (!isRecord(document) || document.documentId !== projection.documentId) {
+        return document;
+    }
+    if (!isRecord(document.fields))
+        return document;
+    let fields = document.fields;
+    for (const entry of projection.entries) {
+        fields = updateProjectedPath(fields, entry.path.split('.'), entry);
+    }
+    return fields === document.fields ? document : { ...document, fields };
+}
+function updateProjectedPath(root, segments, entry) {
+    const [head, ...tail] = segments;
+    if (head === undefined)
+        return root;
+    if (tail.length === 0) {
+        const hasCurrent = Object.prototype.hasOwnProperty.call(root, head);
+        if (!entry.present) {
+            if (!hasCurrent)
+                return root;
+            const next = { ...root };
+            delete next[head];
+            return next;
+        }
+        if (hasCurrent && Object.is(root[head], entry.value))
+            return root;
+        return { ...root, [head]: entry.value };
+    }
+    const current = root[head];
+    if (!isRecord(current) && !entry.present)
+        return root;
+    const nextChild = updateProjectedPath(isRecord(current) ? current : {}, tail, entry);
+    return nextChild === current ? root : { ...root, [head]: nextChild };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/runtime/momentary-navigate.d.ts

@@ -0,0 +1,16 @@
+export declare const MOMENTARY_NAVIGATE_KEY_SIGNAL_TYPE: "storystick.preview.momentary-navigate-key";
+export interface MomentaryNavigateKeySignal {
+    type: typeof MOMENTARY_NAVIGATE_KEY_SIGNAL_TYPE;
+    key: 'Alt';
+    active: boolean;
+}
+interface MomentaryNavigateKeyRelayOptions {
+    getTargetOrigin?: () => string | null;
+}
+export declare function isMomentaryNavigateKeySignal(data: unknown): data is MomentaryNavigateKeySignal;
+export declare function installMomentaryNavigateKeyRelay(win?: Window, options?: MomentaryNavigateKeyRelayOptions): () => void;
+/** Customer links are observed only within explicit editing carriers. */
+export declare function getAnchorFromPreviewClickEvent(event: Event, win?: Window): HTMLAnchorElement | null;
+export declare function isMomentaryNavigateKeyDown(event: KeyboardEvent): boolean;
+export declare function normalizeMomentaryNavigateLinkClick(event: MouseEvent, target: HTMLAnchorElement, win?: Window): boolean;
+export {};

package/dist/runtime/momentary-navigate.js

@@ -0,0 +1,106 @@
+export const MOMENTARY_NAVIGATE_KEY_SIGNAL_TYPE = 'storystick.preview.momentary-navigate-key';
+export function isMomentaryNavigateKeySignal(data) {
+    if (data === null || typeof data !== 'object')
+        return false;
+    const signal = data;
+    return (signal.type === MOMENTARY_NAVIGATE_KEY_SIGNAL_TYPE &&
+        signal.key === 'Alt' &&
+        typeof signal.active === 'boolean');
+}
+export function installMomentaryNavigateKeyRelay(win = window, options = {}) {
+    if (win.parent === win)
+        return () => { };
+    const doc = win.document;
+    let lastActive = null;
+    const emit = (active) => {
+        if (lastActive === active)
+            return;
+        lastActive = active;
+        const targetOrigin = options.getTargetOrigin?.() ?? '*';
+        win.parent.postMessage({
+            type: MOMENTARY_NAVIGATE_KEY_SIGNAL_TYPE,
+            key: 'Alt',
+            active,
+        }, targetOrigin && targetOrigin.length > 0 ? targetOrigin : '*');
+    };
+    const onKeyDown = (event) => {
+        if (!isMomentaryNavigateKeyDown(event))
+            return;
+        emit(true);
+    };
+    const onKeyUp = (event) => {
+        if (event.key === 'Alt' || !event.altKey)
+            emit(false);
+    };
+    const release = () => emit(false);
+    doc.addEventListener('keydown', onKeyDown, true);
+    doc.addEventListener('keyup', onKeyUp, true);
+    win.addEventListener('pagehide', release);
+    doc.addEventListener('visibilitychange', release);
+    return () => {
+        if (lastActive === true)
+            emit(false);
+        doc.removeEventListener('keydown', onKeyDown, true);
+        doc.removeEventListener('keyup', onKeyUp, true);
+        win.removeEventListener('pagehide', release);
+        doc.removeEventListener('visibilitychange', release);
+    };
+}
+/** Customer links are observed only within explicit editing carriers. */
+export function getAnchorFromPreviewClickEvent(event, win = window) {
+    const view = win;
+    const nodes = typeof event.composedPath === 'function' ? event.composedPath() : [];
+    for (const node of [...nodes, event.target]) {
+        if (!(node instanceof view.Element))
+            continue;
+        const anchor = node.closest('a[href]');
+        if (!(anchor instanceof view.HTMLAnchorElement))
+            continue;
+        if (anchor.matches('[data-ss-e], [data-ss-p]') ||
+            anchor.closest('[data-ss-e], [data-ss-p]') !== null ||
+            anchor.querySelector('[data-ss-e], [data-ss-p]') !== null) {
+            return anchor;
+        }
+    }
+    return null;
+}
+export function isMomentaryNavigateKeyDown(event) {
+    if (event.key !== 'Alt')
+        return false;
+    if (!event.altKey)
+        return false;
+    if (event.ctrlKey || event.metaKey)
+        return false;
+    if (event.getModifierState('AltGraph'))
+        return false;
+    return true;
+}
+export function normalizeMomentaryNavigateLinkClick(event, target, win = window) {
+    if (!shouldNormalizeMomentaryNavigateLinkClick(event, target, win)) {
+        return false;
+    }
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    target.click();
+    return true;
+}
+function shouldNormalizeMomentaryNavigateLinkClick(event, target, win) {
+    if (event.defaultPrevented)
+        return false;
+    if (event.button !== 0)
+        return false;
+    if (!event.altKey)
+        return false;
+    if (event.ctrlKey || event.metaKey || event.shiftKey)
+        return false;
+    if (target.hasAttribute('download'))
+        return false;
+    let url;
+    try {
+        url = new URL(target.href, win.location.href);
+    }
+    catch {
+        return false;
+    }
+    return url.origin === win.location.origin;
+}

package/dist/runtime/observation-scheduler.d.ts

@@ -0,0 +1,15 @@
+export type PreviewObservationReason = 'resize' | 'mutation' | 'fonts-ready' | 'render-mode' | 'initial' | 'kick' | 'cache-version-changed' | 'route-hash-ready' | 'schema-ready' | 'form-contract';
+export interface PreviewObservationScheduler {
+    request(reason: PreviewObservationReason): void;
+    flush(): void;
+    cancel(): void;
+    isPending(): boolean;
+}
+export interface CreatePreviewObservationSchedulerOptions {
+    raf: (cb: () => void) => number;
+    caf: (handle: number) => void;
+    onFlush: (reason: PreviewObservationReason) => void;
+    onEnqueue?: (reason: PreviewObservationReason) => void;
+    onSkipPending?: (reason: PreviewObservationReason, pendingReason: PreviewObservationReason) => void;
+}
+export declare function createPreviewObservationScheduler(opts: CreatePreviewObservationSchedulerOptions): PreviewObservationScheduler;

package/dist/runtime/observation-scheduler.js

@@ -0,0 +1,42 @@
+export function createPreviewObservationScheduler(opts) {
+    let pending = null;
+    let pendingReason = null;
+    const run = () => {
+        if (pending === null)
+            return;
+        const reason = pendingReason ?? 'kick';
+        pending = null;
+        pendingReason = null;
+        opts.onFlush(reason);
+    };
+    return {
+        request(reason) {
+            if (pending !== null) {
+                opts.onSkipPending?.(reason, pendingReason ?? reason);
+                return;
+            }
+            pendingReason = reason;
+            opts.onEnqueue?.(reason);
+            pending = opts.raf(run);
+        },
+        flush() {
+            if (pending !== null) {
+                opts.caf(pending);
+                pending = null;
+            }
+            const reason = pendingReason ?? 'kick';
+            pendingReason = null;
+            opts.onFlush(reason);
+        },
+        cancel() {
+            if (pending !== null) {
+                opts.caf(pending);
+            }
+            pending = null;
+            pendingReason = null;
+        },
+        isPending() {
+            return pending !== null;
+        },
+    };
+}

package/dist/runtime/perf-metrics.d.ts

@@ -0,0 +1,28 @@
+export type PreviewPerfMetricName = 'preview.grant.request' | 'preview.grant.response' | 'preview.navigate.received' | 'preview.navigate.paintAck' | 'next.navigate.context' | 'next.navigate.replace' | 'next.navigate.refresh' | 'next.navigate.refreshSettled' | 'next.navigate.locationCommitted' | 'next.contentRefresh.schedule' | 'next.contentRefresh.refresh' | 'next.contentRefresh.skipDuplicate' | 'next.contentRefresh.skipUnrelated' | 'next.contentRefresh.skipNavigateRefresh' | 'next.contentRefresh.skipEcho' | 'next.projectionRefresh.request' | 'next.projectionRefresh.satisfied' | 'next.previewCookieRefresh' | 'next.previewCookieRefreshOutcome' | 'preview.authTokenObserved' | 'snapshot.assemble.async' | 'snapshot.assemble.sync' | 'snapshot.emit' | 'snapshot.publish.drop' | 'snapshot.schedule.deferHostResize' | 'snapshot.schedule.enqueue' | 'snapshot.schedule.skipPending' | 'studio.previewBoot.mark' | 'studio.previewBoot.summary' | 'studio.previewOrchestrator.event' | 'studio.previewSurface.render' | 'studio.previewSurface.snapshotWrite' | 'studio.previewV2.keydownToPatchQueued' | 'studio.previewV2.patchQueued' | 'studio.previewV2.patchSendDropped' | 'studio.previewV2.patchPostMessage' | 'studio.previewV2.patchSent' | 'studio.previewV2.sourceIdentityMissing' | 'studio.previewV2.overlayMapAckTimeout' | 'studio.previewV2.overlayMapRejected' | 'studio.previewV2.overlayMapSent' | 'studio.previewV2.overlayReadinessStale' | 'studio.previewV2.overlayClickIgnored' | 'studio.previewV2.directLocatorRevalidation' | 'studio.previewV2.overlayPlanNull' | 'studio.previewV2.overlayReadyIgnored' | 'studio.previewV2.overlayReadyObserved' | 'studio.previewV2.epochAckMissed' | 'studio.previewV2.revealSkipped' | 'studio.previewV2.revealSent' | 'studio.previewV2.revealResult' | 'studio.previewV2.geometryTransactionStart' | 'studio.previewV2.geometryTransactionCommit' | 'studio.previewV2.geometryTransactionSlow' | 'studio.previewV2.geometryTransactionSuperseded' | 'studio.previewV2.recoveryAction' | 'previewV2.patchReceived' | 'previewV2.patchBatchRejected' | 'previewV2.patchSentToReceived' | 'previewV2.patchReceivedToStoreApplied' | 'previewV2.storeApplied' | 'previewV2.storeAppliedToPaint' | 'previewV2.dataSeamRejected' | 'studio.saveAttempt' | 'studio.saveAccepted' | 'studio.saveRejected' | 'studio.saveUnknown' | 'studio.saveNoop' | 'preview.contentRevisionObserved' | 'preview.overlayMapSent' | 'preview.overlayPaintApplied' | 'preview.overlayBoxesCommitted' | 'preview.overlayGeometryPass' | 'preview.overlayPresentationPass' | 'studio.editToPaint' | 'preview.liveQuery.projectionReceived' | 'preview.liveQuery.firstPaintOpportunity' | 'studio.preview.overlayMapAckRetry' | 'studio.preview.overlayReadinessStaleCount';
+export type PreviewPerfMetricValue = string | number | boolean | null;
+export interface PreviewPerfMetric {
+    name: PreviewPerfMetricName;
+    ts: number;
+    durationMs?: number;
+    detail?: Record<string, PreviewPerfMetricValue>;
+}
+export interface PreviewPerfSink {
+    enabled?: boolean;
+    maxEvents?: number;
+    events?: PreviewPerfMetric[];
+    onEvent?: (metric: PreviewPerfMetric) => void;
+}
+export declare function isPreviewPerfEnabled(win: Window): boolean;
+export declare function previewPerfNow(win: Window): number;
+export declare function recordPreviewPerfMetric(win: Window, metric: Omit<PreviewPerfMetric, 'ts'> & {
+    ts?: number;
+}): void;
+export declare function recordPreviewPerfMeasure(win: Window, name: PreviewPerfMetricName, startedAt: number, detail?: Record<string, PreviewPerfMetricValue>): void;
+export declare function estimatePreviewPayloadBytes(win: Window, payload: unknown): number | null;
+export declare function computeLiveQueryPaintP50P95(events: readonly PreviewPerfMetric[]): {
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+    count: number;
+};

package/dist/runtime/perf-metrics.js

@@ -0,0 +1,90 @@
+const DEFAULT_MAX_EVENTS = 250;
+const MAX_EVENTS = 1000;
+const MAX_DETAIL_FIELDS = 32;
+export function isPreviewPerfEnabled(win) {
+    return readPreviewPerfSink(win)?.enabled === true;
+}
+export function previewPerfNow(win) {
+    const perf = win.performance;
+    return perf && typeof perf.now === 'function' ? perf.now() : Date.now();
+}
+export function recordPreviewPerfMetric(win, metric) {
+    const sink = readPreviewPerfSink(win);
+    if (sink?.enabled !== true)
+        return;
+    try {
+        const event = {
+            name: metric.name,
+            ts: Number.isFinite(metric.ts) ? metric.ts : previewPerfNow(win),
+            ...(typeof metric.durationMs === 'number' && Number.isFinite(metric.durationMs) && metric.durationMs >= 0
+                ? { durationMs: metric.durationMs } : {}),
+            ...(metric.detail ? { detail: scalarMetricDetail(metric.detail) } : {}),
+        };
+        if (!Array.isArray(sink.events))
+            sink.events = [];
+        sink.events.push(event);
+        const maxEvents = typeof sink.maxEvents === 'number' && Number.isFinite(sink.maxEvents) && sink.maxEvents >= 1
+            ? Math.min(MAX_EVENTS, Math.floor(sink.maxEvents))
+            : DEFAULT_MAX_EVENTS;
+        if (sink.events.length > maxEvents) {
+            sink.events.splice(0, sink.events.length - maxEvents);
+        }
+        sink.onEvent?.(event);
+    }
+    catch {
+        // Perf telemetry must never affect preview runtime behavior.
+    }
+}
+function scalarMetricDetail(detail) {
+    // Metric names carry the closed phase vocabulary. Keep counts/flags only:
+    // route URLs, content, credentials and high-cardinality identifiers do not
+    // belong in a metrics buffer or in its external onEvent callback.
+    return Object.fromEntries(Object.entries(detail).filter(([key, value]) => /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) && (value === null || typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)))).slice(0, MAX_DETAIL_FIELDS));
+}
+export function recordPreviewPerfMeasure(win, name, startedAt, detail) {
+    if (!isPreviewPerfEnabled(win))
+        return;
+    recordPreviewPerfMetric(win, {
+        name,
+        durationMs: Math.max(0, previewPerfNow(win) - startedAt),
+        detail,
+    });
+}
+export function estimatePreviewPayloadBytes(win, payload) {
+    if (!isPreviewPerfEnabled(win))
+        return null;
+    try {
+        const json = JSON.stringify(payload);
+        const encoder = new TextEncoder();
+        return encoder.encode(json).byteLength;
+    }
+    catch {
+        return null;
+    }
+}
+function readPreviewPerfSink(win) {
+    const raw = win.__STORYSTICK_PREVIEW_PERF__;
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    return raw;
+}
+export function computeLiveQueryPaintP50P95(events) {
+    const samples = events.flatMap((event) => event.name === 'preview.liveQuery.firstPaintOpportunity' &&
+        typeof event.durationMs === 'number' &&
+        Number.isFinite(event.durationMs) && event.durationMs >= 0
+        ? [event.durationMs]
+        : []).sort((a, b) => a - b);
+    if (samples.length === 0)
+        return { p50: 0, p95: 0, p99: 0, max: 0, count: 0 };
+    return {
+        p50: percentile(samples, 0.5),
+        p95: percentile(samples, 0.95),
+        p99: percentile(samples, 0.99),
+        max: samples[samples.length - 1],
+        count: samples.length,
+    };
+}
+function percentile(values, ratio) {
+    return values[Math.ceil(values.length * ratio) - 1];
+}

package/dist/runtime/preview-interaction-policy.d.ts

@@ -0,0 +1 @@
+export declare function installPreviewInteractionPolicy(win: Window): () => void;