@pixel-point/toolcraft 0.0.2

package/templates/runtime/schema/keyframe-capability.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftControlKeyframeCapability } from "./keyframe-capability";
+import type { ToolcraftControlSchema } from "./types";
+
+function control(
+  type: ToolcraftControlSchema["type"],
+  target: string,
+  extra: Partial<ToolcraftControlSchema> = {},
+): ToolcraftControlSchema {
+  return {
+    defaultValue: 0,
+    label: "Control",
+    target,
+    type,
+    ...extra,
+  };
+}
+
+describe("getToolcraftControlKeyframeCapability", () => {
+  it("marks numeric and visual parameter controls as keyframe-capable by component type", () => {
+    for (const type of [
+      "slider",
+      "rangeSlider",
+      "rangeInput",
+      "vector",
+      "color",
+      "gradient",
+      "curves",
+      "anchorGrid",
+      "channelMixer",
+    ]) {
+      expect(
+        getToolcraftControlKeyframeCapability(control(type, `effect.${type}`)),
+      ).toEqual({
+        capable: true,
+        reason: "control-type",
+      });
+    }
+  });
+
+  it("does not let schema keyframeable false hide diamonds for capable control types", () => {
+    expect(
+      getToolcraftControlKeyframeCapability(
+        control("slider", "mesh.blur", { keyframeable: false }),
+      ),
+    ).toEqual({
+      capable: true,
+      reason: "control-type",
+    });
+  });
+
+  it("blocks runtime-owned canvas size targets even when the visual type could otherwise animate", () => {
+    expect(
+      getToolcraftControlKeyframeCapability(control("text", "canvas.size.width")),
+    ).toEqual({
+      capable: false,
+      reason: "runtime-owned-target",
+    });
+
+    expect(
+      getToolcraftControlKeyframeCapability(control("slider", "canvas.size.height")),
+    ).toEqual({
+      capable: false,
+      reason: "runtime-owned-target",
+    });
+  });
+
+  it("blocks command, source, mode, boolean, text, and choice controls", () => {
+    for (const type of [
+      "actions",
+      "checkbox",
+      "code",
+      "fileDrop",
+      "imagePicker",
+      "panelActions",
+      "select",
+      "segmented",
+      "switch",
+      "text",
+    ]) {
+      expect(
+        getToolcraftControlKeyframeCapability(control(type, `effect.${type}`)),
+      ).toEqual({
+        capable: false,
+        reason: "control-type",
+      });
+    }
+  });
+});

package/templates/runtime/schema/keyframe-capability.ts

@@ -0,0 +1,51 @@
+import { getToolcraftCanvasSizeTargetDimension } from "./runtime-targets";
+import type { ToolcraftControlSchema } from "./types";
+
+export type ToolcraftControlKeyframeCapabilityReason =
+  | "control-type"
+  | "runtime-owned-target";
+
+export type ToolcraftControlKeyframeCapability =
+  | {
+      capable: true;
+      reason: "control-type";
+    }
+  | {
+      capable: false;
+      reason: ToolcraftControlKeyframeCapabilityReason;
+    };
+
+const keyframeCapableControlTypes = new Set([
+  "anchorGrid",
+  "channelMixer",
+  "color",
+  "curves",
+  "gradient",
+  "rangeInput",
+  "rangeSlider",
+  "slider",
+  "vector",
+]);
+
+export function getToolcraftControlKeyframeCapability(
+  control: ToolcraftControlSchema,
+): ToolcraftControlKeyframeCapability {
+  if (getToolcraftCanvasSizeTargetDimension(control.target)) {
+    return {
+      capable: false,
+      reason: "runtime-owned-target",
+    };
+  }
+
+  if (keyframeCapableControlTypes.has(control.type)) {
+    return {
+      capable: true,
+      reason: "control-type",
+    };
+  }
+
+  return {
+    capable: false,
+    reason: "control-type",
+  };
+}

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

@@ -0,0 +1,40 @@
+export const toolcraftRuntimeOwnedTargets = [
+  "canvas.size.width",
+  "canvas.size.height",
+] as const;
+
+export const toolcraftReservedTargets = [
+  ...toolcraftRuntimeOwnedTargets,
+  "selectedLayer.opacity",
+  "selectedLayer.visible",
+] as const;
+
+export type ToolcraftRuntimeOwnedTarget =
+  (typeof toolcraftRuntimeOwnedTargets)[number];
+
+export type ToolcraftReservedTarget = (typeof toolcraftReservedTargets)[number];
+
+export function getToolcraftCanvasSizeTargetDimension(
+  target: string,
+): "height" | "width" | null {
+  switch (target) {
+    case "canvas.size.height":
+      return "height";
+    case "canvas.size.width":
+      return "width";
+    default:
+      return null;
+  }
+}
+
+export function isToolcraftReservedTarget(
+  target: string,
+): target is ToolcraftReservedTarget {
+  return toolcraftReservedTargets.includes(target as ToolcraftReservedTarget);
+}
+
+export function isToolcraftRuntimeOwnedTarget(
+  target: string,
+): target is ToolcraftRuntimeOwnedTarget {
+  return toolcraftRuntimeOwnedTargets.includes(target as ToolcraftRuntimeOwnedTarget);
+}

package/templates/runtime/schema/types.ts

@@ -0,0 +1,370 @@
+import type {
+  ToolcraftControlLayoutGroupColumns,
+  ToolcraftControlLayoutGroupLayout,
+  ToolcraftSectionLayout,
+} from "../contracts/types";
+
+export type ToolcraftCanvasSize = {
+  height: number;
+  unit: "px";
+  width: number;
+};
+
+export type ToolcraftCanvasSizeSource = "app" | "runtime-default";
+
+export type ToolcraftCanvasSizingMode =
+  | "editable-output"
+  | "fixed-output"
+  | "intrinsic-media";
+
+export type ToolcraftCanvasSizingSchema = {
+  mode: ToolcraftCanvasSizingMode;
+};
+
+export type ToolcraftPngExportBackground = "include" | "transparent";
+
+export type ToolcraftPngExportSchema = {
+  background?: ToolcraftPngExportBackground;
+};
+
+export type ToolcraftExportSchema = {
+  png?: ToolcraftPngExportSchema;
+};
+
+export type ResolvedToolcraftExportSchema = {
+  png: Required<ToolcraftPngExportSchema>;
+};
+
+export type ToolcraftAssemblyComponentId =
+  | "canvas"
+  | "controlsPanel"
+  | "layersPanel"
+  | "timelinePanel"
+  | "toolbar";
+
+export type ToolcraftAssemblyCapability =
+  | "canvas.draggable"
+  | "canvas.editableSize"
+  | "canvas.upload"
+  | "controls.defaults"
+  | "controls.panel"
+  | "history.undoRedo"
+  | "layers.groups"
+  | "layers.panel"
+  | "layers.selection"
+  | "layers.visibility"
+  | "panels.doubleClickReset"
+  | "panels.draggable"
+  | "panels.snap"
+  | "timeline.duration"
+  | "timeline.keyframes"
+  | "timeline.panel"
+  | "timeline.playback"
+  | "toolbar.history"
+  | "toolbar.radar"
+  | "toolbar.theme"
+  | "toolbar.zoom";
+
+export type ToolcraftAssemblyCommand =
+  | "canvas.center"
+  | "canvas.panBy"
+  | "canvas.setOffset"
+  | "canvas.setSize"
+  | "canvas.setViewport"
+  | "canvas.zoomIn"
+  | "canvas.zoomOut"
+  | "canvas.zoomReset"
+  | "controls.apply"
+  | "controls.reset"
+  | "controls.setValue"
+  | "history.redo"
+  | "history.undo"
+  | "layers.add"
+  | "layers.delete"
+  | "layers.moveToGroup"
+  | "layers.rename"
+  | "layers.reorder"
+  | "layers.select"
+  | "layers.toggleCollapsed"
+  | "layers.toggleVisibility"
+  | "media.delete"
+  | "media.import"
+  | "panels.resetOffset"
+  | "panels.setOffset"
+  | "timeline.changeKeyframeEasing"
+  | "timeline.deleteControlKeyframes"
+  | "timeline.deleteKeyframe"
+  | "timeline.moveKeyframe"
+  | "timeline.selectKeyframe"
+  | "timeline.setCurrentTime"
+  | "timeline.setDuration"
+  | "timeline.setExpanded"
+  | "timeline.setPlaying"
+  | "timeline.toggleControlKeyframes"
+  | "timeline.toggleExpanded"
+  | "timeline.toggleLoop"
+  | "timeline.togglePlayback";
+
+export type ToolcraftAssemblyPanelContract = {
+  capabilities: readonly ToolcraftAssemblyCapability[];
+  commands: readonly ToolcraftAssemblyCommand[];
+  defaultPlacement: "bottom" | "left" | "right" | "top";
+  dragMode: "handle" | "panel";
+  enabled: boolean;
+  requiredWrapper: "PanelHost";
+  snapEdges: readonly ("bottom" | "left" | "right" | "top")[];
+  visualComponent: string;
+};
+
+export type ToolcraftAssemblyCanvasContract = {
+  capabilities: readonly ToolcraftAssemblyCapability[];
+  commands: readonly ToolcraftAssemblyCommand[];
+  enabled: boolean;
+  visualComponent: "CanvasShell";
+};
+
+export type ToolcraftAssemblyContract = {
+  capabilities: readonly ToolcraftAssemblyCapability[];
+  commands: readonly ToolcraftAssemblyCommand[];
+  components: readonly ToolcraftAssemblyComponentId[];
+  surfaces: {
+    canvas: ToolcraftAssemblyCanvasContract;
+    panels: {
+      controls?: ToolcraftAssemblyPanelContract;
+      layers?: ToolcraftAssemblyPanelContract;
+      timeline?: ToolcraftAssemblyPanelContract;
+      toolbar: ToolcraftAssemblyPanelContract;
+    };
+  };
+};
+
+export type ToolcraftCanvasSchema = {
+  draggable?: boolean;
+  enabled: boolean;
+  size?: ToolcraftCanvasSize;
+  sizing?: ToolcraftCanvasSizingSchema;
+  upload?: boolean;
+};
+
+export type ToolcraftToolbarSchema = {
+  history?: boolean;
+  radar?: boolean;
+  theme?: boolean;
+  zoom?: boolean;
+};
+
+export type ToolcraftTimelineMode = "keyframes" | "playback";
+
+export type ToolcraftTimelinePanelSchema =
+  | boolean
+  | {
+      enabled?: boolean;
+      mode?: ToolcraftTimelineMode;
+    };
+
+export type ResolvedToolcraftTimelinePanelSchema = {
+  enabled: boolean;
+  mode: ToolcraftTimelineMode;
+};
+
+export type ToolcraftPersistableStateSlice =
+  | "canvas"
+  | "layers"
+  | "panels"
+  | "timeline"
+  | "values";
+
+export type ToolcraftNoPersistenceSchema = {
+  storage?: "none";
+};
+
+export type ToolcraftLocalStoragePersistenceSchema = {
+  include: readonly ToolcraftPersistableStateSlice[];
+  key: `toolcraft:${string}:state:v${number}`;
+  storage: "localStorage";
+  version: number;
+};
+
+export type ToolcraftPersistenceSchema =
+  | ToolcraftNoPersistenceSchema
+  | ToolcraftLocalStoragePersistenceSchema;
+
+export type ResolvedToolcraftPersistenceSchema =
+  | { storage: "none" }
+  | ToolcraftLocalStoragePersistenceSchema;
+
+export type ToolcraftSettingsTransferMode = boolean | "auto";
+
+export type ToolcraftSettingsTransferObjectSchema = {
+  appId?: string;
+  enabled?: ToolcraftSettingsTransferMode;
+  fileName?: string;
+};
+
+export type ToolcraftSettingsTransferSchema =
+  | ToolcraftSettingsTransferMode
+  | ToolcraftSettingsTransferObjectSchema;
+
+export type ResolvedToolcraftSettingsTransferSchema = {
+  appId: string;
+  enabled: boolean;
+  fileName: string;
+  mode: ToolcraftSettingsTransferMode;
+};
+
+export type ToolcraftActionCommand = "controls.apply" | "controls.reset";
+
+export type ToolcraftActionSchema = {
+  command?: ToolcraftActionCommand;
+  icon?:
+    | "check"
+    | "copy"
+    | "download"
+    | "download-simple"
+    | "eraser"
+    | "export"
+    | "rotate-ccw"
+    | "shuffle"
+    | "wand-sparkles";
+  label?: string;
+  value: string;
+  variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary";
+};
+
+export type ToolcraftImagePickerItemSchema = {
+  alt?: string;
+  src: string;
+  value: string;
+};
+
+export type ToolcraftControlOrderRole =
+  | "action"
+  | "advanced"
+  | "color"
+  | "detail"
+  | "input"
+  | "mode"
+  | "primary"
+  | "spatial"
+  | "strength";
+
+export type ToolcraftControlPerformanceRole =
+  | "responsiveness"
+  | "workload";
+
+export type ToolcraftControlConditionSchema = {
+  equals?: unknown;
+  greaterThan?: number;
+  greaterThanOrEqual?: number;
+  lessThan?: number;
+  lessThanOrEqual?: number;
+  notOneOf?: readonly unknown[];
+  notEquals?: unknown;
+  oneOf?: readonly unknown[];
+  target: string;
+};
+
+export type ToolcraftControlDisabledConditionSchema =
+  ToolcraftControlConditionSchema;
+
+export type ToolcraftColorOpacityValueSchema = {
+  hex: string;
+  opacity?: number;
+};
+
+export type ToolcraftFontPickerValueSchema = {
+  color?: string;
+  fontId: string;
+  fontSize?: number;
+  fontWeight?: string;
+  letterSpacing?: "tight" | "tighter" | "normal" | "wide" | "wider" | "widest";
+  lineHeight?: "loose" | "none" | "normal" | "relaxed" | "snug" | "tight";
+  opacity?: number;
+  textCase?: "capitalize" | "lowercase" | "original" | "titleCase" | "uppercase";
+};
+
+export type ToolcraftCurveInterpolation = "monotone" | "smooth";
+
+export type ToolcraftControlSchema = {
+  accept?: string;
+  actions?: readonly (ToolcraftActionSchema | string)[];
+  commitMode?: "content" | "setting";
+  defaultValue?: unknown;
+  description?: string;
+  disabled?: boolean;
+  disabledWhen?: ToolcraftControlDisabledConditionSchema;
+  interpolation?: ToolcraftCurveInterpolation;
+  items?: readonly ToolcraftImagePickerItemSchema[];
+  keyframeable?: boolean;
+  label?: boolean | string;
+  markerCount?: number;
+  max?: number;
+  min?: number;
+  orderRole?: ToolcraftControlOrderRole;
+  performanceReason?: string;
+  performanceRole?: ToolcraftControlPerformanceRole;
+  options?: readonly { label: string; value: string }[];
+  step?: number;
+  target: string;
+  type: string;
+  unit?: string;
+  valueLabel?: string;
+  variant?: string;
+  visibleWhen?: ToolcraftControlConditionSchema;
+  xLabel?: string;
+  yLabel?: string;
+};
+
+export type ToolcraftControlLayoutGroupSchema = {
+  columns?: ToolcraftControlLayoutGroupColumns;
+  controls: readonly string[];
+  layout: ToolcraftControlLayoutGroupLayout;
+};
+
+export type ToolcraftControlSectionSchema = {
+  actionGroup?: "primary" | "secondary";
+  controls: Record<string, ToolcraftControlSchema>;
+  layout?: ToolcraftSectionLayout;
+  layoutGroups?: readonly ToolcraftControlLayoutGroupSchema[];
+  title?: string;
+  visibleWhen?: ToolcraftControlConditionSchema;
+};
+
+export type ToolcraftControlsPanelSchema = {
+  sections: readonly ToolcraftControlSectionSchema[];
+  title: string;
+};
+
+export type ToolcraftPanelsSchema = {
+  controls?: ToolcraftControlsPanelSchema;
+  layers?: boolean;
+  timeline?: ToolcraftTimelinePanelSchema;
+};
+
+export type ResolvedToolcraftPanelsSchema = {
+  controls?: ToolcraftControlsPanelSchema;
+  layers?: boolean;
+  timeline?: ResolvedToolcraftTimelinePanelSchema;
+};
+
+export type ToolcraftAppSchema = {
+  canvas: ToolcraftCanvasSchema;
+  export?: ToolcraftExportSchema;
+  panels: ToolcraftPanelsSchema;
+  persistence?: ToolcraftPersistenceSchema;
+  settingsTransfer?: ToolcraftSettingsTransferSchema;
+  toolbar?: ToolcraftToolbarSchema;
+};
+
+export type ResolvedToolcraftAppSchema = {
+  assembly: ToolcraftAssemblyContract;
+  canvas: Required<ToolcraftCanvasSchema> & {
+    size: ToolcraftCanvasSize;
+    sizeSource: ToolcraftCanvasSizeSource;
+  };
+  export: ResolvedToolcraftExportSchema;
+  panels: ResolvedToolcraftPanelsSchema;
+  persistence: ResolvedToolcraftPersistenceSchema;
+  settingsTransfer: ResolvedToolcraftSettingsTransferSchema;
+  toolbar: Required<ToolcraftToolbarSchema>;
+};

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

@@ -0,0 +1,8 @@
+export const toolcraftCanvasZoomMin = 25;
+export const toolcraftCanvasZoomMax = 400;
+export const toolcraftCanvasZoomStep = 10;
+export const toolcraftCanvasZoomDefault = 70;
+
+export function clampToolcraftCanvasZoom(zoom: number): number {
+  return Math.min(toolcraftCanvasZoomMax, Math.max(toolcraftCanvasZoomMin, zoom));
+}