@pixel-point/toolcraft 0.0.6 → 0.0.8

package/templates/runtime/contracts/decision-contracts.ts

@@ -177,7 +177,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Product-output apps expose final output delivery through sticky footer panelActions.",
     desiredBehavior:
-      'Static products include Export PNG plus an "Image Export" section for format and 2K/4K/8K resolution; animated products include Export Video and Export PNG plus "Video Export" settings. Copy can be secondary, but it does not replace export. Product apps expose a required "Background" section directly before export settings, with a Switch labeled "Include" and a background color control with label false in one equal-width row. Standard export helpers own runtime PNG transparency and selected image dimensions or retina fallback, while live preview, workspace canvas backing, and video keep the background.',
+      'Static products include Export PNG plus an "Image Export" section for format and 2K/4K/8K resolution; animated products include Export Video and Export PNG plus "Video Export" settings. Copy can be secondary, but it does not replace export. Product apps expose a required "Background" section directly before export settings, with a Switch labeled "Include" and a background color control with label false in one equal-width row. Standard helpers own runtime PNG transparency, live preview product-background visibility, and selected image dimensions or retina fallback, while Toolcraft canvas backing and video keep the background.',
     enforcement: ["acceptance-validator", "performance-validator", "browser-helper", "starter-agents"],
     id: "output-export-required",
     level: "invariant",
@@ -237,7 +237,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Performance coverage currently asks every visible non-action control for a performance scenario.",
     desiredBehavior:
-      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required when the first working version of an app exists, when renderer/canvas/animation/export/timeline/layers change, when canvas.renderScale or the Resolution scale retina slider is added/enabled, after fixing a bug that previously broke functionality, after any performance optimization, and whenever the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom. Performance fixes must preserve the selected render scale and must not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping canvas.renderScale below the user's chosen value. Browser performance tests read budgets from typed performance config and run sequentially for stable measurements.",
+      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required only when the first working version of an app exists, or whenever the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive controls need targeted functional/browser checks first and targeted performance scenarios only for touched workload/viewport/export paths. Performance fixes must preserve the selected render scale and must not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping canvas.renderScale below the user's chosen value. Browser performance tests read budgets from typed performance config and run sequentially for stable measurements.",
     enforcement: ["performance-validator", "browser-helper", "starter-agents"],
     id: "performance-coverage-levels",
     level: "invariant",

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

@@ -8,6 +8,7 @@ import {
   getToolcraftRetinaExportPixelRatio,
   getToolcraftRetinaExportSize,
   shouldIncludeToolcraftExportBackground,
+  shouldIncludeToolcraftPreviewBackground,
 } from "./export";
 
 function createState(schema = defineToolcraft({ canvas: { enabled: true }, panels: {} })): ToolcraftState {
@@ -89,6 +90,36 @@ describe("Toolcraft export helpers", () => {
     expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
   });
 
+  it("uses include-background runtime state for live preview background", () => {
+    const state = createState();
+
+    expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(true);
+
+    state.values["export.includeBackground"] = false;
+    expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(false);
+
+    state.values["export.includeBackground"] = true;
+    expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(true);
+  });
+
+  it("keeps video export background independent from preview include state", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      export: {
+        png: {
+          background: "transparent",
+        },
+      },
+      panels: {},
+    });
+    const state = createState(schema);
+
+    state.values["export.includeBackground"] = false;
+
+    expect(shouldIncludeToolcraftPreviewBackground({ state })).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);

package/templates/runtime/export/export.ts

@@ -16,6 +16,11 @@ export type ToolcraftExportBackgroundOptions = {
   schema: ResolvedToolcraftAppSchema;
 };
 
+export type ToolcraftPreviewBackgroundOptions = {
+  includeBackgroundTarget?: string;
+  state: ToolcraftState;
+};
+
 export type ToolcraftExportSizeOptions = {
   devicePixelRatio?: number;
   state: ToolcraftState;
@@ -129,6 +134,42 @@ export function shouldIncludeToolcraftExportBackground({
   return schema.export.png.background !== "transparent";
 }
 
+export function shouldIncludeToolcraftPreviewBackground({
+  includeBackgroundTarget = "export.includeBackground",
+  state,
+}: ToolcraftPreviewBackgroundOptions): boolean {
+  const includeBackgroundValue = state.values[includeBackgroundTarget];
+
+  if (typeof includeBackgroundValue === "boolean") {
+    return includeBackgroundValue;
+  }
+
+  if (typeof includeBackgroundValue === "string") {
+    const normalizedValue = includeBackgroundValue.trim().toLowerCase();
+
+    if (
+      normalizedValue === "false" ||
+      normalizedValue === "off" ||
+      normalizedValue === "no" ||
+      normalizedValue === "transparent" ||
+      normalizedValue === "exclude"
+    ) {
+      return false;
+    }
+
+    if (
+      normalizedValue === "true" ||
+      normalizedValue === "on" ||
+      normalizedValue === "yes" ||
+      normalizedValue === "include"
+    ) {
+      return true;
+    }
+  }
+
+  return true;
+}
+
 export function createToolcraftPngExportCanvas({
   background = "#000000",
   canvasFactory = () => document.createElement("canvas"),

package/templates/runtime/react/canvas-shell.test.tsx

@@ -43,7 +43,13 @@ function CanvasStateProbe() {
       <span data-testid="canvas-zoom">{state.canvas.zoom}</span>
       <span data-testid="media-count">{state.mediaAssets.length}</span>
       <span data-testid="media-size">
-        {state.mediaAssets[0]?.size.width ?? 0},{state.mediaAssets[0]?.size.height ?? 0}
+        {state.mediaAssets[0]?.size?.width ?? 0},{state.mediaAssets[0]?.size?.height ?? 0}
+      </span>
+      <span data-testid="media-targets">
+        {state.mediaAssets.map((asset) => asset.sourceTarget ?? "none").join(",")}
+      </span>
+      <span data-testid="media-kinds">
+        {state.mediaAssets.map((asset) => asset.assetKind ?? "image").join(",")}
       </span>
     </>
   );
@@ -376,6 +382,76 @@ describe("CanvasShell", () => {
     expect(screen.getByRole("button", { name: "Select material.png" })).toBeTruthy();
   });
 
+  it("routes canvas drops to image and file upload targets by asset kind", async () => {
+    const schema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { width: 300, height: 200, unit: "px" },
+        upload: true,
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                files: {
+                  assetKind: "file",
+                  label: "Files",
+                  multiple: true,
+                  target: "source.files",
+                  type: "fileDrop",
+                },
+                image: {
+                  label: "Image",
+                  target: "source.image",
+                  type: "fileDrop",
+                },
+              },
+              title: "Sources",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    render(
+      <ToolcraftRoot schema={schema}>
+        <div style={{ height: 640, position: "relative", width: 640 }}>
+          <CanvasShell />
+          <CanvasStateProbe />
+        </div>
+      </ToolcraftRoot>,
+    );
+
+    const canvas = screen.getByRole("application", { name: "Canvas viewport" });
+    const imageFile = new File(["image"], "material.png", { type: "image/png" });
+    const textFile = new File(["notes"], "notes.txt", { type: "text/plain" });
+
+    fireEvent.drop(canvas, {
+      clientX: 0,
+      clientY: 0,
+      dataTransfer: {
+        files: [imageFile, textFile],
+      },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("media-count").textContent).toBe("2");
+    });
+
+    expect(screen.getByTestId("media-targets").textContent?.split(",").sort()).toEqual([
+      "source.files",
+      "source.image",
+    ]);
+    expect(screen.getByTestId("media-kinds").textContent?.split(",").sort()).toEqual([
+      "file",
+      "image",
+    ]);
+    expect(screen.getByRole("button", { name: "Select material.png" })).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "Select notes.txt" })).toBeNull();
+  });
+
   it("hides media when a parent layer group is hidden", () => {
     render(
       <ToolcraftRoot

package/templates/runtime/react/canvas-shell.tsx

@@ -3,9 +3,22 @@
 import * as React from "react";
 
 import { clampToolcraftCanvasZoom } from "../state/canvas-zoom";
-import type { ToolcraftPoint } from "../state/types";
+import type {
+  ToolcraftMediaAsset,
+  ToolcraftPoint,
+  ToolcraftState,
+} from "../state/types";
+import type { ToolcraftControlSchema } from "../schema/types";
+import {
+  isToolcraftControlVisible,
+  isToolcraftSectionVisible,
+} from "./control-conditions";
 import { isToolcraftLayerVisibleInTree } from "./layer-tree";
-import { readImportedImageFile } from "./media-file";
+import {
+  isToolcraftImageFile,
+  readImportedFile,
+  readImportedImageFile,
+} from "./media-file";
 import { useToolcraft } from "./use-toolcraft";
 
 export type CanvasShellProps = {
@@ -20,6 +33,9 @@ type CanvasDragState = {
   startX: number;
   startY: number;
 };
+type ToolcraftCanvasImageAsset = ToolcraftMediaAsset & {
+  size: NonNullable<ToolcraftMediaAsset["size"]>;
+};
 
 const wheelZoomSensitivity = 0.12;
 const wheelPinchZoomSensitivity = 0.5;
@@ -28,13 +44,6 @@ function cn(...classNames: Array<string | false | null | undefined>): string {
   return classNames.filter(Boolean).join(" ");
 }
 
-function isImageFile(file: File): boolean {
-  return (
-    file.type.startsWith("image/") ||
-    /\.(avif|gif|jpe?g|png|svg|webp)$/i.test(file.name)
-  );
-}
-
 function isDragLeavingCurrentTarget(
   event: React.DragEvent<HTMLElement>,
 ): boolean {
@@ -79,6 +88,94 @@ function getNextWheelZoom(
   return clampToolcraftCanvasZoom(currentZoom + zoomDelta);
 }
 
+function getFileExtension(file: File): string {
+  const match = /\.([a-z0-9]+)$/iu.exec(file.name);
+
+  return match?.[1]?.toLowerCase() ?? "";
+}
+
+function controlAcceptsFile(control: ToolcraftControlSchema, file: File): boolean {
+  const accept = control.accept?.trim();
+
+  if (!accept) {
+    return control.assetKind === "file" || isToolcraftImageFile(file);
+  }
+
+  const fileExtension = getFileExtension(file);
+  const mimeType = file.type.toLowerCase();
+
+  return accept.split(",").some((rawToken) => {
+    const token = rawToken.trim().toLowerCase();
+
+    if (!token) {
+      return false;
+    }
+
+    if (token.startsWith(".")) {
+      return token.slice(1) === fileExtension;
+    }
+
+    if (token.endsWith("/*")) {
+      const prefix = token.slice(0, -1);
+
+      return mimeType.startsWith(prefix);
+    }
+
+    if (token.includes("/")) {
+      return mimeType === token;
+    }
+
+    return token === fileExtension;
+  });
+}
+
+function getVisibleFileDropControls(state: ToolcraftState): ToolcraftControlSchema[] {
+  return (state.schema.panels.controls?.sections ?? []).flatMap((section) => {
+    if (!isToolcraftSectionVisible(state, section)) {
+      return [];
+    }
+
+    return Object.values(section.controls).filter(
+      (control) =>
+        control.type === "fileDrop" && isToolcraftControlVisible(state, control),
+    );
+  });
+}
+
+function getCanvasDropTarget(
+  state: ToolcraftState,
+  file: File,
+): ToolcraftControlSchema | null {
+  const isImage = isToolcraftImageFile(file);
+  const controls = getVisibleFileDropControls(state).filter((control) =>
+    controlAcceptsFile(control, file),
+  );
+  const preferredAssetKind = isImage ? "image" : "file";
+  const exactMatch = controls.find(
+    (control) =>
+      (control.assetKind === "file" ? "file" : "image") === preferredAssetKind,
+  );
+
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  return isImage
+    ? (controls.find((control) => control.assetKind === "file") ?? null)
+    : null;
+}
+
+function isDefaultCanvasImageAsset(
+  state: ToolcraftState,
+  mediaAsset: ToolcraftMediaAsset,
+): mediaAsset is ToolcraftCanvasImageAsset {
+  return (
+    (mediaAsset.assetKind ?? "image") === "image" &&
+    mediaAsset.size !== undefined &&
+    isToolcraftLayerVisibleInTree(state.layers, mediaAsset.layerId)
+  );
+}
+
 function getZoomedCanvasOffset({
   clientX,
   clientY,
@@ -122,7 +219,7 @@ export function CanvasShell({
   const visibleMediaAssets = React.useMemo(
     () =>
       state.mediaAssets.filter((mediaAsset) =>
-        isToolcraftLayerVisibleInTree(state.layers, mediaAsset.layerId),
+        isDefaultCanvasImageAsset(state, mediaAsset),
       ),
     [state.layers, state.mediaAssets],
   );
@@ -279,28 +376,86 @@ export function CanvasShell({
     event.preventDefault();
     setDragOver(false);
 
-    const uploadedFile = Array.from(event.dataTransfer?.files ?? [])[0];
+    const uploadedFiles = Array.from(event.dataTransfer?.files ?? []);
 
-    if (!uploadedFile || !isImageFile(uploadedFile)) {
+    if (uploadedFiles.length === 0) {
       return;
     }
 
     const position = getCanvasPositionFromEvent(event, offset, zoom);
+    const hasFileDropControls = getVisibleFileDropControls(state).length > 0;
+
+    uploadedFiles.forEach((uploadedFile) => {
+      const targetControl = getCanvasDropTarget(state, uploadedFile);
 
-    void readImportedImageFile(uploadedFile, size).then((importedImage) => {
-      if (!importedImage) {
+      if (!targetControl) {
+        if (hasFileDropControls || !isToolcraftImageFile(uploadedFile)) {
+          return;
+        }
+
+        void readImportedImageFile(uploadedFile, size).then((importedImage) => {
+          if (!importedImage) {
+            return;
+          }
+
+          dispatch({
+            asset: {
+              assetKind: "image",
+              dataUrl: importedImage.dataUrl,
+              fileName: uploadedFile.name,
+              mimeType: uploadedFile.type || "image/*",
+              position,
+              size: importedImage.size,
+            },
+            type: "media.import",
+          });
+        });
         return;
       }
 
-      dispatch({
-        asset: {
-          dataUrl: importedImage.dataUrl,
-          fileName: uploadedFile.name,
-          mimeType: uploadedFile.type || "image/*",
-          position,
-          size: importedImage.size,
-        },
-        type: "media.import",
+      const assetKind = targetControl.assetKind === "file" ? "file" : "image";
+      const replaceExisting = targetControl.multiple !== true;
+
+      if (assetKind === "file") {
+        void readImportedFile(uploadedFile).then((importedFile) => {
+          if (!importedFile) {
+            return;
+          }
+
+          dispatch({
+            asset: {
+              assetKind: "file",
+              dataUrl: importedFile.dataUrl,
+              fileName: uploadedFile.name,
+              mimeType: uploadedFile.type || "application/octet-stream",
+              position: { x: 0, y: 0 },
+              sourceTarget: targetControl.target,
+            },
+            replaceExisting,
+            type: "media.import",
+          });
+        });
+        return;
+      }
+
+      void readImportedImageFile(uploadedFile, size).then((importedImage) => {
+        if (!importedImage) {
+          return;
+        }
+
+        dispatch({
+          asset: {
+            assetKind: "image",
+            dataUrl: importedImage.dataUrl,
+            fileName: uploadedFile.name,
+            mimeType: uploadedFile.type || "image/*",
+            position,
+            size: importedImage.size,
+            sourceTarget: targetControl.target,
+          },
+          replaceExisting,
+          type: "media.import",
+        });
       });
     });
   };

package/templates/runtime/react/control-conditions.ts

@@ -0,0 +1,166 @@
+import {
+  getToolcraftCanvasSizeTargetDimension,
+} from "../schema/runtime-targets";
+import type {
+  ToolcraftControlConditionSchema,
+  ToolcraftControlSchema,
+  ToolcraftControlSectionSchema,
+} from "../schema/types";
+import type { ToolcraftState } from "../state/types";
+
+function valuesEqual(first: unknown, second: unknown): boolean {
+  if (Object.is(first, second)) {
+    return true;
+  }
+
+  if (
+    (typeof first !== "object" || first === null) &&
+    (typeof second !== "object" || second === null)
+  ) {
+    return false;
+  }
+
+  try {
+    return JSON.stringify(first) === JSON.stringify(second);
+  } catch {
+    return false;
+  }
+}
+
+function valuesInclude(value: unknown, options: readonly unknown[]): boolean {
+  return options.some((option) => valuesEqual(value, option));
+}
+
+function readComparableNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const numberValue = Number(value.trim());
+
+    return Number.isFinite(numberValue) ? numberValue : null;
+  }
+
+  return null;
+}
+
+function compareConditionNumbers(
+  value: unknown,
+  expected: number | undefined,
+  comparator: (value: number, expected: number) => boolean,
+): boolean | null {
+  if (typeof expected !== "number" || !Number.isFinite(expected)) {
+    return null;
+  }
+
+  const numberValue = readComparableNumber(value);
+
+  return numberValue === null ? false : comparator(numberValue, expected);
+}
+
+function getControlDefaultValueByTarget(
+  sections: readonly ToolcraftControlSectionSchema[],
+  target: string,
+): unknown {
+  for (const section of sections) {
+    for (const control of Object.values(section.controls)) {
+      if (control.target === target) {
+        return control.defaultValue;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+export function getToolcraftTargetValue(
+  state: ToolcraftState,
+  target: string,
+): unknown {
+  const canvasSizeDimension = getToolcraftCanvasSizeTargetDimension(target);
+
+  return canvasSizeDimension
+    ? state.canvas.size[canvasSizeDimension]
+    : (state.values[target] ??
+        getControlDefaultValueByTarget(
+          state.schema.panels.controls?.sections ?? [],
+          target,
+        ));
+}
+
+export function toolcraftConditionMatches(
+  state: ToolcraftState,
+  condition: ToolcraftControlConditionSchema,
+): boolean {
+  const value = getToolcraftTargetValue(state, condition.target);
+  const matches: boolean[] = [];
+
+  if ("equals" in condition) {
+    matches.push(valuesEqual(value, condition.equals));
+  }
+
+  if ("notEquals" in condition) {
+    matches.push(!valuesEqual(value, condition.notEquals));
+  }
+
+  if (Array.isArray(condition.oneOf)) {
+    matches.push(valuesInclude(value, condition.oneOf));
+  }
+
+  if (Array.isArray(condition.notOneOf)) {
+    matches.push(!valuesInclude(value, condition.notOneOf));
+  }
+
+  const greaterThan = compareConditionNumbers(
+    value,
+    condition.greaterThan,
+    (numberValue, expected) => numberValue > expected,
+  );
+  const greaterThanOrEqual = compareConditionNumbers(
+    value,
+    condition.greaterThanOrEqual,
+    (numberValue, expected) => numberValue >= expected,
+  );
+  const lessThan = compareConditionNumbers(
+    value,
+    condition.lessThan,
+    (numberValue, expected) => numberValue < expected,
+  );
+  const lessThanOrEqual = compareConditionNumbers(
+    value,
+    condition.lessThanOrEqual,
+    (numberValue, expected) => numberValue <= expected,
+  );
+
+  for (const match of [
+    greaterThan,
+    greaterThanOrEqual,
+    lessThan,
+    lessThanOrEqual,
+  ]) {
+    if (match !== null) {
+      matches.push(match);
+    }
+  }
+
+  return matches.length > 0 && matches.every(Boolean);
+}
+
+export function isToolcraftSectionVisible(
+  state: ToolcraftState,
+  section: ToolcraftControlSectionSchema,
+): boolean {
+  return section.visibleWhen
+    ? toolcraftConditionMatches(state, section.visibleWhen)
+    : true;
+}
+
+export function isToolcraftControlVisible(
+  state: ToolcraftState,
+  control: ToolcraftControlSchema,
+): boolean {
+  return control.visibleWhen
+    ? toolcraftConditionMatches(state, control.visibleWhen)
+    : true;
+}