@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/react/timeline/timeline-panel.tsx

@@ -13,6 +13,7 @@ import { motion } from 'motion/react';
 
 import type {
   ToolcraftPanelState,
+  ToolcraftState,
   ToolcraftTimelineKeyframeEasing,
   ToolcraftTimelineKeyframeGroup,
 } from '../../state/types';
@@ -39,8 +40,14 @@ import {
 import { timelineKeyframeRowHeightPx } from './timeline-panel-layout';
 import { useTimelineClock, useTimelineScrubber } from './timeline-playback-hooks';
 import { PanelContainer } from '../panel-host/panel-host';
+import { useToolcraftPanelBinding } from '../panel-host/use-toolcraft-panel-binding';
 import type { PanelPlacement, PanelStateChange } from '../panel-host/panel-host-types';
-import { useToolcraft } from '../app-shell/use-toolcraft';
+import { useToolcraftStore } from '../app-shell/toolcraft-store-context';
+import {
+  useToolcraftCommittedSelector,
+  useToolcraftDependencySelector,
+} from '../app-shell/toolcraft-selectors';
+import { useToolcraftDispatch } from '../app-shell/use-toolcraft';
 
 type TimelinePanelProps = {
   className?: string;
@@ -76,6 +83,12 @@ const timelinePanelResizeTransition = {
   duration: 0.16,
   ease: [0.22, 1, 0.36, 1],
 } as const;
+const playbackDependencies = [{ kind: 'playback' }] as const;
+const selectSchema = (state: ToolcraftState) => state.schema;
+const selectMediaAssets = (state: ToolcraftState) => state.mediaAssets;
+const selectCommittedTimeline = (state: ToolcraftState) => state.timeline;
+const selectCurrentTimeSeconds = (state: ToolcraftState) =>
+  state.timeline.currentTimeSeconds;
 
 function getTimelinePanelExpandedSize(keyframeGroups: readonly ToolcraftTimelineKeyframeGroup[]): {
   height: number;
@@ -106,24 +119,38 @@ export function TimelinePanel({
   panelState,
   variant = 'extended',
 }: TimelinePanelProps): React.JSX.Element | null {
-  const { dispatch, state } = useToolcraft();
+  const dispatch = useToolcraftDispatch();
+  const panelBinding = useToolcraftPanelBinding({
+    onPanelStateChange,
+    panelId: 'timeline',
+    panelState,
+  });
+  const resolvedPanelState = panelBinding.panelState;
+  const store = useToolcraftStore();
+  const schema = useToolcraftCommittedSelector(selectSchema);
+  const mediaAssets = useToolcraftCommittedSelector(selectMediaAssets);
+  const timeline = useToolcraftCommittedSelector(selectCommittedTimeline);
+  const currentTimeSeconds = useToolcraftDependencySelector(
+    selectCurrentTimeSeconds,
+    Object.is,
+    playbackDependencies,
+  );
 
-  if (!state.schema.panels.timeline) {
+  if (!schema.panels.timeline) {
     return null;
   }
 
-  const keyframesEnabled = state.schema.assembly.capabilities.includes('timeline.keyframes');
-  const playbackReady = isTimelineReadyForPlayback(state.schema, state.mediaAssets);
+  const keyframesEnabled = schema.assembly.capabilities.includes('timeline.keyframes');
+  const playbackReady = isTimelineReadyForPlayback(schema, mediaAssets);
 
   const {
-    currentTimeSeconds,
     durationSeconds,
     expanded,
     isLooping,
     isPlaying,
     keyframeGroups,
     selectedKeyframeId,
-  } = state.timeline;
+  } = timeline;
   const [defaultExpandedPending, setDefaultExpandedPending] = useState(defaultExpanded);
   const [isHoverPaused, setIsHoverPaused] = useState(false);
   const displayedIsPlaying = playbackReady && isPlaying;
@@ -131,15 +158,11 @@ export function TimelinePanel({
   const isExpanded = !isCompact && keyframesEnabled && (expanded || defaultExpandedPending);
   const expandedPanelSize = getTimelinePanelExpandedSize(keyframeGroups);
   const previousIsExpandedRef = useRef(isExpanded);
-  const timelineRef = useRef(state.timeline);
   const isExpandCollapseTransition = previousIsExpandedRef.current !== isExpanded;
   const timelinePanelTransition = isExpandCollapseTransition
     ? timelinePanelExpandCollapseTransition
     : timelinePanelResizeTransition;
 
-  useEffect(() => {
-    timelineRef.current = state.timeline;
-  }, [state.timeline]);
   useEffect(() => {
     previousIsExpandedRef.current = isExpanded;
   }, [isExpanded]);
@@ -167,23 +190,35 @@ export function TimelinePanel({
 
   const setCurrentTimeSeconds = useCallback(
     (nextValue: React.SetStateAction<number>): void => {
+      const currentTime = store.getState().timeline.currentTimeSeconds;
       const resolvedValue =
         typeof nextValue === 'function'
-          ? nextValue(timelineRef.current.currentTimeSeconds)
+          ? nextValue(currentTime)
           : nextValue;
 
-      dispatch({ currentTimeSeconds: resolvedValue, type: 'timeline.setCurrentTime' });
+      store.dispatchTransient({
+        currentTimeSeconds: resolvedValue,
+        type: 'timeline.setCurrentTime',
+      });
     },
-    [dispatch],
+    [store],
+  );
+  const commitCurrentTimeSeconds = useCallback((): void => {
+    store.commitTransient('playback');
+  }, [store]);
+  const getCurrentTimeSeconds = useCallback(
+    (): number => store.getState().timeline.currentTimeSeconds,
+    [store],
   );
   const setIsPlaying = useCallback(
     (nextValue: React.SetStateAction<boolean>): void => {
+      const currentIsPlaying = store.getState().timeline.isPlaying;
       const resolvedValue =
-        typeof nextValue === 'function' ? nextValue(timelineRef.current.isPlaying) : nextValue;
+        typeof nextValue === 'function' ? nextValue(currentIsPlaying) : nextValue;
 
       dispatch({ isPlaying: resolvedValue, type: 'timeline.setPlaying' });
     },
-    [dispatch],
+    [dispatch, store],
   );
   const setSelectedKeyframeId = useCallback(
     (keyframeId: string | null): void => {
@@ -192,6 +227,7 @@ export function TimelinePanel({
     [dispatch],
   );
   const scrubber = useTimelineScrubber({
+    commitCurrentTimeSeconds,
     currentTimeSeconds,
     disabled: !playbackReady,
     durationSeconds,
@@ -230,6 +266,7 @@ export function TimelinePanel({
 
   useTimelineClock({
     durationSeconds,
+    getCurrentTimeSeconds,
     isHoverPaused,
     isLooping,
     isPlaying: displayedIsPlaying,
@@ -354,6 +391,7 @@ export function TimelinePanel({
       data-scrubbing={scrubber.isScrubbing ? 'true' : 'false'}
       data-slot="timeline-panel"
       data-timeline-panel-variant={variant}
+      data-toolcraft-timeline-panel-variant={variant}
       initial={false}
       ref={timelineSurfaceRef}
       style={timelinePanelLayoutStyle}
@@ -395,6 +433,7 @@ export function TimelinePanel({
           playbackReady={playbackReady}
           onDurationCommit={commitDurationValue}
           onScrubKeyDown={scrubber.handleScrubKeyDown}
+          onScrubLostPointerCapture={scrubber.handleScrubLostPointerCapture}
           onScrubPointerDown={scrubber.handleScrubPointerDown}
           onScrubPointerMove={scrubber.handleScrubPointerMove}
           onScrubPointerUp={scrubber.handleScrubPointerUp}
@@ -405,6 +444,11 @@ export function TimelinePanel({
           onToggleLoop={() => dispatch({ type: 'timeline.toggleLoop' })}
           onTogglePlayback={() => {
             setIsHoverPaused(false);
+            if (displayedIsPlaying) {
+              setIsPlaying(false);
+              return;
+            }
+
             dispatch({ type: 'timeline.togglePlayback' });
           }}
           stripRef={scrubber.stripRef}
@@ -421,6 +465,7 @@ export function TimelinePanel({
             onDeleteKeyframe={deleteKeyframe}
             onKeyframeDragStart={() => setIsPlaying(false)}
             onKeyDown={scrubber.handleScrubKeyDown}
+            onLostPointerCapture={scrubber.handleScrubLostPointerCapture}
             onMoveKeyframe={moveKeyframe}
             onPointerDown={scrubber.handleScrubPointerDown}
             onPointerMove={scrubber.handleScrubPointerMove}
@@ -434,16 +479,24 @@ export function TimelinePanel({
     </motion.div>
   );
 
-  return (
+  const panel = (
     <PanelContainer
-      onPanelStateChange={onPanelStateChange}
-      panelState={panelState}
+      onPanelStateChange={panelBinding.onPanelStateChange}
+      panelState={resolvedPanelState}
       panelType="timeline"
       placement={resolvedPanelPlacement}
     >
       {timelineSurface}
     </PanelContainer>
   );
+
+  return resolvedPanelState.hidden ? (
+    <div data-toolcraft-timeline-panel-hidden="true" hidden>
+      {panel}
+    </div>
+  ) : (
+    panel
+  );
 }
 
 export { TimelinePanel as KeyframesPanel };

package/templates/runtime/react/timeline/timeline-playback-hooks.ts

@@ -11,6 +11,7 @@ import {
 
 type TimelineClockOptions = {
   durationSeconds: number;
+  getCurrentTimeSeconds: () => number;
   isHoverPaused: boolean;
   isLooping: boolean;
   isPlaying: boolean;
@@ -20,6 +21,7 @@ type TimelineClockOptions = {
 };
 
 type TimelineScrubberOptions = {
+  commitCurrentTimeSeconds: () => void;
   currentTimeSeconds: number;
   disabled?: boolean;
   durationSeconds: number;
@@ -29,6 +31,7 @@ type TimelineScrubberOptions = {
 
 type TimelineScrubberResult = {
   handleScrubKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+  handleScrubLostPointerCapture: () => void;
   handleScrubPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
   handleScrubPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
   handleScrubPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
@@ -66,6 +69,7 @@ function getKeyboardScrubTime({
 
 export function useTimelineClock({
   durationSeconds,
+  getCurrentTimeSeconds,
   isHoverPaused,
   isLooping,
   isPlaying,
@@ -90,24 +94,27 @@ export function useTimelineClock({
       const elapsedSeconds = (timestamp - previousTimestamp) / 1000;
 
       previousTimestamp = timestamp;
-      setCurrentTimeSeconds((currentValue) => {
-        const nextValue = currentValue + elapsedSeconds;
+      const nextValue = getCurrentTimeSeconds() + elapsedSeconds;
 
-        if (nextValue < durationSeconds) {
-          return nextValue;
-        }
+      if (nextValue < durationSeconds) {
+        setCurrentTimeSeconds(nextValue);
+        frame = window.requestAnimationFrame(tick);
+        return;
+      }
 
-        if (isLooping) {
-          return getToolcraftTimelineLoopTime({
+      if (isLooping) {
+        setCurrentTimeSeconds(
+          getToolcraftTimelineLoopTime({
             currentTimeSeconds: nextValue,
             durationSeconds,
-          });
-        }
-
-        setIsPlaying(false);
-        return durationSeconds;
-      });
-      frame = window.requestAnimationFrame(tick);
+          }),
+        );
+        frame = window.requestAnimationFrame(tick);
+        return;
+      }
+
+      setCurrentTimeSeconds(durationSeconds);
+      setIsPlaying(false);
     };
 
     frame = window.requestAnimationFrame(tick);
@@ -115,6 +122,7 @@ export function useTimelineClock({
     return () => window.cancelAnimationFrame(frame);
   }, [
     durationSeconds,
+    getCurrentTimeSeconds,
     isHoverPaused,
     isLooping,
     isPlaying,
@@ -125,6 +133,7 @@ export function useTimelineClock({
 }
 
 export function useTimelineScrubber({
+  commitCurrentTimeSeconds,
   currentTimeSeconds,
   disabled = false,
   durationSeconds,
@@ -132,13 +141,38 @@ export function useTimelineScrubber({
   setIsPlaying,
 }: TimelineScrubberOptions): TimelineScrubberResult {
   const [isScrubbing, setIsScrubbing] = useState(false);
+  const isScrubbingRef = useRef(false);
+  const isMountedRef = useRef(true);
+  const commitCurrentTimeSecondsRef = useRef(commitCurrentTimeSeconds);
   const stripRef = useRef<HTMLDivElement | null>(null);
+  commitCurrentTimeSecondsRef.current = commitCurrentTimeSeconds;
 
-  useEffect(() => {
-    if (disabled && isScrubbing) {
+  const finishScrub = React.useCallback((): void => {
+    if (!isScrubbingRef.current) {
+      return;
+    }
+
+    isScrubbingRef.current = false;
+    if (isMountedRef.current) {
       setIsScrubbing(false);
     }
-  }, [disabled, isScrubbing]);
+    commitCurrentTimeSecondsRef.current();
+  }, []);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    return () => {
+      isMountedRef.current = false;
+      finishScrub();
+    };
+  }, [finishScrub]);
+
+  useEffect(() => {
+    if (disabled) {
+      finishScrub();
+    }
+  }, [disabled, finishScrub]);
 
   const getScrubGeometry = (): { rect: DOMRect; trackStart: number; trackWidth: number } | null => {
     const rect = stripRef.current?.getBoundingClientRect();
@@ -212,6 +246,7 @@ export function useTimelineScrubber({
 
     event.preventDefault();
     setCurrentTimeSeconds(clampToolcraftTimelineTime(nextTime, durationSeconds));
+    commitCurrentTimeSeconds();
   };
   const handleScrubPointerDown = (event: React.PointerEvent<HTMLDivElement>): void => {
     if (disabled || !canStartScrubbingFromPointerEvent(event)) {
@@ -220,31 +255,33 @@ export function useTimelineScrubber({
 
     event.preventDefault();
     event.currentTarget.setPointerCapture(event.pointerId);
+    isScrubbingRef.current = true;
     setIsPlaying(false);
     setIsScrubbing(true);
     setCurrentTimeFromClientX(event.clientX);
   };
   const handleScrubPointerMove = (event: React.PointerEvent<HTMLDivElement>): void => {
-    if (!isScrubbing) {
+    if (!isScrubbingRef.current) {
       return;
     }
 
     setCurrentTimeFromClientX(event.clientX);
   };
   const handleScrubPointerUp = (event: React.PointerEvent<HTMLDivElement>): void => {
-    if (!isScrubbing) {
+    if (!isScrubbingRef.current) {
       return;
     }
 
+    finishScrub();
+
     if (event.currentTarget.hasPointerCapture(event.pointerId)) {
       event.currentTarget.releasePointerCapture(event.pointerId);
     }
-
-    setIsScrubbing(false);
   };
 
   return {
     handleScrubKeyDown,
+    handleScrubLostPointerCapture: finishScrub,
     handleScrubPointerDown,
     handleScrubPointerMove,
     handleScrubPointerUp,

package/templates/runtime/react/timeline/timeline-scrub-lifecycle.test.tsx

@@ -0,0 +1,154 @@
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import * as React from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../../schema/define-toolcraft";
+import type { ToolcraftExternalStore } from "../../state/toolcraft-external-store";
+import { ToolcraftRoot } from "../app-shell/toolcraft-root";
+import { useToolcraftStore } from "../app-shell/toolcraft-store-context";
+import { TimelinePanel } from "./timeline-panel";
+
+const persistenceKey = "toolcraft:scrub-lifecycle:state:v1";
+const scrubLifecycleSchema = defineToolcraft({
+  canvas: { enabled: true },
+  panels: { timeline: { mode: "playback" } },
+  persistence: {
+    include: ["panels", "timeline"],
+    key: persistenceKey,
+    storage: "localStorage",
+    version: 1,
+  },
+});
+
+function CaptureStore({
+  capture,
+}: {
+  capture: (store: ToolcraftExternalStore) => void;
+}): null {
+  capture(useToolcraftStore());
+  return null;
+}
+
+function ScrubLifecycleHarness({
+  capture,
+}: {
+  capture: (store: ToolcraftExternalStore) => void;
+}): React.JSX.Element {
+  const [visible, setVisible] = React.useState(true);
+
+  return (
+    <>
+      <button onClick={() => setVisible(false)} type="button">
+        Unmount timeline
+      </button>
+      {visible ? <TimelinePanel framed={false} /> : null}
+      <CaptureStore capture={capture} />
+    </>
+  );
+}
+
+function configureScrubber(scrubber: HTMLElement): void {
+  vi.spyOn(scrubber, "getBoundingClientRect").mockReturnValue({
+    bottom: 20,
+    height: 20,
+    left: 0,
+    right: 100,
+    toJSON: () => ({}),
+    top: 0,
+    width: 100,
+    x: 0,
+    y: 0,
+  });
+  Object.assign(scrubber, {
+    hasPointerCapture: () => true,
+    releasePointerCapture: vi.fn(),
+    setPointerCapture: vi.fn(),
+  });
+}
+
+function persistedTime(): number | undefined {
+  const persisted = JSON.parse(window.localStorage.getItem(persistenceKey) ?? "{}");
+  return persisted.state?.timeline?.currentTimeSeconds;
+}
+
+beforeAll(() => {
+  Object.defineProperty(window, "matchMedia", {
+    configurable: true,
+    value: () => ({
+      addEventListener: () => undefined,
+      addListener: () => undefined,
+      matches: false,
+      removeEventListener: () => undefined,
+      removeListener: () => undefined,
+    }),
+  });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  cleanup();
+  window.localStorage.clear();
+  vi.restoreAllMocks();
+});
+
+function renderLifecycleHarness(): {
+  getStore: () => ToolcraftExternalStore;
+} {
+  let store: ToolcraftExternalStore | undefined;
+  render(
+    <ToolcraftRoot
+      initialState={{ timeline: { isPlaying: false } }}
+      schema={scrubLifecycleSchema}
+    >
+      <ScrubLifecycleHarness capture={(value) => { store = value; }} />
+    </ToolcraftRoot>,
+  );
+  act(() => {
+    vi.advanceTimersByTime(120);
+  });
+
+  return { getStore: () => store! };
+}
+
+describe("timeline scrub lifecycle boundaries", () => {
+  it("commits and persists an active scrub when the timeline unmounts", () => {
+    vi.useFakeTimers();
+    const { getStore } = renderLifecycleHarness();
+    const scrubber = screen.getByRole("slider", { name: "Playback position" });
+    configureScrubber(scrubber);
+    fireEvent.pointerDown(scrubber, { clientX: 25, pointerId: 4 });
+    fireEvent.pointerMove(scrubber, { clientX: 50, pointerId: 4 });
+    const commitTransient = vi.spyOn(getStore(), "commitTransient");
+
+    fireEvent.click(screen.getByRole("button", { name: "Unmount timeline" }));
+
+    expect(commitTransient).toHaveBeenCalledTimes(1);
+    expect(commitTransient).toHaveBeenCalledWith("playback");
+    expect(getStore().getCommittedState().timeline.currentTimeSeconds).toBe(4);
+    act(() => {
+      vi.advanceTimersByTime(120);
+    });
+    expect(persistedTime()).toBe(4);
+  });
+
+  it("finishes lost pointer capture once even when pointerUp follows", () => {
+    vi.useFakeTimers();
+    const { getStore } = renderLifecycleHarness();
+    const scrubber = screen.getByRole("slider", { name: "Playback position" });
+    configureScrubber(scrubber);
+    fireEvent.pointerDown(scrubber, { clientX: 25, pointerId: 5 });
+    fireEvent.pointerMove(scrubber, { clientX: 75, pointerId: 5 });
+    const commitTransient = vi.spyOn(getStore(), "commitTransient");
+
+    fireEvent.lostPointerCapture(scrubber, { pointerId: 5 });
+
+    expect(getStore().getCommittedState().timeline.currentTimeSeconds).toBe(6);
+    fireEvent.pointerUp(scrubber, { clientX: 75, pointerId: 5 });
+    expect(commitTransient).toHaveBeenCalledTimes(1);
+    expect(commitTransient).toHaveBeenCalledWith("playback");
+    act(() => {
+      vi.advanceTimersByTime(120);
+    });
+    expect(persistedTime()).toBe(6);
+  });
+});

package/templates/runtime/rendering/index.ts

@@ -0,0 +1,3 @@
+export * from "./renderer-pipeline-registration";
+export * from "./renderer-pipeline-runtime";
+export * from "./renderer-pipeline-runtime-owner";