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

package/dist/runtime/preview-interaction-policy.js

@@ -0,0 +1,103 @@
+import { getInteractionMode, subscribeInteractionMode, } from "../interaction-mode.js";
+import { PREVIEW_SELECT_CURSOR } from "../select-cursor.js";
+const STYLE_ID = "storystick-preview-interaction-policy-style";
+const INTERACTION_ATTR = "data-ss-preview-interaction";
+// `:root` is stable state-free specificity. It keeps the policy above common
+// customer utility classes that also declare an `!important` cursor, without
+// putting any mutable interaction state back on a React-owned singleton.
+const EDIT_INTERACTION_CSS = `
+  html:root,
+  html:root body,
+  html:root body * {
+    cursor: ${PREVIEW_SELECT_CURSOR} !important;
+    -webkit-user-select: none !important;
+    user-select: none !important;
+  }
+`;
+const POLICY_STATE_KEY = Symbol.for("storystick.preview.interaction-policy-state.v1");
+export function installPreviewInteractionPolicy(win) {
+    const existing = getPolicyInstallation(win);
+    if (existing !== undefined) {
+        existing.count += 1;
+        // Installation ref-counting must not turn a repeated install into a
+        // no-op for the DOM. Framework head reconciliation can leave the
+        // in-memory mode intact while the runtime-owned style is absent.
+        applyInteractionMode(win.document, getInteractionMode());
+        return releasePreviewInteractionPolicy(win);
+    }
+    const doc = win.document;
+    ensureInteractionPolicyStyle(doc);
+    applyInteractionMode(doc, getInteractionMode());
+    const installation = {
+        count: 1,
+        unsubscribe: subscribeInteractionMode((mode) => {
+            applyInteractionMode(doc, mode);
+        }),
+    };
+    Reflect.set(win, POLICY_STATE_KEY, installation);
+    return releasePreviewInteractionPolicy(win);
+}
+function releasePreviewInteractionPolicy(win) {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const installation = getPolicyInstallation(win);
+        if (installation === undefined)
+            return;
+        installation.count = Math.max(0, installation.count - 1);
+        if (installation.count > 0)
+            return;
+        installation.unsubscribe();
+        // The DOM contract belongs to the browsing realm, not to whichever
+        // component/session/runtime guard currently holds an installation ref.
+        // Keeping the last authoritative stylesheet state prevents transient
+        // teardown (StrictMode, route handoff, recovery-frame swap, duplicate SDK
+        // entrypoints) from exposing the customer's native cursor. A full document
+        // navigation naturally discards the entire Window and its policy.
+        Reflect.deleteProperty(win, POLICY_STATE_KEY);
+    };
+}
+function getPolicyInstallation(win) {
+    return Reflect.get(win, POLICY_STATE_KEY);
+}
+function applyInteractionMode(doc, mode) {
+    const style = ensureInteractionPolicyStyle(doc);
+    // React 19 treats <html>, <head>, and <body> as singleton nodes. During an
+    // App Router segment swap it releases and reacquires those singletons,
+    // removing attributes that were not declared by the new React tree. The
+    // interaction mode therefore cannot live on documentElement: a doc-to-doc
+    // SPA navigation would erase it without producing an iframe `load` or a new
+    // Studio interaction-mode envelope.
+    //
+    // Keep both the state marker and the active rule on the runtime-owned style
+    // element instead. The style survives singleton reconciliation, so Select
+    // remains the default across every route commit. Browse opts out by leaving
+    // the policy stylesheet empty, preserving the customer's own cursor rules.
+    style.setAttribute(INTERACTION_ATTR, mode);
+    const nextCss = mode === "edit" ? EDIT_INTERACTION_CSS : "";
+    if (style.textContent !== nextCss)
+        style.textContent = nextCss;
+}
+function ensureInteractionPolicyStyle(doc) {
+    const existing = doc.getElementById(STYLE_ID);
+    if (existing?.tagName === "STYLE")
+        return existing;
+    existing?.remove();
+    const style = doc.createElement("style");
+    style.id = STYLE_ID;
+    // Product rule (owner arbitration 2026-08-05): in Select mode
+    // (`edit` interaction) the custom Select cursor applies ALWAYS,
+    // across the whole preview surface — independent of painter state,
+    // overlay presence, or render-mode. The former
+    // `body[data-render-mode="device"]` gate made the cursor vanish
+    // whenever the render-mode message had not (yet) stamped the body
+    // (fresh realm after a hard nav, painter dead, non-device stages) —
+    // exactly the states where the mode signal must stay readable.
+    // Navigation (minimap) stages are unaffected by the wider selector:
+    // their iframe wrapper is `pointerEvents: none`, so no pointer ever
+    // hovers iframe content there.
+    (doc.head ?? doc.documentElement).appendChild(style);
+    return style;
+}

package/dist/runtime/preview-overlay-painter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ADR-142 P1 — iframe-local field overlay painter.
+ *
+ * Paint stays iframe-local: no labels/handles, no high-z overlay root.
+ * Optional clicks report only opaque paint identity to Studio; Studio
+ * owns the private field routing table.
+ */
+import type { PreviewIframeInteractionPayload, PreviewOverlayClickPayload, PreviewOverlayMapPayload, PreviewV2RevealResultStatus, PreviewV2RevealSourcePayload } from "@storystick/transport-allowlist";
+export interface PreviewOverlayPainterOptions {
+    onClick?: (payload: PreviewOverlayClickPayload) => void;
+}
+export interface PreviewEditInteractionGuardOptions {
+    onInteraction?: (payload: PreviewIframeInteractionPayload) => void;
+}
+export interface PreviewOverlayPaintResult {
+    generation: number;
+    paintedCount: number;
+    missingSnapshotItemKeys: string[];
+}
+export interface PreviewV2RevealResult {
+    status: PreviewV2RevealResultStatus;
+    revealedCount: number;
+}
+export declare function applyPreviewOverlayMap(payload: PreviewOverlayMapPayload, win: Window, options?: PreviewOverlayPainterOptions | ((payload: PreviewOverlayClickPayload) => void)): PreviewOverlayPaintResult;
+export declare function clearPreviewOverlayPaint(): void;
+export declare function installPreviewEditInteractionGuard(win: Window, options?: PreviewEditInteractionGuardOptions): () => void;
+export declare function revealPreviewV2SourceInIframe(payload: PreviewV2RevealSourcePayload, win: Window): PreviewV2RevealResult;