@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/runtime/schema/panels-schema-normalization.ts

@@ -0,0 +1,49 @@
+import {
+  createToolcraftRuntimeSetupSection,
+} from "./runtime-setup-section";
+import { normalizeControlsPanelLayout } from "./controls-panel-normalization";
+import { resolveToolcraftTimelinePanel } from "./schema-resolvers";
+import type {
+  ResolvedToolcraftAppSchema,
+  ResolvedToolcraftPanelsSchema,
+  ResolvedToolcraftSettingsTransferSchema,
+  ToolcraftAppSchema,
+} from "./types";
+export function normalizeToolcraftPanels({
+  canvas,
+  panels,
+  settingsTransfer,
+}: {
+  canvas: ResolvedToolcraftAppSchema["canvas"];
+  panels: ToolcraftAppSchema["panels"];
+  settingsTransfer: ResolvedToolcraftSettingsTransferSchema;
+}): ResolvedToolcraftPanelsSchema {
+  const normalizedTimeline = resolveToolcraftTimelinePanel(panels.timeline);
+  const normalizedPanels: ResolvedToolcraftPanelsSchema = {
+    ...(panels.controls ? { controls: panels.controls } : {}),
+    ...(panels.layers ? { layers: panels.layers } : {}),
+    ...(normalizedTimeline ? { timeline: normalizedTimeline } : {}),
+  };
+
+  if (!panels.controls) {
+    return normalizedPanels;
+  }
+
+  const controls = { ...panels.controls };
+  const runtimeSetupSection = createToolcraftRuntimeSetupSection({
+    canvas,
+    settingsTransfer,
+    timeline: normalizedTimeline,
+  });
+
+  return {
+    ...normalizedPanels,
+    controls: normalizeControlsPanelLayout({
+      ...controls,
+      sections: [
+        runtimeSetupSection,
+        ...controls.sections,
+      ],
+    }),
+  };
+}

package/templates/runtime/schema/runtime-section-titles.ts

@@ -0,0 +1 @@
+export const toolcraftRuntimeSetupSectionTitle = "Setup";

package/templates/runtime/schema/runtime-setup-section.ts

@@ -0,0 +1,282 @@
+import {
+  getToolcraftCanvasAspectRatioPreset,
+  getToolcraftCanvasAspectRatioPresetBySize,
+} from "./canvas-aspect-ratio-presets";
+import { toolcraftRuntimeSetupSectionTitle } from "./runtime-section-titles";
+import { toolcraftTimelinePanelExtendedTarget } from "./runtime-targets";
+import type {
+  ResolvedToolcraftAppSchema,
+  ResolvedToolcraftSettingsTransferSchema,
+  ResolvedToolcraftTimelinePanelSchema,
+  ToolcraftAppSchema,
+  ToolcraftCanvasSize,
+  ToolcraftControlLayoutGroupSchema,
+  ToolcraftControlSchema,
+  ToolcraftControlSectionSchema,
+  ToolcraftControlsPanelSchema,
+  ToolcraftSettingsTransferSchema,
+} from "./types";
+
+const canvasSizeControlTargets = {
+  height: "canvas.size.height",
+  width: "canvas.size.width",
+} as const;
+const canvasAspectRatioTarget = "canvas.aspectRatio";
+const canvasRenderScaleTarget = "canvas.renderScale";
+const settingsTransferTarget = "runtime.settingsTransfer";
+
+function slugifySettingsTransferAppId(value: string | undefined): string {
+  const slug = value
+    ?.trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || "toolcraft-app";
+}
+
+function getSettingsTransferMode(
+  settingsTransfer: ToolcraftSettingsTransferSchema | undefined,
+): "auto" | boolean {
+  if (typeof settingsTransfer === "object" && settingsTransfer !== null) {
+    return settingsTransfer.enabled ?? "auto";
+  }
+
+  return settingsTransfer ?? "auto";
+}
+
+function getSettingsTransferObject(
+  settingsTransfer: ToolcraftSettingsTransferSchema | undefined,
+): Extract<ToolcraftSettingsTransferSchema, object> | undefined {
+  return typeof settingsTransfer === "object" && settingsTransfer !== null
+    ? settingsTransfer
+    : undefined;
+}
+
+function getSettingsTransferAppId({
+  controls,
+  persistence,
+  settingsTransfer,
+}: {
+  controls: ToolcraftControlsPanelSchema | undefined;
+  persistence: ResolvedToolcraftAppSchema["persistence"];
+  settingsTransfer: ToolcraftSettingsTransferSchema | undefined;
+}): string {
+  const objectSchema = getSettingsTransferObject(settingsTransfer);
+
+  if (objectSchema?.appId) {
+    return slugifySettingsTransferAppId(objectSchema.appId);
+  }
+
+  if (persistence.storage === "localStorage") {
+    const match = /^toolcraft:(.+):state:v\d+$/u.exec(persistence.key);
+
+    if (match?.[1]) {
+      return slugifySettingsTransferAppId(match[1]);
+    }
+  }
+
+  return slugifySettingsTransferAppId(controls?.title);
+}
+
+function getSettingsTransferFileName({
+  appId,
+  settingsTransfer,
+}: {
+  appId: string;
+  settingsTransfer: ToolcraftSettingsTransferSchema | undefined;
+}): string {
+  const explicitFileName = getSettingsTransferObject(settingsTransfer)?.fileName?.trim();
+
+  if (explicitFileName) {
+    return explicitFileName.endsWith(".json")
+      ? explicitFileName
+      : `${explicitFileName}.json`;
+  }
+
+  return `${appId}-settings.json`;
+}
+
+export function resolveToolcraftSettingsTransfer({
+  controls,
+  persistence,
+  settingsTransfer,
+}: {
+  controls: ToolcraftControlsPanelSchema | undefined;
+  persistence: ResolvedToolcraftAppSchema["persistence"];
+  settingsTransfer: ToolcraftSettingsTransferSchema | undefined;
+}): ResolvedToolcraftSettingsTransferSchema {
+  const mode = getSettingsTransferMode(settingsTransfer);
+  const appId = getSettingsTransferAppId({
+    controls,
+    persistence,
+    settingsTransfer,
+  });
+
+  return {
+    appId,
+    enabled: Boolean(controls),
+    fileName: getSettingsTransferFileName({ appId, settingsTransfer }),
+    mode,
+  };
+}
+
+function getGreatestCommonDivisor(left: number, right: number): number {
+  let a = Math.abs(Math.round(left));
+  let b = Math.abs(Math.round(right));
+
+  while (b !== 0) {
+    const next = b;
+    b = a % b;
+    a = next;
+  }
+
+  return a || 1;
+}
+
+function getCanvasAspectRatioDefaultValue(size: ToolcraftCanvasSize): {
+  height: number;
+  mode: "custom" | "preset";
+  value: string;
+  width: number;
+} {
+  const divisor = getGreatestCommonDivisor(size.width, size.height);
+  const width = Math.max(1, Math.round(size.width / divisor));
+  const height = Math.max(1, Math.round(size.height / divisor));
+  const value = `${width}:${height}`;
+  const preset =
+    getToolcraftCanvasAspectRatioPreset(value) ??
+    getToolcraftCanvasAspectRatioPresetBySize(size);
+
+  return {
+    height: preset?.ratioHeight ?? height,
+    mode: preset ? "preset" : "custom",
+    value: preset?.value ?? value,
+    width: preset?.ratioWidth ?? width,
+  };
+}
+
+function createRenderScaleControl(
+  canvas: ResolvedToolcraftAppSchema["canvas"],
+): ToolcraftControlSchema | undefined {
+  if (!canvas.renderScale.enabled) {
+    return undefined;
+  }
+
+  return {
+    defaultValue: canvas.renderScale.defaultValue,
+    description:
+      "Increases raster canvas backing resolution without changing the visible output size.",
+    label: "Resolution scale",
+    markerCount:
+      Math.floor(
+        (canvas.renderScale.max - canvas.renderScale.min) / canvas.renderScale.step,
+      ) + 1,
+    max: canvas.renderScale.max,
+    min: canvas.renderScale.min,
+    performanceReason:
+      "Resolution scale changes raster, Canvas, WebGL, or WebGPU backing pixels.",
+    performanceRole: "workload",
+    step: canvas.renderScale.step,
+    target: canvasRenderScaleTarget,
+    type: "slider",
+    variant: "discrete",
+  };
+}
+
+function createTimelineExtendedControl(
+  timeline: ResolvedToolcraftTimelinePanelSchema | undefined,
+): ToolcraftControlSchema | undefined {
+  if (!timeline?.enabled) {
+    return undefined;
+  }
+
+  return {
+    defaultValue: false,
+    description:
+      "Shows the extended runtime timeline with scrubber, duration, loop, and keyframe controls; compact mode keeps only Play visible.",
+    label: "Timeline",
+    target: toolcraftTimelinePanelExtendedTarget,
+    type: "switch",
+  };
+}
+
+function createEditableCanvasControls(
+  canvas: ResolvedToolcraftAppSchema["canvas"],
+): {
+  controls: ToolcraftControlSectionSchema["controls"];
+  layoutGroups?: readonly ToolcraftControlLayoutGroupSchema[];
+} {
+  if (!canvas.enabled || canvas.sizing.mode !== "editable-output") {
+    return { controls: {} };
+  }
+
+  return {
+    controls: {
+      canvasAspectRatio: {
+        defaultValue: getCanvasAspectRatioDefaultValue(canvas.size),
+        label: "Aspect ratio",
+        orderRole: "input",
+        performanceReason: "Aspect ratio changes output dimensions and renderer workload.",
+        performanceRole: "workload",
+        target: canvasAspectRatioTarget,
+        type: "aspectRatio",
+      },
+      canvasWidth: {
+        defaultValue: canvas.size.width,
+        label: "Canvas width",
+        orderRole: "input",
+        performanceReason: "Canvas width changes output dimensions and renderer workload.",
+        performanceRole: "workload",
+        target: canvasSizeControlTargets.width,
+        type: "text",
+      },
+      canvasHeight: {
+        defaultValue: canvas.size.height,
+        label: "Canvas height",
+        orderRole: "input",
+        performanceReason: "Canvas height changes output dimensions and renderer workload.",
+        performanceRole: "workload",
+        target: canvasSizeControlTargets.height,
+        type: "text",
+      },
+    },
+    layoutGroups: [
+      {
+        columns: 2,
+        controls: ["canvasWidth", "canvasHeight"],
+        layout: "inline",
+      },
+    ],
+  };
+}
+
+export function createToolcraftRuntimeSetupSection({
+  canvas,
+  settingsTransfer,
+  timeline,
+}: {
+  canvas: ResolvedToolcraftAppSchema["canvas"];
+  settingsTransfer: ResolvedToolcraftSettingsTransferSchema;
+  timeline: ResolvedToolcraftTimelinePanelSchema | undefined;
+}): ToolcraftControlSectionSchema {
+  const editableCanvas = createEditableCanvasControls(canvas);
+  const renderScaleControl = createRenderScaleControl(canvas);
+  const timelineExtendedControl = createTimelineExtendedControl(timeline);
+
+  return {
+    controls: {
+      settingsTransfer: {
+        label: false,
+        target: settingsTransferTarget,
+        type: "settingsTransfer",
+      },
+      ...editableCanvas.controls,
+      ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
+      ...(timelineExtendedControl ? { timelineExtended: timelineExtendedControl } : {}),
+    },
+    layout: "standalone",
+    layoutGroups: editableCanvas.layoutGroups,
+    title: toolcraftRuntimeSetupSectionTitle,
+  };
+}

package/templates/runtime/schema/schema-resolvers.ts

@@ -0,0 +1,168 @@
+import {
+  clampToolcraftTimelineDurationSeconds,
+  toolcraftTimelineDefaultDurationSeconds,
+} from "../state/timeline-values";
+import type {
+  ResolvedToolcraftAppSchema,
+  ResolvedToolcraftTimelinePanelSchema,
+  ToolcraftAppSchema,
+  ToolcraftCanvasSize,
+  ToolcraftCanvasSizingSchema,
+  ToolcraftTimelinePanelSchema,
+  ToolcraftToolbarSchema,
+} from "./types";
+
+export const defaultToolcraftCanvasSize = {
+  height: 1080,
+  unit: "px",
+  width: 1920,
+} satisfies ToolcraftCanvasSize;
+
+const defaultCanvasRenderScale = {
+  defaultValue: 2,
+  enabled: false,
+  max: 2,
+  min: 1,
+  step: 0.25,
+} satisfies ResolvedToolcraftAppSchema["canvas"]["renderScale"];
+
+function assertNever(value: never): never {
+  throw new Error(`Unsupported Toolcraft template persistence storage: ${String(value)}`);
+}
+
+export function resolveToolcraftPersistence(
+  persistence: ToolcraftAppSchema["persistence"],
+): ResolvedToolcraftAppSchema["persistence"] {
+  switch (persistence?.storage) {
+    case undefined:
+    case "none":
+      return { storage: "none" };
+    case "localStorage":
+      return persistence;
+    default:
+      return assertNever(persistence);
+  }
+}
+
+export function resolveToolcraftCanvasSizing(
+  canvas: ToolcraftAppSchema["canvas"],
+): ToolcraftCanvasSizingSchema {
+  if (canvas.sizing) {
+    return canvas.sizing;
+  }
+
+  if (canvas.size) {
+    return { mode: "editable-output" };
+  }
+
+  if (canvas.upload) {
+    return { mode: "editable-output" };
+  }
+
+  return { mode: "intrinsic-media" };
+}
+
+function clampCanvasRenderScale(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+
+  return Math.max(1, Math.min(2, value));
+}
+
+export function resolveToolcraftCanvasRenderScale(
+  renderScale: ToolcraftAppSchema["canvas"]["renderScale"],
+): ResolvedToolcraftAppSchema["canvas"]["renderScale"] {
+  if (renderScale === true) {
+    return {
+      ...defaultCanvasRenderScale,
+      enabled: true,
+    };
+  }
+
+  if (!renderScale) {
+    return defaultCanvasRenderScale;
+  }
+
+  const min = clampCanvasRenderScale(renderScale.min, defaultCanvasRenderScale.min);
+  const max = Math.max(
+    min,
+    clampCanvasRenderScale(renderScale.max, defaultCanvasRenderScale.max),
+  );
+  const step =
+    typeof renderScale.step === "number" && Number.isFinite(renderScale.step)
+      ? Math.max(0.01, Math.min(1, renderScale.step))
+      : defaultCanvasRenderScale.step;
+  const defaultValue = Math.max(
+    min,
+    Math.min(
+      max,
+      clampCanvasRenderScale(renderScale.defaultValue, defaultCanvasRenderScale.defaultValue),
+    ),
+  );
+
+  return {
+    defaultValue,
+    enabled: renderScale.enabled ?? true,
+    max,
+    min,
+    step,
+  };
+}
+
+export function resolveToolcraftExport(
+  exportSchema: ToolcraftAppSchema["export"],
+): ResolvedToolcraftAppSchema["export"] {
+  return {
+    png: {
+      background: exportSchema?.png?.background ?? "include",
+    },
+  };
+}
+
+export function resolveToolcraftMedia(
+  mediaSchema: ToolcraftAppSchema["media"],
+): ResolvedToolcraftAppSchema["media"] {
+  return {
+    defaultAssets: mediaSchema?.defaultAssets ?? [],
+  };
+}
+
+export function resolveToolcraftTimelinePanel(
+  timeline: ToolcraftTimelinePanelSchema | undefined,
+): ResolvedToolcraftTimelinePanelSchema | undefined {
+  if (timeline === true) {
+    return {
+      defaultDurationSeconds: toolcraftTimelineDefaultDurationSeconds,
+      enabled: true,
+      mode: "keyframes",
+    };
+  }
+
+  if (!timeline || timeline.enabled === false) {
+    return undefined;
+  }
+
+  return {
+    defaultDurationSeconds: clampToolcraftTimelineDurationSeconds(
+      timeline.defaultDurationSeconds,
+    ),
+    enabled: true,
+    mode: timeline.mode ?? "keyframes",
+  };
+}
+
+export function resolveToolcraftToolbar({
+  canvasEnabled,
+  toolbar,
+}: {
+  canvasEnabled: boolean;
+  toolbar: ToolcraftAppSchema["toolbar"];
+}): Required<ToolcraftToolbarSchema> {
+  return {
+    history: toolbar?.history ?? canvasEnabled,
+    radar: toolbar?.radar ?? canvasEnabled,
+    theme: toolbar?.theme ?? true,
+    zoom: toolbar?.zoom ?? canvasEnabled,
+  };
+}

package/templates/runtime/schema/types.ts

@@ -241,6 +241,12 @@ export type ResolvedToolcraftSettingsTransferSchema = {
 
 export type ToolcraftActionCommand = "controls.apply" | "controls.reset";
 
+export type ToolcraftActionRole =
+  | "copy-output"
+  | "download-output"
+  | "export-image"
+  | "export-video";
+
 export type ToolcraftActionSchema = {
   command?: ToolcraftActionCommand;
   icon?:
@@ -255,6 +261,7 @@ export type ToolcraftActionSchema = {
     | "upload-simple"
     | "wand-sparkles";
   label?: string;
+  role?: ToolcraftActionRole;
   value: string;
   variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary";
 };
@@ -280,6 +287,12 @@ export type ToolcraftControlPerformanceRole =
   | "responsiveness"
   | "workload";
 
+export type ToolcraftCurveIntent = "color-channels" | "single-value-map";
+
+export type ToolcraftSliderValueKind = "continuous" | "discrete";
+
+export type ToolcraftTextValueKind = "multiline" | "single-line" | "structured";
+
 export type ToolcraftFileDropAssetKind = "file" | "image";
 
 export type ToolcraftMediaPositionSchema = {
@@ -371,6 +384,7 @@ export type ToolcraftControlSchema = {
   addLabel?: string;
   commitMode?: "content" | "setting";
   coordinateMode?: ToolcraftVectorCoordinateMode;
+  curveIntent?: ToolcraftCurveIntent;
   defaultValue?: unknown;
   description?: string;
   disabled?: boolean;
@@ -394,8 +408,11 @@ export type ToolcraftControlSchema = {
   options?: readonly { label: string; value: string }[];
   recommendedMaxItems?: number;
   removeLabel?: string;
+  semanticGroup?: string;
+  sliderValueKind?: ToolcraftSliderValueKind;
   step?: number;
   target: string;
+  textValueKind?: ToolcraftTextValueKind;
   type: string;
   unit?: string;
   valueLabel?: string;

package/templates/runtime/state/canvas-reducer.ts

@@ -0,0 +1,106 @@
+import {
+  clampToolcraftCanvasZoom,
+  toolcraftCanvasZoomDefault,
+  toolcraftCanvasZoomStep,
+} from "./canvas-zoom";
+import { commitToolcraftStatePatch } from "./history-patches";
+import type {
+  ToolcraftCommand,
+  ToolcraftState,
+} from "./types";
+
+type ToolcraftCanvasCommand = Extract<
+  ToolcraftCommand,
+  {
+    type:
+      | "canvas.center"
+      | "canvas.panBy"
+      | "canvas.setOffset"
+      | "canvas.setSize"
+      | "canvas.setViewport"
+      | "canvas.zoomIn"
+      | "canvas.zoomOut"
+      | "canvas.zoomReset";
+  }
+>;
+
+export function reduceToolcraftCanvasCommand(
+  state: ToolcraftState,
+  command: ToolcraftCanvasCommand,
+): ToolcraftState {
+  switch (command.type) {
+    case "canvas.setOffset":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          offset: command.offset,
+        },
+      };
+
+    case "canvas.panBy":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          offset: {
+            x: state.canvas.offset.x + command.delta.x,
+            y: state.canvas.offset.y + command.delta.y,
+          },
+        },
+      };
+
+    case "canvas.setSize":
+      return commitToolcraftStatePatch(state, {
+        after: { "canvas.size": command.size },
+        before: { "canvas.size": state.canvas.size },
+        label: "Resize canvas",
+      });
+
+    case "canvas.center":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          offset: { x: 0, y: 0 },
+        },
+      };
+
+    case "canvas.zoomIn":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          zoom: clampToolcraftCanvasZoom(state.canvas.zoom + toolcraftCanvasZoomStep),
+        },
+      };
+
+    case "canvas.zoomOut":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          zoom: clampToolcraftCanvasZoom(state.canvas.zoom - toolcraftCanvasZoomStep),
+        },
+      };
+
+    case "canvas.zoomReset":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          zoom: toolcraftCanvasZoomDefault,
+        },
+      };
+
+    case "canvas.setViewport":
+      return {
+        ...state,
+        canvas: {
+          ...state.canvas,
+          offset: command.offset,
+          zoom: clampToolcraftCanvasZoom(command.zoom),
+        },
+      };
+  }
+}