@pixel-point/toolcraft 0.0.4 → 0.0.7

package/templates/starter/docs/toolcraft/assembly-workflow.md

@@ -146,7 +146,9 @@ Async product actions such as Export, Download, Copy, Generate, or Apply must re
 
 For complex apps, use schema `settingsTransfer: "auto"` or `true` for settings import/export. Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Do not put Import Settings or Export Settings in sticky footer `panelActions`; runtime inserts the technical `Setup` settings-transfer section first without a visible section heading.
 
-If the app also uses `editable-output` canvas sizing, that first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
+If the app also uses `editable-output` canvas sizing, that first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and optional `Resolution scale` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
+
+For non-vector raster, Canvas 2D, WebGL, or WebGPU previews, set `canvas.renderScale: true`. Runtime appends `Resolution scale` to the same first technical section. The slider changes backing resolution from `1x` to `2x` without changing visible canvas size; DOM/SVG/vector-native previews should not use it.
 
 If a controls panel shows only `Export Settings` and `Import Settings` in the first runtime section, check the canvas sizing decision. Product-output apps usually need `editable-output`; intrinsic media and explicitly fixed output are the cases where visible canvas size inputs are absent.
 
@@ -188,8 +190,8 @@ Use these tiers:
 | 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. |
 
 Choose the tier by blast radius, not by line count. If uncertain, move one tier higher, not automatically to Tier 4.
 
@@ -197,9 +199,9 @@ Do not rerun `pnpm install` after every edit. Run it after fresh export, depende
 
 Use `pnpm verify:ui` when a tier calls for the browser acceptance suite without the performance suite. Use a focused named Playwright test instead when only one entity changed and the relevant test is already known.
 
-Run a full performance checkpoint with `pnpm verify:perf` when the first working version of the 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 the 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 apply. Record the deferred check and reason in the 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 path. Record any skipped full performance run and reason in the worklog.
 
 For final delivery, run:
 
@@ -208,6 +210,6 @@ pnpm verify:final
 pnpm dev
 ```
 
-Browser verification must use the real Toolcraft shell plus renderer output. `pnpm verify:final` runs the full static, build, browser, and browser performance gate. `pnpm dev` is intentionally separate because it keeps the local server running.
+Browser verification must use the real Toolcraft shell plus renderer output. `pnpm verify:final` runs the full static, build, and browser functional gate. `pnpm verify:perf` is intentionally separate and only runs for the two full-performance triggers. `pnpm dev` is intentionally separate because it keeps the local server running.
 
 Do not stop existing local servers to free `3002`. `pnpm dev`, `pnpm preview`, and browser verification prefer `3002`, then automatically use the next free port when it is occupied.

package/templates/starter/docs/toolcraft/component-rules.md

@@ -22,6 +22,7 @@ Common exact-owner choices:
 - Use `imagePicker` for choosing one visual option from a set.
 - Use `palette` only for constrained design-token color choices with both family and shade: brand palette, Tailwind-like token color, style-guide color scale, semantic palette family, or theme accent token.
 - Use `actions` for local section commands that affect only the nearby entity, such as randomize palette, normalize weights, sort glyphs, clear selection, duplicate item, or reset current stop.
+- Use `collectionActions` for repeatable product entities whose actual item list can grow or shrink, such as colors, glyphs, symbols, points, rules, variants, or object entries. Use it instead of a count slider when the user edits the actual set. The item list must be runtime state that changes preview/export, not panel-only row chrome. The collection control shows the collection `label` on the left and remove/add icon buttons on the right. Homogeneous repeated items do not show visible per-item labels like `Color 1`, `Color 2`, `Item 1`, or `Item 2` when the collection label already names the group. Item controls should use built-ins such as `color`, `colorOpacity`, `text`, `select`, `segmented`, `slider`, `switch`, `checkbox`, or `rangeInput` before any custom renderer.
 - Use `panelActions` for sticky final product actions such as export, copy, generate, apply, or download.
 
 Small action buttons inside custom controls are for item-level actions such as remove, reorder, add stop, or delete stop. Use schema `actions` for section-level local commands. Keep final product actions in `panelActions`, keep timeline transport in the top timeline, and keep global reset in the controls panel header.
@@ -35,6 +36,7 @@ For local reset-like `actions`, use product-specific values such as `reset-curre
 - If a section contains exactly one control, whether simple or compound, render only the parent section dividers.
 - Do not add full-width borders inside a compound control, and do not put dividers only around an internal subsection such as Gradient Stops.
 - Small compound fields such as `colorOpacity` and `rangeInput` stay inline fields without section dividers.
+- `collectionActions` is a compound control when it shares a section with generated item controls, so it follows the same content-width divider rules. Place it at the start of the controlled section. Generated item controls still follow normal density rules: plain colors use equal 50% columns when they fit, while color+opacity items stay stacked.
 
 ## Sliders
 
@@ -50,6 +52,10 @@ Visual discrete sliders must declare `step`; the runtime derives one marker per
 
 Schema sliders always render stacked at full width. Do not put `slider` or `rangeSlider` controls in two-column inline rows. The only built-in exception is `fontPicker`, whose letter-spacing and line-height footer sliders stay paired inside that component.
 
+Use slider `unit` only for measurement or scale suffixes: `%`, `px`, `°`, `x`, `s`, `ms`, `fps`, `rows`, `cols`, or a similarly useful domain unit. Do not use `unit` to repeat the entity already named by the section or label. Avoid `Letters` + `letters`, `Shape Density / Count` + `shapes`, `Words` + `words`, `Symbols` + `symbols`, `Items` + `items`, `Particles` + `particles`, and `Layers` + `layers`. If the numeric value needs an entity noun to make sense, rename the label or section instead of appending the noun to the value. Compact units render tight (`70%`, `24px`, `1.2x`, `8s`); word or acronym units render with a space (`5 cols`, `17 fps`) only when they are truly needed.
+
+Slider value labels are editable only when they contain a numeric value. Textual state labels such as `Normal` are display-only and must not expose hover or click editing affordances.
+
 Range sliders are always full-width two-thumb controls. Do not put a `rangeSlider` in an inline row. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the control does not collapse into a single-value slider.
 
 Range slider value editing accepts common range separators such as `20/80`, `20-80`, `20 - 80`, `20 80`, and en-dash ranges. Use the built-in parser instead of adding custom label parsing.
@@ -106,6 +112,8 @@ Section expand/collapse uses the standard runtime height/opacity animation. Do n
 
 Ordinary section collapsed/expanded state persists as a per-app runtime UI preference. It is not undo/redo state, not settings import/export state, and `Reset controls` must not clear it. Runtime technical `Setup` / settings sections and sticky footer `Export` sections are not collapsible.
 
+Ordinary section headers expose the runtime section reset action before the collapse button. It dispatches `controls.resetTargets` and restores only that section's control targets to their schema `defaultValue`.
+
 Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical `Setup` / settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.
 
 ## Colors
@@ -134,6 +142,8 @@ Use `fileDrop` for source material uploads in the controls panel. Do not place u
 
 In single-layer apps, the runtime shows uploaded image preview and clear button in the file control. Clearing removes source material from the renderer and canvas.
 
+Use `multiple: true` when the app needs several uploaded images as one source set. The runtime appends media, switches to a four-column thumbnail grid when more than one image is present, puts the add-more tile last, and keeps per-image removal inside the file control.
+
 In multi-layer apps, deletion and visibility belong to the Layers panel; `fileDrop` stays an upload target.
 
 ## Image Picker
@@ -211,6 +221,8 @@ Short labels must still be semantically sufficient with nearby context. `Animati
 
 Visible control labels can get a runtime-owned filled Phosphor question tooltip icon. Put a concise product-specific explanation in `description` only when it adds meaning beyond the label. Do not write recaps like `Adjusts Opacity`, and do not build custom help icons beside built-in labels.
 
+Do not add `description` to obvious color clusters. If a section title already names the palette/color context, sequential labels such as `Color 1`, `Color 2`, or simple palette controls such as `Spread` do not need help icons. Keep the whole obvious group clean unless the tooltip explains a non-obvious product behavior.
+
 For compound controls such as `fontPicker`, `description` must not enumerate owned fields like font, weight, size, case, color, opacity, letter spacing, or line height. The component already labels those fields.
 
 If a source label is unavoidably long, keep the visible label concise and rely on native `title` for the full text.
@@ -267,10 +279,14 @@ Use schema `settingsTransfer` for settings import/export. Do not add Import Sett
 
 Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. If the threshold is reached, use `settingsTransfer: "auto"` / `true` or document a product-specific opt-out through `runtime.settingsTransfer` acceptance evidence.
 
-When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order. Do not split these into separate app-authored sections, rename the controls, or rebuild the block by hand.
+When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and optional `Resolution scale` in that order. Do not split these into separate app-authored sections, rename the controls, or rebuild the block by hand.
 
 If only `Export Settings` and `Import Settings` appear in that section, the schema is not using `editable-output` canvas sizing or already owns `canvas.size.width` / `canvas.size.height` controls. For product-output apps, prefer fixing the canvas sizing decision over adding hand-built size fields.
 
+Manual `Canvas width` or `Canvas height` edits are exact output-size edits. They keep the other dimension unchanged, switch `Aspect ratio` to `Custom`, and update the custom ratio inputs to the reduced current ratio. Do not recreate the old behavior where typing one size field stays locked to the previous aspect preset.
+
+Enable `canvas.renderScale: true` for non-vector raster previews such as Canvas 2D, WebGL, or WebGPU output. Runtime adds a `Resolution scale` slider after canvas sizing; it defaults to `2x` and lets users trade preview quality/performance without changing output size. Adding or enabling this slider requires targeted browser evidence that the canvas stays responsive while dragging sliders or other high-frequency controls at the selected scale. Full `pnpm verify:perf` is required only for the first working app version or explicit performance complaints. Performance fixes must preserve the selected scale and keep canvas preview responsive. Diagnose the actual bottleneck before lowering quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp `canvas.renderScale` below the user's chosen value. Do not enable it for DOM/SVG/vector-native previews.
+
 Reset belongs to the controls panel header reset button. Do not add a footer action with `label`, `value`, or `command` containing reset; acceptance treats that as a duplicate Reset.
 
 Still-output product apps include one primary `Export PNG` action.

package/templates/starter/docs/toolcraft/custom-controls.md

@@ -2,11 +2,11 @@
 
 Use a custom control only when no built-in Toolcraft control represents the product interaction.
 
-Built-ins come first: `slider`, `rangeSlider`, `select`, `segmented`, `switch`, `checkbox`, `color`, `colorOpacity`, `vector`, `gradient`, `curves`, `fontPicker`, `imagePicker`, `fileDrop`, `text`, `code`, `rangeInput`, `palette`, `actions`, and `panelActions`.
+Built-ins come first: `slider`, `rangeSlider`, `select`, `segmented`, `switch`, `checkbox`, `color`, `colorOpacity`, `vector`, `gradient`, `curves`, `fontPicker`, `imagePicker`, `fileDrop`, `text`, `code`, `rangeInput`, `palette`, `actions`, `collectionActions`, and `panelActions`.
 
 Register custom renderers through `ToolcraftApp controlRenderers`.
 
-Do not use `controlRenderers` to recreate a built-in control. If the product needs a slider, select, segmented mode picker, color input, gradient editor, font picker, upload, textarea, local action group, or footer action, declare the matching schema control instead of rendering the component manually.
+Do not use `controlRenderers` to recreate a built-in control. If the product needs a slider, select, segmented mode picker, color input, gradient editor, font picker, upload, textarea, local action group, repeatable item add/remove, or footer action, declare the matching schema control instead of rendering the component manually.
 
 Do not edit `ControlsPanel`, copied `src/toolcraft`, or Toolcraft internals inside a generated app.
 

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

@@ -55,6 +55,8 @@ Ordinary controls still need lightweight responsiveness checks. They should not
 - panel scroll affecting canvas zoom;
 - timeline or layer interactions destabilizing the viewport.
 
+When `canvas.renderScale` / `Resolution scale` is enabled, responsiveness coverage must include slider or other high-frequency control drags at the selected scale. If the canvas lags, diagnose the source before changing quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, stale async renders, or animation scheduling.
+
 ## Renderer Performance
 
 Custom renderers should:
@@ -99,14 +101,13 @@ Animation checks should sample enough frames to catch jank. Interaction budgets
 
 Use `app-performance.ts` as the single budget and fixture source. Browser performance tests must call `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` for workload values and `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)` for budgets.
 
-Run `pnpm verify:perf` for Tier 3 performance-sensitive edits and inside `pnpm verify:final` before delivery. It runs `e2e/app-performance.spec.ts` and every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
+Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. `pnpm verify:perf` is the full performance suite; it runs `e2e/app-performance.spec.ts` and every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
 
-Run a full performance checkpoint with `pnpm verify:perf` when:
+Run a full performance checkpoint with `pnpm verify:perf` only when:
 
 - the first working version of the app exists;
-- renderer, canvas, animation, export, timeline, or layers change;
-- a bug that previously broke functionality is fixed;
-- a performance optimization lands;
-- the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+- the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
+
+Performance fixes must preserve selected output and preview quality. Do not pass budgets by lowering image quality, selected `canvas.renderScale`, export resolution, source media fidelity, or canvas backing pixels unless the user explicitly chooses that lower-quality value through a visible control. Prefer coalescing slider updates, caching expensive inputs, moving work off the React render path, reusing GPU resources, or changing renderer strategy over reducing visual fidelity.
 
-Do not use the full performance suite as the default loop for Tier 0-2 edits. Those edits still need the targeted checks named by the verification tier, but they should not pay for renderer and viewport stress tests unless a checkpoint trigger applies. If a fast feature loop defers full performance, record the deferred check and reason in the worklog.
+Do not use the full performance suite as the default loop for feature work after the first working version. Those edits still need the targeted checks named by the verification tier, but they should not pay for every renderer and viewport stress test unless one of the two full-performance triggers applies. If a feature loop skips full performance, record the reason in the worklog.

package/templates/starter/docs/toolcraft/renderer-technique.md

@@ -2,7 +2,7 @@
 
 Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
 
-The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery.
+The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery. Do not make a renderer look fast by silently reducing the selected preview scale, backing pixels, source media quality, or export fidelity.
 
 ## Strategy Guide
 

package/templates/starter/docs/toolcraft/schema-reference.md

@@ -9,7 +9,7 @@ Edit `src/app/app-schema.ts` as the public product surface.
 - Use `settingsTransfer: "auto"` for complex apps that should let users import/export control settings.
 - Bind every control to a schema `target`.
 - Use `defaultValue` for reset behavior.
-- Use `description` for product-specific help beside a visible label. Keep `label` short. Omit `description` instead of writing label recaps like `Adjusts Opacity`; compound controls such as `fontPicker` must not use `description` to list their own fields.
+- Use `description` for product-specific help beside a visible label. Keep `label` short. Omit `description` instead of writing label recaps like `Adjusts Opacity`; also omit it for obvious color clusters such as `Color 1` / `Color 2` inside a color section. Compound controls such as `fontPicker` must not use `description` to list their own fields.
 - Use `disabled: true` only when the control is intentionally unavailable; the runtime renders the disabled visual and interaction state.
 - Use `visibleWhen` when a control or section exists only for a specific template, type, mode, variant, or count. Hidden values are preserved. A section with no visible controls is hidden automatically.
 - Use `disabledWhen` when a control belongs to the current entity but is temporarily unavailable in the selected state. The value is preserved while disabled.
@@ -134,10 +134,14 @@ Choose sizing from product context:
 
 For product output, export, copy, download, shader rendering, procedural rendering, or no single intrinsic source image, use `editable-output` unless the product explicitly needs `fixed-output`.
 
-A prompt-provided base/default size is only the initial `canvas.size`. It must not remove the runtime Aspect ratio, Canvas width, and Canvas height controls. Aspect presets use canonical output sizes (`16:9` is `1920x1080`; the other presets are derived around a 1080px short edge or matching portrait long edge). Use `fixed-output` only when the reference or product explicitly locks dimensions, and add runtime acceptance with `canvasSizingCoverage: "fixed-output-size"`.
+A prompt-provided base/default size is only the initial `canvas.size`. It must not remove the runtime Aspect ratio, Canvas width, and Canvas height controls. Aspect presets use canonical output sizes (`16:9` is `1920x1080`; the other presets are derived around a 1080px short edge or matching portrait long edge). When no explicit product size is provided, runtime defaults to `16:9` / `1920x1080`; choose another preset only when the product meaning calls for it. Use `fixed-output` only when the reference or product explicitly locks dimensions, and add runtime acceptance with `canvasSizingCoverage: "fixed-output-size"`.
 
 Resolved `canvas.size` exists for every canvas app, but visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are mandatory only for `editable-output` sizing. They do not depend on `settingsTransfer`: when settings transfer is off, the runtime prepends a technical `Setup` canvas size section without a visible heading; when settings transfer is on, the controls merge into the first technical `Setup` runtime settings section without a visible heading. Do not hand-build a duplicate size selector.
 
+When the user manually edits `Canvas width` or `Canvas height`, the runtime treats that as an exact custom output size. It keeps the typed dimension, keeps the other dimension unchanged, switches `Aspect ratio` to `Custom`, and shows the reduced current ratio in the custom ratio inputs. Only selecting an aspect preset may resize both dimensions from a canonical preset.
+
+For non-vector raster, Canvas 2D, WebGL, or WebGPU previews, set `canvas.renderScale: true`. Runtime appends `Resolution scale` after canvas sizing in the first technical `Setup` section. The slider ranges from `1x` to `2x`, defaults to `2x`, and changes the renderer backing pixels without changing the visible CSS size or product output dimensions. Adding or enabling this slider requires targeted browser evidence that the canvas stays responsive while dragging sliders or other high-frequency controls at the selected scale. Full `pnpm verify:perf` is required only for the first working app version or explicit performance complaints. Performance fixes must preserve the selected scale. Diagnose whether lag comes from renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, stale async renders, or animation scheduling before reducing quality. Do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp `canvas.renderScale` below the user's chosen value. Do not enable it for DOM/SVG/vector-native previews; use native vector rendering for those.
+
 ## Panels
 
 - Use `panels: {}` for the neutral starter or for products that have no user-facing panels yet.
@@ -157,11 +161,12 @@ Use built-ins before custom controls. Unknown `type` values render nothing unles
 | `anchorGrid` | Anchor picker | `defaultValue`, `target` |
 | `channelMixer` | RGB-only channel matrix mixer with R/G/B tabs and Red/Green/Blue source sliders | `defaultValue`, `target`, `label` |
 | `checkbox` | Checkbox field | `defaultValue`, `target`, `label` |
+| `collectionActions` | Add/remove buttons for repeatable product entities and their runtime-backed item controls | `defaultValue: []`, `itemControl`, `itemDefaultValue`, `itemLabel`, `minItems`, `recommendedMaxItems`, `hardMaxItems`, `target` |
 | `code` | Multiline textarea | `defaultValue`, `target`, `label` |
 | `color` | Hex color picker | `defaultValue: { hex }`, `target`, `label` |
 | `colorOpacity` | Hex color picker plus opacity percent input | `defaultValue: { hex, opacity }`, `target`, `label` |
 | `curves` | RGB or single curve editor | `defaultValue`, `target`, `variant: "single"`, `interpolation: "smooth" \| "monotone"` |
-| `fileDrop` | Upload/drop input | `accept`, `target` |
+| `fileDrop` | Upload/drop input | `accept`, `multiple`, `target` |
 | `fontPicker` | Font preview select with popup, category search, weight, size, text case, text color/opacity, letter spacing, and line height; product text must consume `fontId`, `fontWeight`, `fontSize`, `letterSpacing`, `lineHeight`, `textCase`, `color`, and `opacity` | `defaultValue: { fontId, fontWeight, fontSize, letterSpacing, lineHeight, textCase, color, opacity }`, `target` |
 | `gradient` | Gradient editor | `defaultValue: { angle, gradientType, stops }`, `target` |
 | `imagePicker` | Image choice grid | `items`, `defaultValue`, `target` |
@@ -178,6 +183,10 @@ Use built-ins before custom controls. Unknown `type` values render nothing unles
 
 `text` defaults to `commitMode: "content"` and applies while typing for real content such as prompts, names, titles, tokens, and short text. Use `commitMode: "setting"` for text inputs that edit settings such as font size, numeric-like style values, dimensions, ids, or configuration fields; setting text commits on blur or Enter. Canvas width and Canvas height always commit on blur or Enter. `code` / `CodeTextarea` is a content editor, applies while typing, and is capped at 12 visible lines. Long content scrolls inside the textarea instead of making the controls panel taller.
 
+For `slider` and `rangeSlider`, `unit` is a measurement or scale suffix, not the entity being counted. Use units such as `%`, `px`, `°`, `x`, `s`, `ms`, `fps`, `rows`, or `cols` only when they clarify the number. Do not add repeated nouns such as `letters`, `shapes`, `words`, `symbols`, `items`, `particles`, or `layers` when the label or section already names that entity. If the value needs a noun, rename the label or section. Word or acronym units, when truly needed, render with a space (`5 cols`, `17 fps`); compact symbol/CSS units stay tight (`70%`, `24px`).
+
+Use `collectionActions` when the product owns a growable/shrinkable item list. `minItems` protects the smallest valid output, `recommendedMaxItems` is only a design recommendation, and `hardMaxItems` is valid only for a real product or technical limit. Adding/removing items must update the runtime array and the renderer/export must consume that same array. Do not pair a count slider with hidden fixed item controls when the user needs to add or remove actual entities. The collection label is on the left and remove/add buttons stay on the right. Homogeneous repeated items do not show visible per-item labels when the collection label already names the group. `itemControl.type` supports normal item built-ins such as `color`, `colorOpacity`, `text`, `select`, `segmented`, `slider`, `switch`, `checkbox`, and `rangeInput`; item controls still follow normal density rules, so plain colors use equal 50% columns when they fit.
+
 ## Control Selection Inventory
 
 Before writing schema controls, map product needs to built-ins by value model, not visual similarity.
@@ -229,6 +238,8 @@ Section expand/collapse uses the standard runtime height/opacity animation. Do n
 
 Ordinary section collapsed/expanded state persists as a per-app runtime UI preference. It is not undo/redo state, not settings import/export state, and `Reset controls` must not clear it. Runtime technical `Setup` / settings sections and sticky footer `Export` sections are not collapsible.
 
+Ordinary section headers expose the runtime section reset action before the collapse button. It dispatches `controls.resetTargets` and restores only that section's control targets to their schema `defaultValue`.
+
 Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical `Setup` / settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.
 
 Large built-in compound controls inside mixed sections render content-width internal dividers with 18px between each rendered divider and the control content. If a compound control is the first item in that section, render only its bottom internal divider and remove the top internal padding. If a section contains exactly one control, whether simple or compound, only the parent section dividers render. Single `curves` are not compound for dividers; RGB `curves` are compound.
@@ -296,7 +307,7 @@ When enabled, the runtime inserts a technical `Setup` settings-transfer section
 
 After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. If the threshold is reached, use `"auto"` / `true` or add an explicit `runtime.settingsTransfer` opt-out acceptance row with product evidence.
 
-When settings transfer is enabled and the canvas uses `editable-output` sizing, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order. Do not split these into separate sections or recreate them manually.
+When settings transfer is enabled and the canvas uses `editable-output` sizing, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and optional `Resolution scale` in that order. Do not split these into separate sections or recreate them manually.
 
 A settings-transfer section with only `Export Settings` and `Import Settings` means the canvas is not `editable-output` or the app already declares its own `canvas.size.width` / `canvas.size.height` controls. For product-output apps, treat that as a schema decision to review.
 

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

@@ -73,15 +73,12 @@ Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
 
 - Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
 - Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
-- Tier 3: `pnpm verify:quick`, targeted browser acceptance, and relevant `pnpm verify:perf` scenarios.
-- Tier 4: `pnpm verify:final`, then start `pnpm dev` for the local URL.
+- Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths.
+- Tier 4: `pnpm verify:final`; add `pnpm verify:perf` only for the first working app version or explicit performance complaints, then start `pnpm dev` for the local URL.
 
-Run a full performance checkpoint with `pnpm verify:perf` when:
+Run a full performance checkpoint with `pnpm verify:perf` only when:
 
 - the first working version of the app exists;
-- renderer, canvas, animation, export, timeline, or layers change;
-- a bug that previously broke functionality is fixed;
-- a performance optimization lands;
-- the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+- 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 these checkpoint triggers apply. Record the deferred check and reason in the worklog.
+Fast 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 path. Record any skipped full performance run and reason in the worklog.

package/templates/starter/gitignore

@@ -0,0 +1,36 @@
+# Dependencies
+node_modules
+
+# Build output
+dist
+dist-ssr
+.vite
+.turbo
+.output
+.next
+*.tsbuildinfo
+
+# Test output
+coverage
+test-results
+playwright-report
+
+# Local environment
+.env
+.env.*
+!.env.example
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+
+# OS and editor files
+.DS_Store
+Thumbs.db
+.idea
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json

package/templates/starter/package.json

@@ -16,7 +16,7 @@
     "verify:quick": "pnpm ai:check && pnpm test",
     "verify:ui": "pnpm test:browser",
     "verify:perf": "pnpm test:browser:perf",
-    "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser && pnpm test:browser:perf"
+    "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser"
   },
   "dependencies": {
     "@base-ui/react": "^1.4.1",

package/templates/starter/src/app/starter-acceptance.test.ts

@@ -5997,6 +5997,61 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
+  it("rejects redundant descriptions in obvious color sections", () => {
+    const schemaWithObviousColorHelp = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                color1: {
+                  defaultValue: { hex: "#DFFF1A" },
+                  description: "Sets the first bead color.",
+                  label: "Color 1",
+                  target: "beads.color1",
+                  type: "color",
+                },
+                color2: {
+                  defaultValue: { hex: "#8CFF3A" },
+                  description: "Sets the second bead color.",
+                  label: "Color 2",
+                  target: "beads.color2",
+                  type: "color",
+                },
+                colorSpread: {
+                  defaultValue: 34,
+                  description:
+                    "Controls how often beads use colors 2-5 instead of Color 1.",
+                  label: "Spread",
+                  max: 100,
+                  min: 0,
+                  target: "beads.colorSpread",
+                  type: "slider",
+                  unit: "%",
+                },
+              },
+              title: "Bead Colors",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(validateToolcraftAcceptanceCoverage(schemaWithObviousColorHelp, [
+      makeControlAcceptance("beads.color1", "color"),
+      makeControlAcceptance("beads.color2", "color"),
+      makeControlAcceptance("beads.colorSpread", "slider"),
+    ])).toEqual(
+      expect.arrayContaining([
+        "Bead Colors / color1 description adds a help icon to an obvious color-section control. Omit control.description when the section title and visible label already explain the setting.",
+        "Bead Colors / color2 description adds a help icon to an obvious color-section control. Omit control.description when the section title and visible label already explain the setting.",
+        "Bead Colors / colorSpread description adds a help icon to an obvious color-section control. Omit control.description when the section title and visible label already explain the setting.",
+      ]),
+    );
+  });
+
   it("requires mode selectors to appear before dependent controls", () => {
     const schemaWithLateModeSelector = {
       ...starterSchema,

package/templates/starter/src/app/starter-acceptance.ts

@@ -1561,14 +1561,33 @@ function getToolcraftControlDescriptionError({
   control,
   controlId,
   sectionLabel,
+  sectionTitle,
 }: {
   control: ToolcraftControlSchema;
   controlId: string;
   sectionLabel: string;
+  sectionTitle: string | undefined;
 }): string | undefined {
   const description = control.description?.trim();
 
-  if (!description || control.type !== "fontPicker") {
+  if (!description) {
+    return undefined;
+  }
+
+  const label = getControlLabelText(control).trim();
+
+  if (
+    isToolcraftObviousColorSectionControlDescription({
+      control,
+      description,
+      label,
+      sectionTitle,
+    })
+  ) {
+    return `${sectionLabel} / ${controlId} description adds a help icon to an obvious color-section control. Omit control.description when the section title and visible label already explain the setting.`;
+  }
+
+  if (control.type !== "fontPicker") {
     return undefined;
   }
 
@@ -1583,6 +1602,52 @@ function getToolcraftControlDescriptionError({
   return `${sectionLabel} / ${controlId} description repeats FontPicker-owned fields (${repeatedParts.join(", ")}). FontPicker help must explain only non-obvious product behavior; use section titles and visible field labels for font family, weight, size, case, color, opacity, letter spacing, and line height, or omit description.`;
 }
 
+function isToolcraftColorSectionTitle(sectionTitle: string | undefined): boolean {
+  return /\b(colou?rs?|palette|palettes)\b/i.test(sectionTitle ?? "");
+}
+
+function isToolcraftSequentialColorLabel(label: string): boolean {
+  return /^colou?r\s+\d+$/i.test(label.trim());
+}
+
+function isToolcraftSimplePaletteDistributionLabel(label: string): boolean {
+  return /^(spread|mix|distribution)$/i.test(label.trim());
+}
+
+function isToolcraftGenericControlHelpDescription(description: string): boolean {
+  return /^(adjusts?|changes?|chooses?|controls?|defines?|selects?|sets?|updates?)\b/i.test(
+    description.trim(),
+  );
+}
+
+function isToolcraftObviousColorSectionControlDescription({
+  control,
+  description,
+  label,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  description: string;
+  label: string;
+  sectionTitle: string | undefined;
+}): boolean {
+  if (!isToolcraftColorSectionTitle(sectionTitle)) {
+    return false;
+  }
+
+  if (
+    (control.type === "color" || control.type === "colorOpacity") &&
+    isToolcraftSequentialColorLabel(label)
+  ) {
+    return true;
+  }
+
+  return (
+    isToolcraftSimplePaletteDistributionLabel(label) &&
+    isToolcraftGenericControlHelpDescription(description)
+  );
+}
+
 function getToolcraftControlSectionGroupingErrors(
   schema: ResolvedToolcraftAppSchema,
 ): string[] {
@@ -1691,6 +1756,7 @@ function getToolcraftControlSectionGroupingErrors(
         control,
         controlId,
         sectionLabel,
+        sectionTitle,
       });
 
       if (descriptionError) {

package/templates/starter/src/app/starter-performance.test.ts

@@ -299,7 +299,7 @@ describe("Toolcraft template app performance coverage", () => {
     expect(packageJson.scripts?.["verify:ui"]).toBe("pnpm test:browser");
     expect(packageJson.scripts?.["verify:perf"]).toBe("pnpm test:browser:perf");
     expect(packageJson.scripts?.["verify:final"]).toBe(
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser && pnpm test:browser:perf",
+      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
     );
   });
 

package/templates/ui/components/controls/collection-actions/collection-actions-control.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { MinusIcon, PlusIcon } from "@phosphor-icons/react";
+import type * as React from "react";
+
+import { ControlFieldLabel } from "../../control-layout";
+import { Button, Field } from "../../primitives";
+
+export type CollectionActionsControlProps = {
+  addLabel?: string;
+  canAdd?: boolean;
+  canRemove?: boolean;
+  name: string;
+  onAdd?: () => void;
+  onRemove?: () => void;
+  removeLabel?: string;
+};
+
+export function CollectionActionsControl({
+  addLabel = "Add item",
+  canAdd = true,
+  canRemove = true,
+  name,
+  onAdd,
+  onRemove,
+  removeLabel = "Remove item",
+}: CollectionActionsControlProps): React.JSX.Element {
+  return (
+    <Field
+      aria-label={name}
+      className="min-w-0 items-center justify-between gap-2"
+      data-slot="collection-actions-control-header"
+      orientation="horizontal"
+    >
+      <ControlFieldLabel className="flex-1">{name}</ControlFieldLabel>
+      <div className="inline-flex shrink-0 items-center gap-1">
+        <Button
+          aria-label={removeLabel}
+          disabled={!canRemove}
+          onClick={onRemove}
+          size="icon-sm"
+          type="button"
+          variant="outline"
+        >
+          <MinusIcon />
+        </Button>
+        <Button
+          aria-label={addLabel}
+          disabled={!canAdd}
+          onClick={onAdd}
+          size="icon-sm"
+          type="button"
+          variant="outline"
+        >
+          <PlusIcon />
+        </Button>
+      </div>
+    </Field>
+  );
+}

package/templates/ui/components/controls/collection-actions/index.ts

@@ -0,0 +1,4 @@
+"use client";
+
+export { CollectionActionsControl } from "./collection-actions-control";
+export type { CollectionActionsControlProps } from "./collection-actions-control";