@pixel-point/toolcraft 0.0.2

package/templates/runtime/export/export.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import type { ToolcraftState } from "../state/types";
+import {
+  createToolcraftPngExportCanvas,
+  getToolcraftRetinaExportPixelRatio,
+  getToolcraftRetinaExportSize,
+  shouldIncludeToolcraftExportBackground,
+} from "./export";
+
+function createState(schema = defineToolcraft({ canvas: { enabled: true }, panels: {} })): ToolcraftState {
+  return {
+    canvas: {
+      offset: { x: 0, y: 0 },
+      size: { height: 100, unit: "px", width: 200 },
+      zoom: 70,
+    },
+    defaults: {},
+    history: {
+      redo: [],
+      undo: [],
+    },
+    layers: [],
+    mediaAssets: [],
+    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 } },
+    },
+    schema,
+    selectedLayerId: null,
+    timeline: {
+      currentTimeSeconds: 0,
+      durationSeconds: 8,
+      expanded: false,
+      isLooping: true,
+      isPlaying: false,
+      keyframeGroups: [],
+      selectedKeyframeId: null,
+    },
+    values: {},
+  };
+}
+
+function createMockCanvas() {
+  const context = {
+    clearRect: vi.fn(),
+    fillRect: vi.fn(),
+    fillStyle: "",
+    restore: vi.fn(),
+    save: vi.fn(),
+    scale: vi.fn(),
+  };
+  const canvas = {
+    getContext: vi.fn(() => context),
+    height: 0,
+    width: 0,
+  } as unknown as HTMLCanvasElement;
+
+  return { canvas, context };
+}
+
+describe("Toolcraft export helpers", () => {
+  it("normalizes png export background to include by default", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    });
+
+    expect(schema.export.png.background).toBe("include");
+  });
+
+  it("preserves transparent png export background option", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      export: {
+        png: {
+          background: "transparent",
+        },
+      },
+      panels: {},
+    });
+
+    expect(schema.export.png.background).toBe("transparent");
+    expect(shouldIncludeToolcraftExportBackground({ format: "png", schema })).toBe(false);
+    expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
+  });
+
+  it("uses at least 2x pixel ratio for retina export", () => {
+    expect(getToolcraftRetinaExportPixelRatio(1)).toBe(2);
+    expect(getToolcraftRetinaExportPixelRatio(1.5)).toBe(2);
+    expect(getToolcraftRetinaExportPixelRatio(3)).toBe(3);
+  });
+
+  it("resolves retina export size from canvas size rather than viewport zoom", () => {
+    const state = createState();
+    state.canvas.zoom = 35;
+
+    expect(getToolcraftRetinaExportSize({ devicePixelRatio: 2, state })).toEqual({
+      height: 200,
+      pixelRatio: 2,
+      width: 400,
+    });
+  });
+
+  it("creates a transparent retina png canvas when png background is disabled", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      export: {
+        png: {
+          background: "transparent",
+        },
+      },
+      panels: {},
+    });
+    const state = createState(schema);
+    const { canvas, context } = createMockCanvas();
+    const render = vi.fn();
+
+    const exportedCanvas = createToolcraftPngExportCanvas({
+      canvasFactory: () => canvas,
+      devicePixelRatio: 2,
+      render,
+      state,
+    });
+
+    expect(exportedCanvas.width).toBe(400);
+    expect(exportedCanvas.height).toBe(200);
+    expect(context.clearRect).toHaveBeenCalledWith(0, 0, 400, 200);
+    expect(context.fillRect).not.toHaveBeenCalled();
+    expect(context.scale).toHaveBeenCalledWith(2, 2);
+    expect(render).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cssHeight: 100,
+        cssWidth: 200,
+        includeBackground: false,
+        pixelHeight: 200,
+        pixelRatio: 2,
+        pixelWidth: 400,
+      }),
+    );
+  });
+
+  it("fills the png background when png background is enabled", () => {
+    const state = createState();
+    const { canvas, context } = createMockCanvas();
+
+    createToolcraftPngExportCanvas({
+      background: "#112233",
+      canvasFactory: () => canvas,
+      devicePixelRatio: 2,
+      render: vi.fn(),
+      state,
+    });
+
+    expect(context.fillStyle).toBe("#112233");
+    expect(context.fillRect).toHaveBeenCalledWith(0, 0, 400, 200);
+  });
+
+  it("allows runtime controls to disable the png background", () => {
+    const state = createState();
+    const { canvas, context } = createMockCanvas();
+
+    createToolcraftPngExportCanvas({
+      background: "#112233",
+      canvasFactory: () => canvas,
+      devicePixelRatio: 2,
+      includeBackground: false,
+      render: vi.fn(),
+      state,
+    });
+
+    expect(context.fillRect).not.toHaveBeenCalled();
+  });
+
+  it("allows runtime controls to include the png background for transparent schema defaults", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      export: {
+        png: {
+          background: "transparent",
+        },
+      },
+      panels: {},
+    });
+    const state = createState(schema);
+    const { canvas, context } = createMockCanvas();
+
+    createToolcraftPngExportCanvas({
+      background: "#445566",
+      canvasFactory: () => canvas,
+      devicePixelRatio: 2,
+      includeBackground: true,
+      render: vi.fn(),
+      state,
+    });
+
+    expect(context.fillStyle).toBe("#445566");
+    expect(context.fillRect).toHaveBeenCalledWith(0, 0, 400, 200);
+  });
+});

package/templates/runtime/export/export.ts

@@ -0,0 +1,132 @@
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type { ToolcraftState } from "../state/types";
+
+export type ToolcraftExportFormat = "png" | "video";
+
+export type ToolcraftRetinaExportSize = {
+  height: number;
+  pixelRatio: number;
+  width: number;
+};
+
+export type ToolcraftExportBackgroundOptions = {
+  format: ToolcraftExportFormat;
+  schema: ResolvedToolcraftAppSchema;
+};
+
+export type ToolcraftExportSizeOptions = {
+  devicePixelRatio?: number;
+  state: ToolcraftState;
+};
+
+export type ToolcraftPngRenderContext = {
+  canvas: HTMLCanvasElement;
+  context: CanvasRenderingContext2D;
+  cssHeight: number;
+  cssWidth: number;
+  includeBackground: boolean;
+  pixelHeight: number;
+  pixelRatio: number;
+  pixelWidth: number;
+};
+
+export type ToolcraftPngExportCanvasOptions = {
+  background?: string;
+  canvasFactory?: () => HTMLCanvasElement;
+  devicePixelRatio?: number;
+  includeBackground?: boolean;
+  render: (context: ToolcraftPngRenderContext) => void;
+  state: ToolcraftState;
+};
+
+export function getToolcraftRetinaExportPixelRatio(devicePixelRatio?: number): number {
+  const globalPixelRatio = (globalThis as typeof globalThis & { devicePixelRatio?: number })
+    .devicePixelRatio;
+  const fallbackPixelRatio =
+    typeof globalPixelRatio === "number" && Number.isFinite(globalPixelRatio)
+      ? globalPixelRatio
+      : 1;
+  const requestedPixelRatio =
+    typeof devicePixelRatio === "number" && Number.isFinite(devicePixelRatio)
+      ? devicePixelRatio
+      : fallbackPixelRatio;
+
+  return Math.max(2, requestedPixelRatio);
+}
+
+export function getToolcraftRetinaExportSize({
+  devicePixelRatio,
+  state,
+}: ToolcraftExportSizeOptions): ToolcraftRetinaExportSize {
+  const pixelRatio = getToolcraftRetinaExportPixelRatio(devicePixelRatio);
+
+  return {
+    height: Math.ceil(state.canvas.size.height * pixelRatio),
+    pixelRatio,
+    width: Math.ceil(state.canvas.size.width * pixelRatio),
+  };
+}
+
+export function shouldIncludeToolcraftExportBackground({
+  format,
+  schema,
+}: ToolcraftExportBackgroundOptions): boolean {
+  if (format === "video") {
+    return true;
+  }
+
+  return schema.export.png.background !== "transparent";
+}
+
+export function createToolcraftPngExportCanvas({
+  background = "#000000",
+  canvasFactory = () => document.createElement("canvas"),
+  devicePixelRatio,
+  includeBackground: includeBackgroundOverride,
+  render,
+  state,
+}: ToolcraftPngExportCanvasOptions): HTMLCanvasElement {
+  const canvas = canvasFactory();
+  const { height, pixelRatio, width } = getToolcraftRetinaExportSize({
+    devicePixelRatio,
+    state,
+  });
+  const includeBackground =
+    includeBackgroundOverride ??
+    shouldIncludeToolcraftExportBackground({
+      format: "png",
+      schema: state.schema,
+    });
+
+  canvas.width = width;
+  canvas.height = height;
+
+  const context = canvas.getContext("2d");
+
+  if (!context) {
+    throw new Error("Toolcraft PNG export requires a 2D canvas context.");
+  }
+
+  context.save();
+  context.clearRect(0, 0, width, height);
+
+  if (includeBackground) {
+    context.fillStyle = background;
+    context.fillRect(0, 0, width, height);
+  }
+
+  context.scale(pixelRatio, pixelRatio);
+  render({
+    canvas,
+    context,
+    cssHeight: state.canvas.size.height,
+    cssWidth: state.canvas.size.width,
+    includeBackground,
+    pixelHeight: height,
+    pixelRatio,
+    pixelWidth: width,
+  });
+  context.restore();
+
+  return canvas;
+}

package/templates/runtime/export/index.ts

@@ -0,0 +1 @@
+export * from "./export";

package/templates/runtime/index.ts

@@ -0,0 +1,14 @@
+export * from "./contracts/component-contracts";
+export * from "./contracts/decision-contracts";
+export * from "./contracts/types";
+export * from "./export";
+export * from "./schema/define-toolcraft";
+export * from "./schema/keyframe-capability";
+export * from "./schema/runtime-targets";
+export * from "./schema/types";
+export * from "./state/create-template-state";
+export * from "./state/keyframe-evaluation";
+export * from "./state/persistence";
+export * from "./state/reducer";
+export * from "./state/types";
+export * from "./testing/performance";