@pixel-point/toolcraft 0.0.2

package/templates/runtime/state/create-template-state.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "./create-template-state";
+
+describe("createToolcraftState", () => {
+  it("initializes values from control defaults by target", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
+                },
+                prompt: {
+                  defaultValue: "",
+                  target: "generation.prompt",
+                  type: "textarea",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.values).toEqual({
+      "generation.prompt": "",
+      "selectedLayer.opacity": 75,
+    });
+    expect(state.defaults).toEqual(state.values);
+    expect(state.values).not.toBe(state.defaults);
+  });
+
+  it("initializes editable canvas size control defaults only for editable output apps", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true, sizing: { mode: "editable-output" } },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.values).toMatchObject({
+      "canvas.size.height": 1024,
+      "canvas.size.width": 1024,
+    });
+  });
+
+  it("initializes canvas state from resolved canvas size", () => {
+    const size = { width: 1200, height: 900, unit: "px" } as const;
+    const app = defineToolcraft({
+      canvas: { enabled: true, size },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.canvas.size).toEqual(size);
+    expect(state.canvas.zoom).toBe(70);
+  });
+
+  it("preserves seeded canvas width", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app, {
+      canvas: {
+        size: { width: 640, height: 900, unit: "px" },
+      },
+    });
+
+    expect(state.canvas.size).toEqual({ width: 640, height: 900, unit: "px" });
+  });
+
+  it("initializes default panel offsets", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.panels).toEqual({
+      controls: { offset: { x: 0, y: 0 } },
+      layers: { offset: { x: 0, y: 0 } },
+      timeline: { offset: { x: 0, y: 0 } },
+      toolbar: { offset: { x: 0, y: 0 } },
+    });
+  });
+
+  it("initializes media and layer state as empty", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.layers).toEqual([]);
+    expect(state.mediaAssets).toEqual([]);
+    expect(state.selectedLayerId).toBeNull();
+  });
+
+  it("accepts seeded runtime layer state", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app, {
+      layers: [
+        {
+          displayName: "Layer 1",
+          id: "layer-1",
+          kind: "layer",
+          name: "layer-1",
+          visible: true,
+        },
+      ],
+      selectedLayerId: "layer-1",
+    });
+
+    expect(state.layers).toHaveLength(1);
+    expect(state.layers[0]?.displayName).toBe("Layer 1");
+    expect(state.selectedLayerId).toBe("layer-1");
+    expect(state.history.undo).toEqual([]);
+  });
+
+  it("creates timeline runtime state", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app, {
+      timeline: {
+        currentTimeSeconds: 2,
+        durationSeconds: 10,
+        isPlaying: false,
+      },
+    });
+
+    expect(state.timeline.currentTimeSeconds).toBe(2);
+    expect(state.timeline.durationSeconds).toBe(10);
+    expect(state.timeline.expanded).toBe(false);
+    expect(state.timeline.isLooping).toBe(true);
+    expect(state.timeline.isPlaying).toBe(false);
+    expect(state.timeline.keyframeGroups).toEqual([]);
+  });
+
+  it("keeps upload-dependent intrinsic-media timelines paused until media exists", () => {
+    const app = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "intrinsic-media" },
+        upload: true,
+      },
+      panels: {
+        timeline: { mode: "playback" },
+      },
+    });
+
+    const state = createToolcraftState(app);
+
+    expect(state.timeline.currentTimeSeconds).toBe(0);
+    expect(state.timeline.isPlaying).toBe(false);
+  });
+
+  it("allows upload-dependent intrinsic-media timelines to start ready when media is seeded", () => {
+    const app = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "intrinsic-media" },
+        upload: true,
+      },
+      panels: {
+        timeline: { mode: "playback" },
+      },
+    });
+
+    const state = createToolcraftState(app, {
+      mediaAssets: [
+        {
+          dataUrl: "data:image/png;base64,AAAA",
+          fileName: "source.png",
+          id: "media-1",
+          layerId: "layer-1",
+          mimeType: "image/png",
+          position: { x: 0, y: 0 },
+          size: { height: 320, unit: "px", width: 512 },
+        },
+      ],
+    });
+
+    expect(state.timeline.isPlaying).toBe(true);
+  });
+
+  it("accepts seeded timeline keyframes without making them runtime defaults", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    const state = createToolcraftState(app, {
+      timeline: {
+        keyframeGroups: [
+          {
+            controlId: "opacity",
+            keyframes: [
+              {
+                controlId: "opacity",
+                controlLabel: "Opacity",
+                easing: { controlPoints: [0.65, 0, 0.35, 1], type: "bezier" },
+                id: "opacity-0",
+                timeSeconds: 0,
+                valueLabel: "Opacity 75%",
+              },
+            ],
+            label: "Opacity",
+          },
+        ],
+      },
+    });
+
+    expect(state.timeline.keyframeGroups.map((group) => group.controlId)).toEqual(["opacity"]);
+  });
+});

package/templates/runtime/state/create-template-state.ts

@@ -0,0 +1,95 @@
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type {
+  ToolcraftInitialState,
+  ToolcraftState,
+  ToolcraftTimelineKeyframeGroup,
+  ToolcraftTimelineState,
+} from "./types";
+import { toolcraftCanvasZoomDefault } from "./canvas-zoom";
+import { getMediaReadyTimelineState } from "./timeline-readiness";
+
+function cloneTimelineKeyframeGroups(
+  keyframeGroups: readonly ToolcraftTimelineKeyframeGroup[],
+): ToolcraftTimelineKeyframeGroup[] {
+  return keyframeGroups.map((group) => ({
+    ...group,
+    keyframes: group.keyframes.map((keyframe) => ({
+      ...keyframe,
+      easing:
+        keyframe.easing?.type === "bezier"
+          ? {
+              controlPoints: [...keyframe.easing.controlPoints],
+              type: "bezier",
+            }
+          : keyframe.easing,
+    })),
+  }));
+}
+
+function createDefaultTimelineState(
+  timeline?: Partial<ToolcraftTimelineState>,
+): ToolcraftTimelineState {
+  return {
+    currentTimeSeconds: 0,
+    durationSeconds: 8,
+    expanded: false,
+    isLooping: true,
+    isPlaying: true,
+    selectedKeyframeId: null,
+    ...timeline,
+    keyframeGroups: cloneTimelineKeyframeGroups(timeline?.keyframeGroups ?? []),
+  };
+}
+
+export function createToolcraftState(
+  schema: ResolvedToolcraftAppSchema,
+  initialState: ToolcraftInitialState = {},
+): ToolcraftState {
+  const defaults: Record<string, unknown> = {};
+  const mediaAssets = initialState.mediaAssets ?? [];
+  const timeline = getMediaReadyTimelineState(
+    schema,
+    createDefaultTimelineState(initialState.timeline),
+    mediaAssets,
+  );
+
+  for (const section of schema.panels.controls?.sections ?? []) {
+    for (const control of Object.values(section.controls)) {
+      defaults[control.target] = control.defaultValue;
+    }
+  }
+
+  const panels: ToolcraftState["panels"] = {
+    controls: { offset: { x: 0, y: 0 } },
+    layers: { offset: { x: 0, y: 0 } },
+    timeline: { offset: { x: 0, y: 0 } },
+    toolbar: { offset: { x: 0, y: 0 } },
+  };
+  const initialCanvas = {
+    offset: { x: 0, y: 0 },
+    size: schema.canvas.size,
+    zoom: toolcraftCanvasZoomDefault,
+    ...initialState.canvas,
+  };
+
+  return {
+    canvas: initialCanvas,
+    defaults,
+    history: {
+      redo: [],
+      undo: [],
+    },
+    layers: initialState.layers ?? [],
+    mediaAssets,
+    panels: {
+      controls: { ...panels.controls, ...initialState.panels?.controls },
+      layers: { ...panels.layers, ...initialState.panels?.layers },
+      timeline: { ...panels.timeline, ...initialState.panels?.timeline },
+      toolbar: { ...panels.toolbar, ...initialState.panels?.toolbar },
+    },
+    schema,
+    selectedLayerId: initialState.selectedLayerId ?? null,
+    timeline,
+    values: { ...defaults, ...initialState.values },
+  };
+}

package/templates/runtime/state/keyframe-evaluation.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "./create-template-state";
+import {
+  evaluateToolcraftTimelineValue,
+  evaluateToolcraftTimelineValues,
+} from "./keyframe-evaluation";
+
+function createKeyframedState() {
+  const app = defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              opacity: {
+                defaultValue: 0,
+                target: "shape.opacity",
+                type: "slider",
+              },
+              position: {
+                defaultValue: { x: 0, y: 0 },
+                target: "shape.position",
+                type: "vector",
+              },
+              preset: {
+                defaultValue: "linear",
+                options: [
+                  { label: "Linear", value: "linear" },
+                  { label: "Radial", value: "radial" },
+                ],
+                target: "shape.preset",
+                type: "select",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+      timeline: { mode: "keyframes" },
+    },
+  });
+
+  return createToolcraftState(app, {
+    timeline: {
+      currentTimeSeconds: 4,
+      durationSeconds: 8,
+      keyframeGroups: [
+        {
+          controlId: "shape.opacity",
+          keyframes: [
+            {
+              controlId: "shape.opacity",
+              controlLabel: "Opacity",
+              id: "shape.opacity::0",
+              timeSeconds: 0,
+              value: 0,
+              valueLabel: "0%",
+            },
+            {
+              controlId: "shape.opacity",
+              controlLabel: "Opacity",
+              id: "shape.opacity::8",
+              timeSeconds: 8,
+              value: 100,
+              valueLabel: "100%",
+            },
+          ],
+          label: "Opacity",
+        },
+        {
+          controlId: "shape.position",
+          keyframes: [
+            {
+              controlId: "shape.position",
+              controlLabel: "Position",
+              id: "shape.position::0",
+              timeSeconds: 0,
+              value: { x: 0, y: 10 },
+              valueLabel: "0.00, 10.00",
+            },
+            {
+              controlId: "shape.position",
+              controlLabel: "Position",
+              id: "shape.position::8",
+              timeSeconds: 8,
+              value: { x: 100, y: 30 },
+              valueLabel: "100.00, 30.00",
+            },
+          ],
+          label: "Position",
+        },
+        {
+          controlId: "shape.preset",
+          keyframes: [
+            {
+              controlId: "shape.preset",
+              controlLabel: "Preset",
+              id: "shape.preset::0",
+              timeSeconds: 0,
+              value: "linear",
+              valueLabel: "Linear",
+            },
+            {
+              controlId: "shape.preset",
+              controlLabel: "Preset",
+              id: "shape.preset::8",
+              timeSeconds: 8,
+              value: "radial",
+              valueLabel: "Radial",
+            },
+          ],
+          label: "Preset",
+        },
+      ],
+    },
+  });
+}
+
+describe("Toolcraft keyframe evaluation", () => {
+  it("evaluates typed keyframe values at the current timeline time", () => {
+    const state = createKeyframedState();
+    const values = evaluateToolcraftTimelineValues(state);
+    const position = values["shape.position"] as { x: number; y: number };
+
+    expect(values["shape.opacity"]).toBeCloseTo(50, 5);
+    expect(position.x).toBeCloseTo(50, 5);
+    expect(position.y).toBeCloseTo(20, 5);
+    expect(values["shape.preset"]).toBe("linear");
+  });
+
+  it("evaluates a single target and falls back to raw values without typed keyframes", () => {
+    const state = createKeyframedState();
+
+    expect(evaluateToolcraftTimelineValue(state, "shape.opacity", 8)).toBe(100);
+    expect(evaluateToolcraftTimelineValue(state, "shape.preset", 8)).toBe("radial");
+    expect(evaluateToolcraftTimelineValue(state, "missing.target", 4)).toBeUndefined();
+  });
+});

package/templates/runtime/state/keyframe-evaluation.ts

@@ -0,0 +1,203 @@
+import type {
+  ToolcraftState,
+  ToolcraftTimelineBezierControlPoints,
+  ToolcraftTimelineKeyframe,
+  ToolcraftTimelineKeyframeEasing,
+  ToolcraftTimelineKeyframeGroup,
+} from "./types";
+
+const defaultTimelineKeyframeEasing: ToolcraftTimelineKeyframeEasing = {
+  controlPoints: [0.65, 0, 0.35, 1],
+  type: "bezier",
+};
+
+function clampUnit(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(1, value));
+}
+
+function getBezierPoint(
+  time: number,
+  firstControlPoint: number,
+  secondControlPoint: number,
+): number {
+  const inverseTime = 1 - time;
+
+  return (
+    3 * inverseTime * inverseTime * time * firstControlPoint +
+    3 * inverseTime * time * time * secondControlPoint +
+    time * time * time
+  );
+}
+
+function getBezierYForX(
+  progress: number,
+  [x1, y1, x2, y2]: ToolcraftTimelineBezierControlPoints,
+): number {
+  let min = 0;
+  let max = 1;
+  let time = progress;
+
+  for (let index = 0; index < 30; index += 1) {
+    time = (min + max) / 2;
+
+    if (getBezierPoint(time, x1, x2) < progress) {
+      min = time;
+    } else {
+      max = time;
+    }
+  }
+
+  return clampUnit(getBezierPoint(time, y1, y2));
+}
+
+function easeProgress(
+  progress: number,
+  easing: ToolcraftTimelineKeyframeEasing | undefined,
+): number {
+  const clampedProgress = clampUnit(progress);
+  const resolvedEasing = easing ?? defaultTimelineKeyframeEasing;
+
+  if (resolvedEasing.type === "step") {
+    return clampedProgress >= 1 ? 1 : 0;
+  }
+
+  return getBezierYForX(clampedProgress, resolvedEasing.controlPoints);
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+
+  return prototype === Object.prototype || prototype === null;
+}
+
+function interpolateToolcraftValue(
+  fromValue: unknown,
+  toValue: unknown,
+  progress: number,
+): unknown {
+  if (typeof fromValue === "number" && typeof toValue === "number") {
+    return fromValue + (toValue - fromValue) * progress;
+  }
+
+  if (Array.isArray(fromValue) && Array.isArray(toValue) && fromValue.length === toValue.length) {
+    return fromValue.map((item, index) =>
+      interpolateToolcraftValue(item, toValue[index], progress),
+    );
+  }
+
+  if (isPlainRecord(fromValue) && isPlainRecord(toValue)) {
+    const fromKeys = Object.keys(fromValue);
+    const toKeys = Object.keys(toValue);
+
+    if (
+      fromKeys.length === toKeys.length &&
+      fromKeys.every((key) => Object.prototype.hasOwnProperty.call(toValue, key))
+    ) {
+      return Object.fromEntries(
+        fromKeys.map((key) => [
+          key,
+          interpolateToolcraftValue(fromValue[key], toValue[key], progress),
+        ]),
+      );
+    }
+  }
+
+  return progress >= 1 ? toValue : fromValue;
+}
+
+function getKeyframeRuntimeValue(keyframe: ToolcraftTimelineKeyframe): unknown {
+  return "value" in keyframe ? keyframe.value : undefined;
+}
+
+function getEvaluatedTimelineGroupValue(
+  group: ToolcraftTimelineKeyframeGroup,
+  timeSeconds: number,
+  fallbackValue: unknown,
+): unknown {
+  const keyframes = group.keyframes
+    .filter((keyframe) => "value" in keyframe)
+    .sort((first, second) => first.timeSeconds - second.timeSeconds);
+
+  if (keyframes.length === 0) {
+    return fallbackValue;
+  }
+
+  const firstKeyframe = keyframes[0];
+  const lastKeyframe = keyframes[keyframes.length - 1];
+
+  if (!firstKeyframe || !lastKeyframe) {
+    return fallbackValue;
+  }
+
+  if (timeSeconds <= firstKeyframe.timeSeconds) {
+    return getKeyframeRuntimeValue(firstKeyframe);
+  }
+
+  if (timeSeconds >= lastKeyframe.timeSeconds) {
+    return getKeyframeRuntimeValue(lastKeyframe);
+  }
+
+  for (let index = 0; index < keyframes.length - 1; index += 1) {
+    const fromKeyframe = keyframes[index];
+    const toKeyframe = keyframes[index + 1];
+
+    if (!fromKeyframe || !toKeyframe) {
+      continue;
+    }
+
+    if (timeSeconds < fromKeyframe.timeSeconds || timeSeconds > toKeyframe.timeSeconds) {
+      continue;
+    }
+
+    const durationSeconds = toKeyframe.timeSeconds - fromKeyframe.timeSeconds;
+    const progress = durationSeconds <= 0 ? 1 : (timeSeconds - fromKeyframe.timeSeconds) / durationSeconds;
+    const easedProgress = easeProgress(progress, fromKeyframe.easing);
+
+    return interpolateToolcraftValue(
+      getKeyframeRuntimeValue(fromKeyframe),
+      getKeyframeRuntimeValue(toKeyframe),
+      easedProgress,
+    );
+  }
+
+  return fallbackValue;
+}
+
+export function evaluateToolcraftTimelineValue(
+  state: ToolcraftState,
+  target: string,
+  timeSeconds = state.timeline.currentTimeSeconds,
+): unknown {
+  const group = state.timeline.keyframeGroups.find((item) => item.controlId === target);
+
+  if (!group) {
+    return state.values[target];
+  }
+
+  return getEvaluatedTimelineGroupValue(group, timeSeconds, state.values[target]);
+}
+
+export function evaluateToolcraftTimelineValues(
+  state: ToolcraftState,
+  timeSeconds = state.timeline.currentTimeSeconds,
+): Record<string, unknown> {
+  const values = { ...state.values };
+
+  for (const group of state.timeline.keyframeGroups) {
+    values[group.controlId] = getEvaluatedTimelineGroupValue(
+      group,
+      timeSeconds,
+      state.values[group.controlId],
+    );
+  }
+
+  return values;
+}