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

package/dist/use-preview-perspective-intent.js

@@ -0,0 +1,227 @@
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import { previewPerspectivesEqual } from '@storystick/preview/runtime/preview-perspective-alignment';
+const DEFAULT_PERSPECTIVE_INTENT_TIMEOUT_MS = 10_000;
+export function isAcceptedPreviewPerspectiveIntent(result) {
+    return result.status === 'applied' || result.status === 'local-noop';
+}
+/**
+ * Event-owned lifecycle for an explicit perspective gesture. React effects
+ * may reconcile the accepted read context, but they never create this intent.
+ */
+export function usePreviewPerspectiveIntent(inputs) {
+    const inputsRef = useRef(inputs);
+    useLayoutEffect(() => {
+        inputsRef.current = inputs;
+    }, [inputs]);
+    const pendingRef = useRef(null);
+    const earlyLifecycleRef = useRef(new Map());
+    const observeLifecycleRef = useRef(null);
+    const settle = useCallback((pending, result, options) => {
+        if (pending.settled)
+            return;
+        pending.settled = true;
+        clearTimeout(pending.timeout);
+        earlyLifecycleRef.current.clear();
+        if (pendingRef.current === pending)
+            pendingRef.current = null;
+        if (options.clearTransition)
+            inputsRef.current.clearTransition();
+        if (options.terminalFailure) {
+            inputsRef.current.onTerminalFailure?.(options.terminalFailure);
+        }
+        const commandId = ('commandId' in result ? result.commandId : null) ?? pending.commandId;
+        switch (result.status) {
+            case 'applied':
+            case 'local-noop':
+                inputsRef.current.onStateChange?.({
+                    kind: 'accepted',
+                    acceptance: result.status,
+                    perspective: pending.perspective,
+                    generation: pending.transition.generation,
+                    commandId,
+                    context: result.context,
+                });
+                break;
+            case 'conflict':
+                inputsRef.current.onStateChange?.({
+                    kind: 'conflict',
+                    perspective: pending.perspective,
+                    generation: pending.transition.generation,
+                    commandId,
+                    context: result.context,
+                });
+                break;
+            case 'unavailable':
+            case 'superseded':
+                inputsRef.current.onStateChange?.({
+                    kind: result.status,
+                    perspective: pending.perspective,
+                    generation: pending.transition.generation,
+                    commandId,
+                });
+                break;
+        }
+        pending.resolve(result);
+    }, []);
+    const dispatch = useCallback((pending) => {
+        earlyLifecycleRef.current.clear();
+        void inputsRef.current
+            .dispatch(pending.perspective)
+            .then(({ commandId }) => {
+            if (commandId !== null) {
+                inputsRef.current.registerCommand(commandId, pending.transition);
+            }
+            if (pendingRef.current !== pending || pending.settled)
+                return;
+            if (commandId === null) {
+                settle(pending, { status: 'unavailable', commandId: null }, { clearTransition: true, terminalFailure: 'unavailable' });
+                return;
+            }
+            pending.commandId = commandId;
+            inputsRef.current.onStateChange?.({
+                kind: 'pending',
+                perspective: pending.perspective,
+                generation: pending.transition.generation,
+                commandId,
+            });
+            const earlyLifecycle = earlyLifecycleRef.current.get(commandId);
+            earlyLifecycleRef.current.clear();
+            if (earlyLifecycle !== undefined) {
+                observeLifecycleRef.current?.(earlyLifecycle);
+            }
+        })
+            .catch(() => {
+            if (pendingRef.current !== pending || pending.settled)
+                return;
+            settle(pending, { status: 'unavailable', commandId: pending.commandId }, { clearTransition: true, terminalFailure: 'unavailable' });
+        });
+    }, [settle]);
+    const changePerspective = useCallback((perspective) => {
+        const previous = pendingRef.current;
+        if (previous !== null &&
+            previewPerspectivesEqual(previous.perspective, perspective)) {
+            return previous.promise;
+        }
+        if (previous !== null) {
+            settle(previous, { status: 'superseded', commandId: previous.commandId }, { clearTransition: false });
+        }
+        const sessionId = inputsRef.current.getSessionId();
+        const context = inputsRef.current.getReadContext();
+        if (sessionId === null || context === null) {
+            inputsRef.current.onTerminalFailure?.('unavailable');
+            inputsRef.current.onStateChange?.({
+                kind: 'unavailable',
+                perspective,
+                generation: null,
+                commandId: null,
+            });
+            return Promise.resolve({ status: 'unavailable', commandId: null });
+        }
+        if (previous === null &&
+            previewPerspectivesEqual(context.perspective, perspective)) {
+            inputsRef.current.onAccepted?.(context);
+            inputsRef.current.onStateChange?.({
+                kind: 'accepted',
+                acceptance: 'local-noop',
+                perspective,
+                generation: null,
+                commandId: null,
+                context,
+            });
+            return Promise.resolve({ status: 'local-noop', context });
+        }
+        const transition = inputsRef.current.beginTransition(perspective);
+        let resolve;
+        const promise = new Promise((done) => {
+            resolve = done;
+        });
+        const timeoutMs = inputsRef.current.timeoutMs ?? DEFAULT_PERSPECTIVE_INTENT_TIMEOUT_MS;
+        const pending = {
+            perspective,
+            transition,
+            promise,
+            resolve,
+            commandId: null,
+            contextId: context.contextId,
+            timeout: setTimeout(() => {
+                settle(pending, { status: 'unavailable', commandId: pending.commandId }, { clearTransition: true, terminalFailure: 'unavailable' });
+            }, timeoutMs),
+            settled: false,
+        };
+        pendingRef.current = pending;
+        inputsRef.current.onStateChange?.({
+            kind: 'pending',
+            perspective,
+            generation: transition.generation,
+            commandId: null,
+        });
+        dispatch(pending);
+        return promise;
+    }, [dispatch, settle]);
+    const observeLifecycle = useCallback((payload) => {
+        const pending = pendingRef.current;
+        const outcome = payload.contextCommand;
+        if (pending === null || outcome === undefined) {
+            return false;
+        }
+        if (pending.commandId === null) {
+            earlyLifecycleRef.current.set(outcome.commandId, payload);
+            return true;
+        }
+        if (outcome.commandId !== pending.commandId)
+            return false;
+        if (outcome.status === 'unavailable' ||
+            payload.readContext === undefined) {
+            settle(pending, { status: 'unavailable', commandId: outcome.commandId }, { clearTransition: true, terminalFailure: 'unavailable' });
+            return true;
+        }
+        // Application and current authority are separate facts. A replay may
+        // acknowledge r while the shared context has already advanced to r+1.
+        const current = inputsRef.current.getReadContext();
+        const context = current?.contextId === payload.readContext.contextId &&
+            current.revision > payload.readContext.revision
+            ? current
+            : payload.readContext;
+        if ((current && current.contextId !== pending.contextId) ||
+            context.contextId !== pending.contextId ||
+            (outcome.status === 'applied' &&
+                outcome.contextId !== pending.contextId)) {
+            settle(pending, { status: 'superseded', commandId: outcome.commandId }, { clearTransition: true });
+            return true;
+        }
+        if (outcome.status === 'applied' &&
+            context.revision >= outcome.appliedRevision &&
+            previewPerspectivesEqual(context.perspective, pending.perspective)) {
+            inputsRef.current.onAccepted?.(context);
+            settle(pending, {
+                status: 'applied',
+                commandId: outcome.commandId,
+                context,
+                appliedRevision: outcome.appliedRevision,
+            }, { clearTransition: false });
+            return true;
+        }
+        if (previewPerspectivesEqual(context.perspective, pending.perspective)) {
+            inputsRef.current.onAccepted?.(context);
+            settle(pending, { status: 'local-noop', context }, { clearTransition: true });
+            return true;
+        }
+        // A conflict observes another accepted gesture. Never silently replay ours
+        // against its newer revision: that would overwrite the other editor.
+        settle(pending, {
+            status: 'conflict', commandId: outcome.commandId, context,
+        }, { clearTransition: true, terminalFailure: 'conflict' });
+        return true;
+    }, [dispatch, settle]);
+    useLayoutEffect(() => {
+        observeLifecycleRef.current = observeLifecycle;
+    }, [observeLifecycle]);
+    const cancelPending = useCallback(() => {
+        const pending = pendingRef.current;
+        if (pending === null)
+            return;
+        settle(pending, { status: 'superseded', commandId: pending.commandId }, { clearTransition: false });
+    }, [settle]);
+    useEffect(() => cancelPending, [cancelPending]);
+    return { changePerspective, observeLifecycle, cancelPending };
+}

package/dist/use-preview-pointer-drag.d.ts

@@ -0,0 +1,16 @@
+import { type PointerEvent as ReactPointerEvent, type MouseEvent as ReactMouseEvent } from 'react';
+import type { Point } from './preview-toolbar-layout.js';
+/** One captured pointer, one paint per frame, one committed position on release. */
+export declare function usePreviewPointerDrag({ onStart, onMove, onEnd, onCancel }: {
+    onStart(event: ReactPointerEvent<HTMLElement>): void;
+    onMove(delta: Point): void;
+    onEnd(delta: Point): void;
+    onCancel(): void;
+}): {
+    onPointerDown(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerMove(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerUp(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerCancel(event: ReactPointerEvent<HTMLElement>): void;
+    onLostPointerCapture(event: ReactPointerEvent<HTMLElement>): void;
+    onClickCapture(event: ReactMouseEvent<HTMLElement>): void;
+};

package/dist/use-preview-pointer-drag.js

@@ -0,0 +1,98 @@
+import { useEffect, useRef } from 'react';
+/** One captured pointer, one paint per frame, one committed position on release. */
+export function usePreviewPointerDrag({ onStart, onMove, onEnd, onCancel }) {
+    const callbacks = useRef({ onStart, onMove, onEnd, onCancel });
+    callbacks.current = { onStart, onMove, onEnd, onCancel };
+    const session = useRef(null);
+    const suppressClick = useRef(false);
+    function finish(cancel) {
+        const current = session.current;
+        if (!current)
+            return;
+        session.current = null;
+        if (current.frame !== null)
+            current.window.cancelAnimationFrame(current.frame);
+        current.cleanup();
+        if (current.element.hasPointerCapture(current.pointer))
+            current.element.releasePointerCapture(current.pointer);
+        if (current.dragging) {
+            suppressClick.current = true;
+            if (cancel)
+                callbacks.current.onCancel();
+            else
+                callbacks.current.onEnd(current.delta);
+        }
+    }
+    useEffect(() => () => finish(true), []);
+    return {
+        onPointerDown(event) {
+            if (event.button !== 0 || event.isPrimary === false || session.current)
+                return;
+            suppressClick.current = false;
+            const element = event.currentTarget;
+            const win = element.ownerDocument.defaultView;
+            const cancel = () => finish(true);
+            const escape = (e) => {
+                if (e.key !== 'Escape')
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                cancel();
+            };
+            element.setPointerCapture(event.pointerId);
+            session.current = { pointer: event.pointerId, start: { x: event.clientX, y: event.clientY },
+                delta: { x: 0, y: 0 }, dragging: false, element, window: win, frame: null,
+                cleanup: () => {
+                    win.removeEventListener('blur', cancel);
+                    win.removeEventListener('resize', cancel);
+                    win.visualViewport?.removeEventListener('resize', cancel);
+                    win.visualViewport?.removeEventListener('scroll', cancel);
+                    win.removeEventListener('keydown', escape, true);
+                } };
+            win.addEventListener('blur', cancel);
+            win.addEventListener('resize', cancel);
+            win.visualViewport?.addEventListener('resize', cancel);
+            win.visualViewport?.addEventListener('scroll', cancel);
+            win.addEventListener('keydown', escape, true);
+        },
+        onPointerMove(event) {
+            const current = session.current;
+            if (!current || current.pointer !== event.pointerId)
+                return;
+            current.delta = { x: event.clientX - current.start.x, y: event.clientY - current.start.y };
+            if (!current.dragging) {
+                if (Math.hypot(current.delta.x, current.delta.y) < 5)
+                    return;
+                current.dragging = true;
+                callbacks.current.onStart(event);
+            }
+            event.preventDefault();
+            if (current.frame === null)
+                current.frame = current.window.requestAnimationFrame(() => {
+                    current.frame = null;
+                    callbacks.current.onMove(current.delta);
+                });
+        },
+        onPointerUp(event) {
+            if (session.current?.pointer !== event.pointerId)
+                return;
+            session.current.delta = { x: event.clientX - session.current.start.x, y: event.clientY - session.current.start.y };
+            finish(false);
+        },
+        onPointerCancel(event) {
+            if (session.current?.pointer === event.pointerId)
+                finish(true);
+        },
+        onLostPointerCapture(event) {
+            if (session.current?.pointer === event.pointerId)
+                finish(true);
+        },
+        onClickCapture(event) {
+            if (!suppressClick.current || event.detail === 0)
+                return;
+            suppressClick.current = false;
+            event.preventDefault();
+            event.stopPropagation();
+        },
+    };
+}

package/dist/use-preview-toolbar-layout.d.ts

@@ -0,0 +1,36 @@
+import { type KeyboardEvent } from 'react';
+import { type Rect, type ResizeEdge } from './preview-toolbar-layout.js';
+export declare function usePreviewToolbarLayout(closeMenu: () => void): {
+    bubble: import("react").RefObject<HTMLButtonElement | null>;
+    panel: import("react").RefObject<HTMLElement | null>;
+    dock: "bottom" | "left" | "right";
+    bubbleDrag: {
+        onPointerDown(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerMove(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerUp(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerCancel(event: import("react").PointerEvent<HTMLElement>): void;
+        onLostPointerCapture(event: import("react").PointerEvent<HTMLElement>): void;
+        onClickCapture(event: import("react").MouseEvent<HTMLElement>): void;
+    };
+    panelDrag: {
+        onPointerDown(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerMove(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerUp(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerCancel(event: import("react").PointerEvent<HTMLElement>): void;
+        onLostPointerCapture(event: import("react").PointerEvent<HTMLElement>): void;
+        onClickCapture(event: import("react").MouseEvent<HTMLElement>): void;
+    };
+    onBubbleKeyDown: (event: KeyboardEvent) => void;
+    onPanelKeyDown: (event: KeyboardEvent) => void;
+    panelBounds: Rect;
+    resizeEdges: readonly ResizeEdge[];
+    resizeHandleProps: (edge: ResizeEdge) => {
+        onKeyDown(event: KeyboardEvent): void;
+        onPointerDown(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerMove(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerUp(event: import("react").PointerEvent<HTMLElement>): void;
+        onPointerCancel(event: import("react").PointerEvent<HTMLElement>): void;
+        onLostPointerCapture(event: import("react").PointerEvent<HTMLElement>): void;
+        onClickCapture(event: import("react").MouseEvent<HTMLElement>): void;
+    };
+};

package/dist/use-preview-toolbar-layout.js

@@ -0,0 +1,141 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { bubbleRect, panelRect, panelResizeEdges, parseToolbarLayout, placePanel, resizePanel, snapBubble } from './preview-toolbar-layout.js';
+import { usePreviewPointerDrag } from './use-preview-pointer-drag.js';
+const STORAGE_KEY = 'storystick.preview.layout.v2';
+function readViewport() {
+    const v = window.visualViewport;
+    return { x: v?.offsetLeft ?? 0, y: v?.offsetTop ?? 0, width: v?.width ?? window.innerWidth, height: v?.height ?? window.innerHeight };
+}
+function paint(element, rect) {
+    if (!element)
+        return;
+    element.style.transform = `translate3d(${rect.x}px, ${rect.y}px, 0)`;
+    element.style.width = `${rect.width}px`;
+    element.style.height = `${rect.height}px`;
+}
+const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+function keyboardDelta(event) {
+    const step = event.shiftKey ? 80 : 20;
+    return { ArrowLeft: { x: -step, y: 0 }, ArrowRight: { x: step, y: 0 }, ArrowUp: { x: 0, y: -step }, ArrowDown: { x: 0, y: step } }[event.key];
+}
+export function usePreviewToolbarLayout(closeMenu) {
+    const bubble = useRef(null);
+    const panel = useRef(null);
+    const [viewport, setViewport] = useState(readViewport);
+    const [layout, setLayout] = useState(() => {
+        try {
+            return parseToolbarLayout(localStorage.getItem(STORAGE_KEY));
+        }
+        catch {
+            return parseToolbarLayout(null);
+        }
+    });
+    const bubbleStart = useRef({ x: 0, y: 0 });
+    const panelStart = useRef({ x: 0, y: 0 });
+    const resizeStart = useRef(null);
+    const bubbleBounds = bubbleRect(layout.bubble, viewport);
+    const panelBounds = panelRect(layout.panel, viewport, layout.bubble);
+    function commit(next) {
+        setLayout(next);
+        try {
+            localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+        }
+        catch { /* Positioning works without storage. */ }
+    }
+    function restore() {
+        bubble.current?.removeAttribute('data-dragging');
+        panel.current?.removeAttribute('data-dragging');
+        panel.current?.removeAttribute('data-resizing');
+        paint(bubble.current, bubbleBounds);
+        paint(panel.current, panelBounds);
+    }
+    useLayoutEffect(restore, [layout, viewport]);
+    useEffect(() => {
+        const resize = () => setViewport(readViewport());
+        window.addEventListener('resize', resize);
+        window.visualViewport?.addEventListener('resize', resize);
+        window.visualViewport?.addEventListener('scroll', resize);
+        return () => {
+            window.removeEventListener('resize', resize);
+            window.visualViewport?.removeEventListener('resize', resize);
+            window.visualViewport?.removeEventListener('scroll', resize);
+        };
+    }, []);
+    const bubbleDrag = usePreviewPointerDrag({
+        onStart() { bubbleStart.current = bubbleBounds; bubble.current?.setAttribute('data-dragging', ''); closeMenu(); },
+        onMove(delta) {
+            const p = add(bubbleStart.current, delta);
+            paint(bubble.current, { ...bubbleBounds,
+                x: Math.max(viewport.x, Math.min(viewport.x + viewport.width - bubbleBounds.width, p.x)),
+                y: Math.max(viewport.y, Math.min(viewport.y + viewport.height - bubbleBounds.height, p.y)) });
+        },
+        onEnd(delta) {
+            bubble.current?.removeAttribute('data-dragging');
+            commit({ ...layout, bubble: snapBubble(add(bubbleStart.current, delta), viewport) });
+        },
+        onCancel: restore,
+    });
+    const panelDrag = usePreviewPointerDrag({
+        onStart() { panelStart.current = panelBounds; panel.current?.setAttribute('data-dragging', ''); closeMenu(); },
+        onMove(delta) { paint(panel.current, panelRect(placePanel(add(panelStart.current, delta), layout.panel, viewport, layout.bubble, false), viewport, layout.bubble)); },
+        onEnd(delta) {
+            panel.current?.removeAttribute('data-dragging');
+            commit({ ...layout, panel: placePanel(add(panelStart.current, delta), layout.panel, viewport, layout.bubble, true) });
+        },
+        onCancel: restore,
+    });
+    function resized(delta) {
+        const start = resizeStart.current;
+        return resizePanel(layout.panel, start.rect, start.edge, delta, viewport, layout.bubble);
+    }
+    const panelResize = usePreviewPointerDrag({
+        onStart(event) {
+            resizeStart.current = { rect: panelBounds, edge: event.currentTarget.dataset.resizeEdge };
+            panel.current?.setAttribute('data-resizing', '');
+            closeMenu();
+        },
+        onMove(delta) { paint(panel.current, panelRect(resized(delta), viewport, layout.bubble)); },
+        onEnd(delta) {
+            panel.current?.removeAttribute('data-resizing');
+            commit({ ...layout, panel: resized(delta) });
+        },
+        onCancel: restore,
+    });
+    function resizeHandleProps(edge) {
+        return { ...panelResize, onKeyDown(event) {
+                const delta = keyboardDelta(event);
+                if (!delta)
+                    return;
+                event.preventDefault();
+                commit({ ...layout, panel: resizePanel(layout.panel, panelBounds, edge, delta, viewport, layout.bubble) });
+            } };
+    }
+    function onBubbleKeyDown(event) {
+        if (!event.altKey || !['ArrowLeft', 'ArrowRight', 'ArrowDown', 'ArrowUp'].includes(event.key))
+            return;
+        event.preventDefault();
+        closeMenu();
+        const edge = event.key === 'ArrowLeft' ? 'left' : event.key === 'ArrowRight' ? 'right' : event.key === 'ArrowDown' ? 'bottom' : layout.bubble.edge;
+        commit({ ...layout, bubble: { edge, offset: event.key === 'ArrowUp' ? Math.max(0, layout.bubble.offset - .1) : .5 } });
+    }
+    function onPanelKeyDown(event) {
+        if (event.altKey && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+            event.preventDefault();
+            const x = layout.panel.kind === 'docked' ? layout.panel.edge === 'left' ? 0 : 1 : layout.panel.x;
+            commit({ ...layout, panel: { width: layout.panel.width, height: layout.panel.height, kind: 'stretched', x } });
+            return;
+        }
+        if (event.key === 'Home' || event.key === 'End') {
+            event.preventDefault();
+            commit({ ...layout, panel: { width: layout.panel.width, height: layout.panel.height, kind: 'docked', edge: event.key === 'Home' ? 'left' : 'right' } });
+            return;
+        }
+        const delta = keyboardDelta(event);
+        if (!delta)
+            return;
+        event.preventDefault();
+        commit({ ...layout, panel: placePanel(add(panelBounds, delta), layout.panel, viewport, layout.bubble, false) });
+    }
+    return { bubble, panel, dock: layout.bubble.edge, bubbleDrag, panelDrag, onBubbleKeyDown, onPanelKeyDown,
+        panelBounds, resizeEdges: panelResizeEdges(layout.panel), resizeHandleProps };
+}

package/dist/use-render-mode-debounce.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function tryWrapResultForPreview<T>(docs: T): T;
+export declare function useRenderModeDebounce<T>(value: T): T;
+/**
+ * Test-only — flushes the dynamic-import cache so tests can inject
+ * fake preview modules. Not exported from index.ts.
+ */
+export declare function _resetPreviewModuleCacheForTests(): void;