@pixel-point/toolcraft 0.0.4 → 0.0.7

package/templates/runtime/schema/types.ts

@@ -21,6 +21,24 @@ export type ToolcraftCanvasSizingSchema = {
   mode: ToolcraftCanvasSizingMode;
 };
 
+export type ToolcraftCanvasRenderScaleSchema =
+  | boolean
+  | {
+      defaultValue?: number;
+      enabled?: boolean;
+      max?: number;
+      min?: number;
+      step?: number;
+    };
+
+export type ResolvedToolcraftCanvasRenderScaleSchema = {
+  defaultValue: number;
+  enabled: boolean;
+  max: number;
+  min: number;
+  step: number;
+};
+
 export type ToolcraftPngExportBackground = "include" | "transparent";
 
 export type ToolcraftPngExportSchema = {
@@ -45,6 +63,7 @@ export type ToolcraftAssemblyComponentId =
 export type ToolcraftAssemblyCapability =
   | "canvas.draggable"
   | "canvas.editableSize"
+  | "canvas.renderScale"
   | "canvas.upload"
   | "controls.defaults"
   | "controls.panel"
@@ -76,6 +95,7 @@ export type ToolcraftAssemblyCommand =
   | "canvas.zoomReset"
   | "controls.apply"
   | "controls.reset"
+  | "controls.resetTargets"
   | "controls.setValue"
   | "history.redo"
   | "history.undo"
@@ -141,6 +161,7 @@ export type ToolcraftAssemblyContract = {
 export type ToolcraftCanvasSchema = {
   draggable?: boolean;
   enabled: boolean;
+  renderScale?: ToolcraftCanvasRenderScaleSchema;
   size?: ToolcraftCanvasSize;
   sizing?: ToolcraftCanvasSizingSchema;
   upload?: boolean;
@@ -272,6 +293,20 @@ export type ToolcraftColorOpacityValueSchema = {
   opacity?: number;
 };
 
+export type ToolcraftCollectionItemControlSchema = {
+  commitMode?: "content" | "setting";
+  defaultValue?: unknown;
+  label?: boolean | string;
+  markerCount?: number;
+  max?: number;
+  min?: number;
+  options?: readonly { label: string; value: string }[];
+  step?: number;
+  type: string;
+  unit?: string;
+  variant?: string;
+};
+
 export type ToolcraftFontPickerValueSchema = {
   color?: string;
   fontId: string;
@@ -288,22 +323,31 @@ export type ToolcraftCurveInterpolation = "monotone" | "smooth";
 export type ToolcraftControlSchema = {
   accept?: string;
   actions?: readonly (ToolcraftActionSchema | string)[];
+  addLabel?: string;
   commitMode?: "content" | "setting";
   defaultValue?: unknown;
   description?: string;
   disabled?: boolean;
   disabledWhen?: ToolcraftControlDisabledConditionSchema;
+  hardMaxItems?: number;
   interpolation?: ToolcraftCurveInterpolation;
   items?: readonly ToolcraftImagePickerItemSchema[];
+  itemControl?: ToolcraftCollectionItemControlSchema;
+  itemDefaultValue?: unknown;
+  itemLabel?: string;
   keyframeable?: boolean;
   label?: boolean | string;
   markerCount?: number;
   max?: number;
   min?: number;
+  minItems?: number;
+  multiple?: boolean;
   orderRole?: ToolcraftControlOrderRole;
   performanceReason?: string;
   performanceRole?: ToolcraftControlPerformanceRole;
   options?: readonly { label: string; value: string }[];
+  recommendedMaxItems?: number;
+  removeLabel?: string;
   step?: number;
   target: string;
   type: string;
@@ -358,7 +402,8 @@ export type ToolcraftAppSchema = {
 
 export type ResolvedToolcraftAppSchema = {
   assembly: ToolcraftAssemblyContract;
-  canvas: Required<ToolcraftCanvasSchema> & {
+  canvas: Omit<Required<ToolcraftCanvasSchema>, "renderScale"> & {
+    renderScale: ResolvedToolcraftCanvasRenderScaleSchema;
     size: ToolcraftCanvasSize;
     sizeSource: ToolcraftCanvasSizeSource;
   };

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

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

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

@@ -55,13 +55,13 @@ describe("createToolcraftState", () => {
 
     expect(state.values).toMatchObject({
       "canvas.aspectRatio": {
-        height: 1,
+        height: 9,
         mode: "preset",
-        value: "1:1",
-        width: 1,
+        value: "16:9",
+        width: 16,
       },
-      "canvas.size.height": 1024,
-      "canvas.size.width": 1024,
+      "canvas.size.height": 1080,
+      "canvas.size.width": 1920,
     });
   });
 
@@ -75,7 +75,7 @@ describe("createToolcraftState", () => {
     const state = createToolcraftState(app);
 
     expect(state.canvas.size).toEqual(size);
-    expect(state.canvas.zoom).toBe(70);
+    expect(state.canvas.zoom).toBe(100);
   });
 
   it("preserves seeded canvas width", () => {

package/templates/runtime/state/reducer.test.ts

@@ -45,6 +45,59 @@ describe("toolcraftReducer", () => {
     expect(state.history.undo.at(-1)?.label).toBe("Reset controls");
   });
 
+  it("resets selected control targets to defaults and records one history patch", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                contrast: {
+                  defaultValue: 22,
+                  target: "style.contrast",
+                  type: "slider",
+                },
+                opacity: {
+                  defaultValue: 75,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
+                },
+              },
+              title: "Tone",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const changedOpacity = toolcraftReducer(createToolcraftState(app), {
+      target: "selectedLayer.opacity",
+      type: "controls.setValue",
+      value: 12,
+    });
+    const changedBoth = toolcraftReducer(changedOpacity, {
+      target: "style.contrast",
+      type: "controls.setValue",
+      value: 9,
+    });
+
+    const state = toolcraftReducer(changedBoth, {
+      label: "Reset Tone section",
+      targets: ["selectedLayer.opacity"],
+      type: "controls.resetTargets",
+    });
+
+    expect(state.values["selectedLayer.opacity"]).toBe(75);
+    expect(state.values["style.contrast"]).toBe(9);
+    expect(state.history.undo).toHaveLength(3);
+    expect(state.history.undo.at(-1)).toMatchObject({
+      after: { "selectedLayer.opacity": 75 },
+      before: { "selectedLayer.opacity": 12 },
+      label: "Reset Tone section",
+    });
+  });
+
   it("updates canvas size and records history", () => {
     const size = { width: 1200, height: 900, unit: "px" } as const;
 
@@ -103,9 +156,15 @@ describe("toolcraftReducer", () => {
     const redone = toolcraftReducer(undone, { type: "history.redo" });
 
     expect(changed.canvas.size.width).toBe(640);
-    expect(changed.canvas.size.height).toBe(410);
+    expect(changed.canvas.size.height).toBe(768);
+    expect(changed.values["canvas.aspectRatio"]).toEqual({
+      height: 6,
+      mode: "custom",
+      value: "5:6",
+      width: 5,
+    });
     expect(changed.values["canvas.size.width"]).toBe(640);
-    expect(changed.values["canvas.size.height"]).toBe(410);
+    expect(changed.values["canvas.size.height"]).toBe(768);
     expect(changed.history.undo.at(-1)?.label).toBe("canvas.size.width");
     expect(reset.canvas.size.width).toBe(1200);
     expect(reset.canvas.size.height).toBe(768);
@@ -115,7 +174,7 @@ describe("toolcraftReducer", () => {
     expect(undone.canvas.size.width).toBe(1200);
     expect(undone.canvas.size.height).toBe(768);
     expect(redone.canvas.size.width).toBe(640);
-    expect(redone.canvas.size.height).toBe(410);
+    expect(redone.canvas.size.height).toBe(768);
   });
 
   it("routes canvas aspect ratio presets through canvas runtime state", () => {
@@ -144,7 +203,7 @@ describe("toolcraftReducer", () => {
     expect(changed.history.undo.at(-1)?.label).toBe("canvas.aspectRatio");
   });
 
-  it("keeps canvas size edits locked to the current aspect ratio", () => {
+  it("turns manual canvas size edits into a custom aspect ratio", () => {
     const state = toolcraftReducer(createState(), {
       target: "canvas.aspectRatio",
       type: "controls.setValue",
@@ -162,9 +221,47 @@ describe("toolcraftReducer", () => {
       value: "720",
     });
 
-    expect(changed.canvas.size).toEqual({ height: 720, unit: "px", width: 1280 });
+    expect(changed.canvas.size).toEqual({ height: 720, unit: "px", width: 1920 });
+    expect(changed.values["canvas.aspectRatio"]).toEqual({
+      height: 3,
+      mode: "custom",
+      value: "8:3",
+      width: 8,
+    });
     expect(changed.values["canvas.size.height"]).toBe(720);
-    expect(changed.values["canvas.size.width"]).toBe(1280);
+    expect(changed.values["canvas.size.width"]).toBe(1920);
+  });
+
+  it("keeps repeated canvas size values as no-op without changing aspect ratio mode", () => {
+    const app = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 1080, unit: "px", width: 1920 },
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+    const state = createToolcraftState(app);
+
+    const unchanged = toolcraftReducer(state, {
+      target: "canvas.size.width",
+      type: "controls.setValue",
+      value: "1920",
+    });
+
+    expect(unchanged).toBe(state);
+    expect(unchanged.values["canvas.aspectRatio"]).toEqual({
+      height: 9,
+      mode: "preset",
+      value: "16:9",
+      width: 16,
+    });
+    expect(unchanged.history.undo).toEqual([]);
   });
 
   it("updates canvas offset without recording history", () => {
@@ -225,11 +322,11 @@ describe("toolcraftReducer", () => {
     state = toolcraftReducer(state, { type: "canvas.zoomOut" });
     state = toolcraftReducer(state, { type: "canvas.zoomIn" });
 
-    expect(state.canvas.zoom).toBe(60);
+    expect(state.canvas.zoom).toBe(90);
 
     state = toolcraftReducer(state, { type: "canvas.zoomReset" });
 
-    expect(state.canvas.zoom).toBe(70);
+    expect(state.canvas.zoom).toBe(100);
   });
 
   it("sets viewport zoom and offset for gesture zoom", () => {
@@ -380,6 +477,40 @@ describe("toolcraftReducer", () => {
     });
   });
 
+  it("appends single-layer media when import is explicitly non-replacing", () => {
+    const state = createState();
+    const first = toolcraftReducer(state, {
+      asset: {
+        dataUrl: "data:image/png;base64,first",
+        fileName: "first.png",
+        mimeType: "image/png",
+        position: { x: 0, y: 0 },
+        size: state.canvas.size,
+      },
+      replaceExisting: false,
+      type: "media.import",
+    });
+    const second = toolcraftReducer(first, {
+      asset: {
+        dataUrl: "data:image/png;base64,second",
+        fileName: "second.png",
+        mimeType: "image/png",
+        position: { x: 0, y: 0 },
+        size: state.canvas.size,
+      },
+      replaceExisting: false,
+      type: "media.import",
+    });
+
+    expect(second.layers.map((layer) => layer.id)).toEqual(["layer-1", "layer-2"]);
+    expect(second.mediaAssets.map((asset) => asset.id)).toEqual(["media-1", "media-2"]);
+    expect(second.mediaAssets.map((asset) => asset.fileName)).toEqual([
+      "first.png",
+      "second.png",
+    ]);
+    expect(second.selectedLayerId).toBe("layer-2");
+  });
+
   it("adds and selects runtime layers and groups", () => {
     const withGroup = toolcraftReducer(createState(), {
       layer: {

package/templates/runtime/state/reducer.ts

@@ -133,6 +133,22 @@ function normalizeCanvasAspectRatioValue(
   return getCanvasAspectRatioFromSize(fallbackSize);
 }
 
+function canvasAspectRatioValuesEqual(
+  first: unknown,
+  second: CanvasAspectRatioValue,
+): boolean {
+  if (!isRecord(first)) {
+    return false;
+  }
+
+  return (
+    first.height === second.height &&
+    first.mode === second.mode &&
+    first.value === second.value &&
+    first.width === second.width
+  );
+}
+
 function applyCanvasAspectRatioToSize({
   anchor,
   ratio,
@@ -196,6 +212,17 @@ function getResetCanvasSize(
   };
 }
 
+function canvasSizesEqual(
+  first: ToolcraftState["canvas"]["size"],
+  second: ToolcraftState["canvas"]["size"],
+): boolean {
+  return (
+    first.height === second.height &&
+    first.unit === second.unit &&
+    first.width === second.width
+  );
+}
+
 function clampTimelineDuration(value: number): number {
   if (!Number.isFinite(value)) {
     return minTimelineDurationSeconds;
@@ -567,7 +594,7 @@ export function toolcraftReducer(
         if (
           state.canvas.size.width === size.width &&
           state.canvas.size.height === size.height &&
-          Object.is(state.values[command.target], ratio)
+          canvasAspectRatioValuesEqual(state.values[command.target], ratio)
         ) {
           return state;
         }
@@ -599,44 +626,42 @@ export function toolcraftReducer(
           return state;
         }
 
-        const hasAspectRatioLock =
+        const hasAspectRatioControl =
           canvasAspectRatioTarget in state.values ||
           canvasAspectRatioTarget in state.defaults;
-        const size = hasAspectRatioLock
-          ? applyCanvasAspectRatioToSize({
-              anchor: canvasSizeDimension,
-              ratio: normalizeCanvasAspectRatioValue(
-                state.values[canvasAspectRatioTarget],
-                state.canvas.size,
-              ),
-              size: state.canvas.size,
-              value: dimensionValue,
-            })
-          : {
-              ...state.canvas.size,
-              [canvasSizeDimension]: dimensionValue,
-            };
+        const size = {
+          ...state.canvas.size,
+          [canvasSizeDimension]: dimensionValue,
+        };
+        const aspectRatio = getCanvasAspectRatioFromSize(size);
         const targetValue = size[canvasSizeDimension];
         const otherTarget =
           canvasSizeDimension === "width" ? canvasSizeHeightTarget : canvasSizeWidthTarget;
         const otherValue = canvasSizeDimension === "width" ? size.height : size.width;
 
-        if (
+        const sizeUnchanged =
           state.canvas.size.width === size.width &&
           state.canvas.size.height === size.height &&
           state.values[command.target] === targetValue &&
-          state.values[otherTarget] === otherValue
-        ) {
+          state.values[otherTarget] === otherValue;
+
+        if (sizeUnchanged) {
           return state;
         }
 
         return commitStatePatch(state, {
           after: {
+            ...(hasAspectRatioControl
+              ? { [canvasAspectRatioTarget]: aspectRatio }
+              : {}),
             "canvas.size": size,
             [command.target]: targetValue,
             [otherTarget]: otherValue,
           },
           before: {
+            ...(hasAspectRatioControl
+              ? { [canvasAspectRatioTarget]: state.values[canvasAspectRatioTarget] }
+              : {}),
             "canvas.size": state.canvas.size,
             [command.target]: state.values[command.target],
             [otherTarget]: state.values[otherTarget],
@@ -698,6 +723,42 @@ export function toolcraftReducer(
       );
     }
 
+    case "controls.resetTargets": {
+      const targetSet = new Set(command.targets);
+      const before: Record<string, unknown> = {};
+      const after: Record<string, unknown> = {};
+
+      for (const target of targetSet) {
+        if (!(target in state.defaults) || Object.is(state.values[target], state.defaults[target])) {
+          continue;
+        }
+
+        before[target] = state.values[target];
+        after[target] = state.defaults[target];
+      }
+
+      const resetCanvasSize = getResetCanvasSize(state);
+      const shouldResetCanvasSize =
+        resetCanvasSize !== null &&
+        (targetSet.has(canvasSizeWidthTarget) || targetSet.has(canvasSizeHeightTarget)) &&
+        !canvasSizesEqual(state.canvas.size, resetCanvasSize);
+
+      if (shouldResetCanvasSize) {
+        before["canvas.size"] = state.canvas.size;
+        after["canvas.size"] = resetCanvasSize;
+      }
+
+      if (Object.keys(after).length === 0) {
+        return state;
+      }
+
+      return commitStatePatch(state, {
+        after,
+        before,
+        label: command.label ?? "Reset section",
+      });
+    }
+
     case "layers.add": {
       const layer = createLayer(state, command.layer);
       const insertIndex = clampInsertIndex(state.layers.length, command.insertIndex);
@@ -1014,13 +1075,18 @@ export function toolcraftReducer(
       };
 
     case "media.import": {
-      const shouldReplaceSingleLayerMedia = !state.schema.panels.layers;
+      const shouldReplaceSingleLayerMedia =
+        !state.schema.panels.layers && command.replaceExisting !== false;
       const shouldResizeCanvas =
         state.schema.canvas.sizing.mode === "intrinsic-media";
       const layerId =
-        command.asset.layerId ?? getSingleLayerImportId(state) ?? getNextLayerId(state);
+        command.asset.layerId ??
+        (shouldReplaceSingleLayerMedia ? getSingleLayerImportId(state) : undefined) ??
+        getNextLayerId(state);
       const mediaId =
-        command.asset.id ?? getSingleMediaImportId(state) ?? getNextMediaId(state);
+        command.asset.id ??
+        (shouldReplaceSingleLayerMedia ? getSingleMediaImportId(state) : undefined) ??
+        getNextMediaId(state);
       const layer = {
         displayName: command.asset.layerName ?? getImportedLayerName(command.asset.fileName),
         id: layerId,

package/templates/runtime/state/types.ts

@@ -11,6 +11,7 @@ export type ToolcraftCommand =
     }
   | { type: "controls.apply" }
   | { type: "controls.reset" }
+  | { label?: string; targets: string[]; type: "controls.resetTargets" }
   | { insertIndex?: number; layer?: ToolcraftLayerDraft; type: "layers.add" }
   | { layerId: string; type: "layers.delete" }
   | { layerIds: string[]; parentGroupId: string | null; type: "layers.moveToGroup" }
@@ -39,6 +40,7 @@ export type ToolcraftCommand =
         layerId?: string;
         layerName?: string;
       };
+      replaceExisting?: boolean;
       type: "media.import";
     }
   | { mediaId: string; type: "media.delete" }
@@ -81,6 +83,7 @@ export const toolcraftRuntimeCommandTypes = [
   "controls.setValue",
   "controls.apply",
   "controls.reset",
+  "controls.resetTargets",
   "layers.add",
   "layers.delete",
   "layers.moveToGroup",

package/templates/starter/AGENTS.md

@@ -23,7 +23,7 @@ Then follow `workflow.md` to choose the required contract docs and verification
 9. Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions, then resume without changing user playback state.
 10. If a Figma URL is provided, inspect the Figma file through MCP and rebuild from its structure; never implement from a screenshot or by eye.
 11. Choose an explicit persistence policy; use schema `persistence` for user-edited app settings that should survive reload, and test real reload restoration when localStorage is enabled.
-12. Use schema `settingsTransfer: "auto"` for complex apps that need import/export of control settings; never implement settings import/export through `panelActions` or route-local file inputs. After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are owned by `editable-output` canvas sizing, not by settings transfer. Runtime aspect presets apply canonical canvas sizes, with `16:9` equal to `1920x1080`. When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order and renders without a visible section heading.
+12. Use schema `settingsTransfer: "auto"` for complex apps that need import/export of control settings; never implement settings import/export through `panelActions` or route-local file inputs. After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are owned by `editable-output` canvas sizing, not by settings transfer. Runtime aspect presets apply canonical canvas sizes, with `16:9` equal to `1920x1080`; manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in custom ratio inputs; when no explicit product size is provided, the runtime default canvas size is also `1920x1080`. Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`; the first technical runtime section then appends `Resolution scale` after canvas sizing so backing pixels can increase up to 2x without changing CSS/output size. Performance fixes must preserve the selected render scale and keep canvas preview responsive to sliders/high-frequency controls at that scale; diagnose the bottleneck before reducing quality. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping `canvas.renderScale` below the user's chosen value. When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and, for raster outputs, `Resolution scale` in that order and renders without a visible section heading.
 13. Product apps expose a required `Background` section directly before export settings. It contains a Switch labeled `Include` and a background color control with `label: false` in one equal-width inline row; PNG export wires those runtime values into the standard export helper while live preview, workspace canvas backing, and video export keep the background. Every app with `Export PNG` exposes `Image Export` with `export.image.format` and `export.image.resolution` as two `select` controls in one compact two-column inline row, and passes the selected resolution to `createToolcraftPngExportCanvas({ resolution })` so 2K/4K/8K change actual PNG dimensions. Animated apps with both PNG and video export place `Image Export` immediately before `Video Export`.
 14. Keep `docs/toolcraft/agent-worklog.md` current with a decision trail, product decisions, evidence, verification, and risks.
 15. Prove every visible entity through acceptance, browser, and performance coverage.
@@ -111,7 +111,7 @@ AI must work on this app through the required workflow skills when the environme
 - Before editing code from an approved spec, use `writing-plans` to produce a deterministic implementation plan focused on app files, tests, build, and browser verification.
 - Before fixing any broken control, failed test, build failure, visual mismatch, export issue, or runtime regression, use `systematic-debugging` to find the root cause first.
 - When the prompt includes a Figma URL, use Figma MCP/design context before implementation. Read the actual node, layer, component, variable, and asset structure; screenshots are only for final visual QA, not the source of truth.
-- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The automated browser gates are `pnpm test:browser` and `pnpm test:browser:perf`.
+- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The default browser gate is `pnpm test:browser`; `pnpm test:browser:perf` is reserved for full performance checkpoints.
 - Run `pnpm ai:check` before app generation or major changes.
 - If a required skill is missing and the environment supports skill installation, install it before implementation and restart or refresh the session if the skill list does not update.
 - If skill installation is not available, stop before implementation and tell the user exactly which required skills are missing.
@@ -139,16 +139,16 @@ Choose the tier by blast radius, not by line count. If uncertain, move one tier
 | Tier 0 — docs/copy | Documentation, comments, copy, labels, or titles change without schema targets, values, runtime behavior, renderer output, or layout mechanics. | Targeted docs/typecheck or targeted app test. Browser is not required unless visual text fitting is the risk. |
 | Tier 1 — local control presentation | One control or panel visual state changes: spacing, hover, focus, disabled, marker visibility, label fit, or component variant display. Runtime state shape and product renderer are unchanged. | Targeted unit/component test plus one focused browser check for the affected control or panel. |
 | Tier 2 — schema/product behavior | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes. | `pnpm verify:quick` plus relevant browser acceptance. Run perf only when the changed control affects renderer workload or responsiveness. |
-| Tier 3 — renderer/canvas/runtime feature | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability. | `pnpm verify:quick`, targeted browser acceptance, and relevant `pnpm verify:perf` scenarios for touched workload/viewport/export paths. |
-| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once, then `pnpm verify:final`, then start `pnpm dev` to provide the local URL. |
+| Tier 3 — renderer/canvas/runtime feature | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability. | `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths. |
+| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once, then `pnpm verify:final`; add `pnpm verify:perf` only for the first working app version or explicit performance complaints, then start `pnpm dev` to provide the local URL. |
 
 Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
 
-Do not run the full browser performance suite for Tier 0-2 edits unless a performance checkpoint trigger applies.
+Do not run the full browser performance suite for Tier 0-2 edits.
 
-Run a full performance checkpoint with `pnpm verify:perf` when the first working version of an app exists, when renderer/canvas/animation/export/timeline/layers change, after fixing a bug that previously broke functionality, after any performance optimization, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+Run a full performance checkpoint with `pnpm verify:perf` only when the first working version of an app exists, or when the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
 
-Fast feature loops may defer full performance only when none of the checkpoint triggers above apply. Record the deferred check and reason in the verification note or worklog.
+Feature loops after the first working version do not run the full performance suite by default. Renderer, canvas, animation, export, timeline, layers, `canvas.renderScale`, bug fixes, and performance-sensitive controls still need targeted functional/browser checks first, plus targeted performance scenarios only when they directly exercise the touched workload/viewport/export path. Record any skipped full performance run and reason in the verification note or worklog.
 
 ## Required Checks
 
@@ -161,7 +161,7 @@ pnpm dev
 
 Use `pnpm install` before this final gate when the folder is fresh or dependencies changed.
 
-`pnpm test` must include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output. `pnpm verify:perf` / `pnpm test:browser:perf` must run the performance browser suite sequentially so budgets are measured without parallel e2e noise.
+`pnpm test` must include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output. `pnpm verify:perf` / `pnpm test:browser:perf` remains available for the two full-performance triggers and must run the performance browser suite sequentially so budgets are measured without parallel e2e noise.
 
 Do not stop or kill existing local servers to free a port. `pnpm dev`, `pnpm preview`, and browser verification prefer port `3002`, but automatically move to the next free port when it is busy. Use `TOOLCRAFT_PORT`, `TOOLCRAFT_DEV_PORT`, or `TOOLCRAFT_TEST_PORT` only to change the preferred starting port.
 

package/templates/starter/docs/toolcraft/README.md

@@ -26,15 +26,16 @@ Every implementation pass must choose a verification tier before editing. Use th
 | Tier 0 | Docs/copy only | targeted docs/typecheck |
 | Tier 1 | One control or panel visual state | targeted test + focused browser check |
 | Tier 2 | Schema, defaults, persistence, actions, product mapping | `pnpm verify:quick` + relevant browser acceptance |
-| Tier 3 | Renderer, canvas, timeline, layers, upload, export, zoom, heavy controls, or a performance checkpoint trigger | `pnpm verify:quick` + targeted browser/perf scenarios |
-| Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final` |
+| Tier 3 | Renderer, canvas, timeline, layers, upload, export, zoom, heavy controls, or a touched performance-sensitive path | `pnpm verify:quick` + targeted browser checks, plus targeted perf scenarios only for the touched path |
+| Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final`; add `pnpm verify:perf` only for the first working app version or explicit performance complaints |
 
-Run `pnpm verify:perf` when a performance checkpoint is triggered: first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+Run the full `pnpm verify:perf` suite only when the first working app version exists, or when the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
 
 Fresh folders or dependency changes need `pnpm install` before verification. Final delivery still starts the local app after the gate:
 
 ```bash
 pnpm verify:final
+pnpm verify:perf # first working version or explicit performance complaint only
 pnpm dev
 ```
 

package/templates/starter/docs/toolcraft/acceptance-testing.md

@@ -14,9 +14,9 @@ Every visible product entity must prove it works. A control is not accepted beca
 - `e2e/app-performance.spec.ts`
 - `e2e/product-observable-helpers.ts`
 
-`pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add `pnpm verify:perf` whenever a performance checkpoint is triggered.
+`pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add full `pnpm verify:perf` only for the first working app version or an explicit performance complaint.
 
-A performance checkpoint is triggered by the first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+A full performance checkpoint is triggered only by the first working app version, or by a user request to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise investigate poor performance.
 
 ## Product Readiness
 
@@ -72,6 +72,7 @@ Required parts:
 | --- | --- |
 | `anchorGrid` | `anchorGrid.position` |
 | `channelMixer` | `channelMixer.activeChannel`, `channelMixer.values`; only for RGB channel matrix behavior |
+| `collectionActions` | `collectionActions.add`, `collectionActions.remove`, `collectionActions.items` |
 | `colorOpacity` | `colorOpacity.hex`, `colorOpacity.opacity` |
 | `curves` | RGB variant: `curves.activeChannel`, `curves.points`; `variant: "single"`: `curves.points` |
 | `fontPicker` | `fontPicker.fontId`, `fontPicker.fontWeight`, `fontPicker.fontSize`, `fontPicker.letterSpacing`, `fontPicker.lineHeight`, `fontPicker.textCase`, `fontPicker.color`, `fontPicker.opacity` |
@@ -97,6 +98,7 @@ High-confidence wrong-substitution cases:
 - typography without `fontPicker`;
 - sibling typography controls that split case, color, opacity, size, weight, letter spacing, or line height away from `fontPicker`;
 - color plus opacity without `colorOpacity`;
+- repeatable user-editable item sets without `collectionActions` or another justified collection owner;
 - from/to range without `rangeSlider` or `rangeInput`;
 - curve, remap, easing, or response without `curves`;
 - position, direction, focus, or vector without `vector`;
@@ -146,6 +148,8 @@ Footer action acceptance must not include Reset. Reset is already available in t
 
 Local `actions` acceptance must click every visible action and prove the nearby entity changed through runtime state or product output. A section-level `Randomize palette` must change palette output, `Normalize weights` must change weights/output, and `Clear selection` must clear only the scoped selection. Do not accept a test that only proves the button rendered.
 
+`collectionActions` acceptance must click plus and minus in the real panel, prove the runtime target array length changes, prove `minItems` prevents invalid removal, prove `recommendedMaxItems` is not a hidden hard limit, and prove preview/export consumes the changed item list.
+
 PNG export tests must prove runtime background behavior: changing the background color affects preview/export, turning `export.includeBackground` off creates transparent PNG output while live preview, workspace canvas backing, and video keep the background, turning it on includes the current background color in PNG, and exported pixel dimensions are retina size, at least `state.canvas.size * 2`.
 
 Invalid final acceptance evidence: