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

package/dist/use-render-mode-debounce.js

@@ -0,0 +1,143 @@
+'use client';
+/**
+ * useRenderModeDebounce — render-mode-aware value debounce.
+ *
+ * Wraps a reactive value and returns a copy that only updates after
+ * the debounce window appropriate for the current render mode:
+ *
+ *   - Navigation mode (`render-mode: 'navigation'` postMessage from
+ *     the Studio) → 100ms debounce. The editor reads STRUCTURE
+ *     (section order, slice type, slice count), not typography —
+ *     debouncing typographic updates by 100ms is imperceptible
+ *     in the miniature and reduces paint pressure during fast
+ *     typing.
+ *
+ *   - Device mode → 0ms (no debounce, real-time feedback).
+ *
+ * Spec: ADR-059 §Technical commitments;
+ * spec/preview-system.md §"Convex subscription debounced 100ms in
+ * Navigation mode".
+ *
+ * Implementation note: `@storystick/preview` is dynamically imported
+ * (it's a `private: true` package and may not be installed in
+ * production consumer apps). When the import fails, the hook falls
+ * back to a passthrough — no debounce, no error. Production builds
+ * never load preview anyway.
+ */
+import { useEffect, useState, useRef } from 'react';
+let previewModuleCache = undefined;
+async function loadPreviewModule() {
+    if (previewModuleCache !== undefined)
+        return previewModuleCache;
+    try {
+        const mod = (await import('@storystick/preview'));
+        if (typeof mod.getRenderMode === 'function' &&
+            typeof mod.subscribeRenderMode === 'function' &&
+            typeof mod.debounceForRenderMode === 'function') {
+            previewModuleCache = mod;
+            return mod;
+        }
+        previewModuleCache = null;
+        return null;
+    }
+    catch {
+        previewModuleCache = null;
+        return null;
+    }
+}
+/**
+ * ADR-125 D3 — synchronous best-effort field-Proxy wrap at the client
+ * query seam. Co-located with the preview-module loader so there is ONE
+ * dynamic-import discipline + ONE "production never loads preview" doc
+ * (anti-spaghetti). Behaviour:
+ *
+ *   - Module not cached yet (first renders, or non-preview where it
+ *     never loads) → returns `data` unchanged. `useRenderModeDebounce`
+ *     (called by the generated-query hook) kicks the async load;
+ *     once cached, subsequent renders wrap. The preview iframe re-renders
+ *     on `contentRevision` so the model populates well within the
+ *     first-visible window.
+ *   - Cached but the SDK reports tracking inactive (not embedded, SSR,
+ *     production) → `wrapWithProxy` itself is a referential identity
+ *     no-op (Lane G). Zero overhead, zero allocation.
+ *
+ * RSC residual (ADR-125 §5/§7): a pure-RSC customer (Next App Router
+ * `createServerClient()` — the next-marketing/Coast dogfood) never
+ * calls this hook, so its field model is never registered. Field
+ * auto-annotation there degrades to `data-ss-doc` (Lane A, serialized)
+ * + section overlays (PR1b) + the `data-ss` developer escape hatch
+ * (Lane C). Closing it needs the SDK to observe the resolved doc
+ * client-side — an ADR-031 Pattern-C extension, deliberately out of PR2.
+ */
+export function tryWrapResultForPreview(docs) {
+    if (previewModuleCache == null)
+        return docs;
+    const wrap = previewModuleCache.wrapWithProxy;
+    if (typeof wrap !== 'function')
+        return docs;
+    if (!Array.isArray(docs))
+        return docs;
+    // Wrap each QueryResult under its own documentId scope. `wrap` is an
+    // identity no-op when tracking is inactive, so this is safe in tests
+    // (jsdom is not an embedded iframe) and production (module unloaded).
+    return docs.map((d) => {
+        const docId = d && typeof d === 'object' && typeof d.documentId === 'string'
+            ? d.documentId
+            : null;
+        return wrap(d, docId);
+    });
+}
+export function useRenderModeDebounce(value) {
+    const [renderMode, setRenderMode] = useState('device');
+    const [debounced, setDebounced] = useState(value);
+    const timerRef = useRef(null);
+    useEffect(() => {
+        let unsub;
+        let cancelled = false;
+        void loadPreviewModule().then((mod) => {
+            if (cancelled || !mod)
+                return;
+            // Seed with current state first so we don't strand on 'device'
+            // if the runtime already flipped before this hook mounted.
+            setRenderMode(mod.getRenderMode());
+            unsub = mod.subscribeRenderMode(setRenderMode);
+        });
+        return () => {
+            cancelled = true;
+            unsub?.();
+        };
+    }, []);
+    useEffect(() => {
+        const ms = renderMode === 'navigation' ? 100 : 0;
+        if (ms === 0) {
+            // Flush any pending tail update synchronously so we don't
+            // strand the user on a stale value when they switch modes.
+            if (timerRef.current !== null) {
+                clearTimeout(timerRef.current);
+                timerRef.current = null;
+            }
+            setDebounced(value);
+            return;
+        }
+        if (timerRef.current !== null)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            setDebounced(value);
+        }, ms);
+        return () => {
+            if (timerRef.current !== null) {
+                clearTimeout(timerRef.current);
+                timerRef.current = null;
+            }
+        };
+    }, [value, renderMode]);
+    return debounced;
+}
+/**
+ * Test-only — flushes the dynamic-import cache so tests can inject
+ * fake preview modules. Not exported from index.ts.
+ */
+export function _resetPreviewModuleCacheForTests() {
+    previewModuleCache = undefined;
+}

package/dist/video.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { type ResolveVideoOptions, type ResolvedStorystickVideo, type StorystickVideoField } from '@storystick/media/video';
+/** Resolve a Video field from an explicit or value-owned asset metadata. */
+export { resolveVideo } from '@storystick/media/video';
+type VideoElementProps = Omit<React.ComponentPropsWithRef<'video'>, 'src' | 'poster' | 'width' | 'height' | 'children'>;
+export type StorystickVideoComponentProps = VideoElementProps & {
+    video: StorystickVideoField | null | undefined;
+    options?: ResolveVideoOptions;
+    children?: React.ReactNode;
+    fallback?: StorystickVideoFallback;
+};
+export type StorystickVideoFailure = Exclude<ResolvedStorystickVideo, {
+    readonly status: 'ok';
+}>;
+export type StorystickVideoFallback = React.ReactNode | ((resolution: StorystickVideoFailure) => React.ReactNode);
+/**
+ * Server-safe native video with provider-owned source, optional poster,
+ * resolved WebVTT tracks and Preview provenance carriers.
+ */
+export declare function StorystickVideo(input: StorystickVideoComponentProps): React.ReactElement | null;
+export type { ResolvedStorystickVideo, ResolvedStorystickVideoPoster, ResolvedStorystickVideoTrack, ResolveVideoOptions, StorystickVideoField, StorystickVideoProps, StorystickVideoTrack, StorystickVideoTrackProps, VideoPosterStatus, VideoStatus, VideoTrackStatus, } from '@storystick/media/video';

package/dist/video.js

@@ -0,0 +1,63 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { emitMediaDiagnostic, isProduction } from '@storystick/media/internal/render-diagnostics';
+import { cleanPreviewAttributes } from '@storystick/types/internal/preview-provenance';
+import { resolveVideo, } from '@storystick/media/video';
+/** Resolve a Video field from an explicit or value-owned asset metadata. */
+export { resolveVideo } from '@storystick/media/video';
+/**
+ * Server-safe native video with provider-owned source, optional poster,
+ * resolved WebVTT tracks and Preview provenance carriers.
+ */
+export function StorystickVideo(input) {
+    const { video, options = {}, children, fallback, ...elementProps } = input;
+    const diagnostics = [];
+    const resolved = resolveVideo(video, {
+        ...options,
+        warn: (message) => diagnostics.push(message),
+    });
+    if (resolved.status !== 'ok') {
+        if (!isProduction() && resolved.status !== 'no-video') {
+            emitMediaDiagnostic(`StorystickWarning: video resolution status=${resolved.status}.${diagnostics.length > 0 ? ` ${diagnostics.join(' ')}` : ''}`, options.warn);
+        }
+        if (fallback !== undefined) {
+            return (_jsx(_Fragment, { children: typeof fallback === 'function' ? fallback(resolved) : fallback }));
+        }
+        if (isProduction() || resolved.status === 'no-video')
+            return null;
+        return (_jsx("span", { "aria-hidden": "true", "data-storystick-video-status": resolved.status, ...('data-ss-e' in resolved
+                ? { 'data-ss-e': resolved['data-ss-e'] }
+                : {}) }));
+    }
+    if (!isProduction()) {
+        for (const message of diagnostics)
+            emitMediaDiagnostic(message, options.warn);
+    }
+    return (_jsxs("video", { ...videoElementProps(resolved.props, elementProps), children: [resolved.tracks.map((track) => track.status === 'ok' ? (_jsx("track", { ...track.props }, track._key)) : null), children] }));
+}
+function videoElementProps(resolved, input) {
+    const forwarded = { ...input };
+    const protectedProps = forwarded;
+    for (const key of [
+        'src',
+        'poster',
+        'width',
+        'height',
+        'data-ss-e',
+        'children',
+        'dangerouslySetInnerHTML',
+    ]) {
+        delete protectedProps[key];
+    }
+    return {
+        ...cleanPreviewAttributes(forwarded),
+        src: resolved.src,
+        ...(resolved.poster ? { poster: resolved.poster } : {}),
+        width: resolved.width,
+        height: resolved.height,
+        crossOrigin: input.crossOrigin ?? resolved.crossOrigin,
+        controls: input.controls ?? resolved.controls,
+        preload: input.preload ?? resolved.preload,
+        playsInline: input.playsInline ?? resolved.playsInline,
+        ...('data-ss-e' in resolved ? { 'data-ss-e': resolved['data-ss-e'] } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,149 @@
 {
   "name": "@storystick/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-rc.0",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-server": "./dist/rendering.js",
+      "import": "./dist/index.js"
+    },
+    "./preview-text": {
+      "types": "./dist/preview-text-props.d.ts",
+      "import": "./dist/preview-text-props.js"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "import": "./dist/image.js"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "import": "./dist/file.js"
+    },
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "import": "./dist/video.js",
+      "default": "./dist/video.js"
+    },
+    "./slice": {
+      "types": "./dist/slice.d.ts",
+      "import": "./dist/slice.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "import": "./dist/link.js"
+    },
+    "./query": {
+      "types": "./dist/use-generated-query.d.ts",
+      "import": "./dist/use-generated-query.js"
+    },
+    "./rich-text": {
+      "types": "./dist/public-rich-text.d.ts",
+      "import": "./dist/public-rich-text.js"
+    },
+    "./slice-zone": {
+      "types": "./dist/public-slice-zone.d.ts",
+      "import": "./dist/public-slice-zone.js"
+    },
+    "./internal/preview-provenance": {
+      "types": "./dist/preview-provenance.d.ts",
+      "import": "./dist/preview-provenance.js"
+    },
+    "./internal/link-adapter": {
+      "types": "./dist/link-adapter.d.ts",
+      "import": "./dist/link-adapter.js"
+    },
+    "./internal/storystick-mark": {
+      "types": "./dist/storystick-mark.d.ts",
+      "import": "./dist/storystick-mark.js"
+    },
+    "./internal/preview-interaction-control": {
+      "types": "./dist/preview-interaction-control.d.ts",
+      "import": "./dist/preview-interaction-control.js"
+    },
+    "./internal/use-preview-perspective-intent": {
+      "types": "./dist/use-preview-perspective-intent.d.ts",
+      "import": "./dist/use-preview-perspective-intent.js"
+    },
+    "./internal/use-momentary-preview-navigate-mode": {
+      "types": "./dist/use-momentary-preview-navigate-mode.d.ts",
+      "import": "./dist/use-momentary-preview-navigate-mode.js"
+    },
+    "./internal/resize-edge": {
+      "types": "./dist/resize-edge.d.ts",
+      "import": "./dist/resize-edge.js"
+    },
+    "./internal/preview-toolbar-shell": {
+      "types": "./dist/preview-toolbar-shell.d.ts",
+      "import": "./dist/preview-toolbar-shell.js"
+    },
+    "./internal/preview-panel-state": {
+      "types": "./dist/preview-panel-state.d.ts",
+      "import": "./dist/preview-panel-state.js"
+    },
+    "./internal/preview-host": {
+      "types": "./dist/preview-host/preview-standalone-controls.d.ts",
+      "import": "./dist/preview-host/preview-standalone-controls.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "NOTICE",
+    "PUBLIC-API.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "tag": "beta"
+  },
+  "dependencies": {
+    "@tanstack/query-core": "5.101.4",
+    "@base-ui/react": "1.3.0",
+    "@storystick/preview": "0.2.0-rc.0",
+    "@storystick/media": "0.2.0-rc.0",
+    "@storystick/types": "0.1.0-rc.0",
+    "@storystick/client": "0.2.0-rc.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.13.10",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "jsdom": "^29.0.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstorystick/storystick.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://storystick.app",
+  "bugs": {
+    "url": "https://storystick.app"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/package-dist.mjs clean && tsc && node ../../scripts/package-dist.mjs seal",
+    "test": "vitest run",
+    "test:dist-fresh": "node ../../scripts/package-dist.mjs assert",
+    "test:types": "tsc -p tsconfig.type-tests.json --noEmit",
+    "test:watch": "vitest"
+  }
 }