@pixel-point/toolcraft 0.0.4 → 0.0.6

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.
 
@@ -197,7 +199,7 @@ 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` when the first working version of the 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, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
 Fast feature loops may defer full performance only when none of the checkpoint triggers apply. Record the deferred check and reason in the worklog.
 

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

@@ -50,6 +50,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.
@@ -134,6 +138,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 +217,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 +275,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 a full `pnpm verify:perf` checkpoint. Performance fixes must preserve the selected scale and keep canvas preview responsive while dragging sliders or other high-frequency controls. 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/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:
@@ -105,8 +107,11 @@ Run a full performance checkpoint with `pnpm verify:perf` when:
 
 - the first working version of the app exists;
 - renderer, canvas, animation, export, timeline, or layers change;
+- `canvas.renderScale` or the `Resolution scale` retina slider is added/enabled;
 - 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.
 
+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.

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 a full `pnpm verify:perf` checkpoint. Performance fixes must preserve the selected scale and keep the canvas responsive while dragging sliders or other high-frequency controls at that 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.
@@ -161,7 +165,7 @@ Use built-ins before custom controls. Unknown `type` values render nothing unles
 | `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 +182,8 @@ 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`).
+
 ## Control Selection Inventory
 
 Before writing schema controls, map product needs to built-ins by value model, not visual similarity.
@@ -296,7 +302,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/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/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/ui/components/controls/file-drop/file-drop-control.tsx

@@ -1,13 +1,14 @@
 "use client";
 
 import * as React from "react";
-import { CloudArrowUpIcon, XIcon } from "@phosphor-icons/react";
+import { CloudArrowUpIcon, PlusIcon, XIcon } from "@phosphor-icons/react";
 
 import { cn } from "../../../lib/utils";
 import { Button, Field } from "../../primitives";
 
 export type FileDropPreview = {
   alt?: string;
+  id?: string;
   size?: {
     height: number;
     width: number;
@@ -17,9 +18,13 @@ export type FileDropPreview = {
 
 export type FileDropControlProps = {
   accept: string;
+  multiple?: boolean;
   onClear?: () => void;
   onFileSelect?: (file: File) => void;
+  onFilesSelect?: (files: File[]) => void;
+  onPreviewRemove?: (preview: FileDropPreview, index: number) => void;
   preview?: FileDropPreview;
+  previews?: readonly FileDropPreview[];
 };
 
 function isDragLeavingCurrentTarget(event: React.DragEvent<HTMLElement>): boolean {
@@ -73,20 +78,38 @@ function getPreviewImageStyle(size: FileDropPreview["size"]): React.CSSPropertie
 
 export function FileDropControl({
   accept,
+  multiple = false,
   onClear,
   onFileSelect,
+  onFilesSelect,
+  onPreviewRemove,
   preview,
+  previews,
 }: FileDropControlProps): React.JSX.Element {
   const inputRef = React.useRef<HTMLInputElement>(null);
   const [dragOver, setDragOver] = React.useState(false);
-  const hasPreview = Boolean(preview?.src);
+  const previewItems = previews ?? (preview ? [preview] : []);
+  const hasPreview = previewItems.some((item) => Boolean(item.src));
+  const shouldRenderPreviewGrid = multiple && previewItems.length > 1;
 
-  function handleFile(file: File | undefined): void {
-    if (!file) {
+  function handleFiles(fileList: FileList | readonly File[] | undefined): void {
+    const files = Array.from(fileList ?? []);
+
+    if (files.length === 0) {
       return;
     }
 
-    onFileSelect?.(file);
+    if (multiple) {
+      if (onFilesSelect) {
+        onFilesSelect(files);
+        return;
+      }
+
+      files.forEach((file) => onFileSelect?.(file));
+      return;
+    }
+
+    onFileSelect?.(files[0]);
   }
 
   function openFileDialog(): void {
@@ -109,15 +132,24 @@ export function FileDropControl({
         aria-hidden="true"
         className="hidden"
         onChange={(event) => {
-          handleFile(event.currentTarget.files?.[0]);
+          handleFiles(event.currentTarget.files ?? undefined);
           event.currentTarget.value = "";
         }}
+        multiple={multiple}
         ref={inputRef}
         tabIndex={-1}
         type="file"
       />
       <div
-        aria-label={hasPreview ? "Replace image file" : "Browse image file"}
+        aria-label={
+          hasPreview
+            ? multiple
+              ? "Drop image files"
+              : "Replace image file"
+            : multiple
+              ? "Browse image files"
+              : "Browse image file"
+        }
         className={cn(
           "group/file-upload relative flex min-h-16 w-full cursor-pointer flex-col items-center justify-center gap-1.5 rounded-lg border border-dashed border-[color:color-mix(in_oklab,var(--border)_18%,transparent)] bg-[color:color-mix(in_oklab,var(--foreground)_3%,transparent)] text-center shadow-none transition-[background-color,border-color,box-shadow] duration-150 ease-out hover:border-[color:color-mix(in_oklab,var(--border)_35%,transparent)] hover:bg-[color:color-mix(in_oklab,var(--foreground)_6%,transparent)] data-[drag-over=true]:border-[color:color-mix(in_oklab,var(--link)_28%,transparent)] data-[drag-over=true]:bg-[color:color-mix(in_oklab,var(--link)_13%,transparent)] data-[drag-over=true]:shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--background)]",
           hasPreview ? "overflow-hidden p-2" : "px-3 py-3",
@@ -140,23 +172,74 @@ export function FileDropControl({
         onDrop={(event) => {
           event.preventDefault();
           setDragOver(false);
-          handleFile(event.dataTransfer?.files?.[0]);
+          handleFiles(event.dataTransfer?.files ?? undefined);
         }}
         onKeyDown={handleDropTargetKeyDown}
         role="button"
         tabIndex={0}
       >
-        {hasPreview ? (
+        {shouldRenderPreviewGrid ? (
+          <div
+            className="grid w-full grid-cols-4 gap-2"
+            data-slot="file-upload-preview-grid"
+          >
+            {previewItems.map((item, index) => (
+              <div
+                className="relative aspect-square min-w-0 overflow-hidden rounded-[calc(var(--radius-lg)-4px)] bg-[color:color-mix(in_oklab,var(--foreground)_6%,transparent)]"
+                data-slot="file-upload-preview-item"
+                key={item.id ?? `${item.src}-${index}`}
+              >
+                <img
+                  alt={item.alt ?? ""}
+                  className="size-full object-cover"
+                  draggable={false}
+                  height={item.size?.height}
+                  src={item.src}
+                  width={item.size?.width}
+                />
+                {onPreviewRemove ? (
+                  <Button
+                    aria-label={`Remove ${item.alt ?? "image"}`}
+                    className="absolute top-1 right-1"
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      onPreviewRemove(item, index);
+                    }}
+                    size="icon-sm"
+                    type="button"
+                    variant="ghost"
+                  >
+                    <XIcon className="drop-shadow-[0_2px_1px_color-mix(in_oklab,var(--background)_80%,transparent)]" />
+                  </Button>
+                ) : null}
+              </div>
+            ))}
+            <button
+              aria-label="Add image files"
+              className="flex aspect-square min-w-0 items-center justify-center rounded-[calc(var(--radius-lg)-4px)] border border-[color:color-mix(in_oklab,var(--border)_5%,transparent)] bg-[color:color-mix(in_oklab,var(--foreground)_4%,transparent)] text-[color:color-mix(in_oklab,var(--foreground)_65%,transparent)] transition-[background-color,border-color,color] duration-150 ease-out hover:border-[color:color-mix(in_oklab,var(--border)_35%,transparent)] hover:bg-[color:color-mix(in_oklab,var(--foreground)_7%,transparent)] hover:text-[color:var(--foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
+              data-slot="file-upload-add-preview"
+              onClick={(event) => {
+                event.stopPropagation();
+                openFileDialog();
+              }}
+              type="button"
+            >
+              <PlusIcon className="size-4" weight="regular" />
+            </button>
+          </div>
+        ) : hasPreview ? (
           <>
-            <img
-              alt={preview?.alt ?? ""}
-              className="block h-auto max-h-[196px] max-w-full rounded-[calc(var(--radius-lg)-4px)] object-contain"
-              draggable={false}
-              height={preview?.size?.height}
-              src={preview?.src}
-              style={getPreviewImageStyle(preview?.size)}
-              width={preview?.size?.width}
-            />
+            {previewItems[0] ? (
+              <img
+                alt={previewItems[0].alt ?? ""}
+                className="block h-auto max-h-[196px] max-w-full rounded-[calc(var(--radius-lg)-4px)] object-contain"
+                draggable={false}
+                height={previewItems[0].size?.height}
+                src={previewItems[0].src}
+                style={getPreviewImageStyle(previewItems[0].size)}
+                width={previewItems[0].size?.width}
+              />
+            ) : null}
             {onClear ? (
               <Button
                 aria-label="Remove image"

package/templates/ui/components/controls/range-slider/range-slider-value.ts

@@ -1,8 +1,11 @@
+import { applySliderValueLabelUnit } from "../slider/slider-value";
+
 export function formatRangeSliderValue(
   value: readonly number[],
   unit?: string,
 ): string {
-  const formatValue = (item: number): string => `${Math.round(item)}${unit ?? ""}`;
+  const formatValue = (item: number): string =>
+    applySliderValueLabelUnit(String(Math.round(item)), unit);
 
   if (value.length >= 2 && value[0] === value[1]) {
     return formatValue(value[0] ?? 0);

package/templates/ui/components/controls/slider/slider-value.ts

@@ -17,19 +17,62 @@ export function formatSliderValue(value: number, step: number): string {
   return String(rounded);
 }
 
+const compactSliderValueUnits = new Set([
+  "%",
+  "°",
+  "px",
+  "em",
+  "rem",
+  "vw",
+  "vh",
+  "vmin",
+  "vmax",
+  "x",
+  "s",
+  "ms",
+]);
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function getSliderValueUnitSeparator(unit: string): "" | " " {
+  const normalizedUnit = unit.trim();
+
+  if (
+    normalizedUnit === "" ||
+    compactSliderValueUnits.has(normalizedUnit) ||
+    /^[^\p{Letter}\p{Number}]+$/u.test(normalizedUnit)
+  ) {
+    return "";
+  }
+
+  return " ";
+}
+
 export function applySliderValueLabelUnit(
   valueLabel: string,
   unit?: string,
 ): string {
-  if (!unit || typeof parseSliderValueLabel(valueLabel) !== "number") {
+  const normalizedUnit = unit?.trim();
+
+  if (
+    !normalizedUnit ||
+    typeof parseSliderValueLabel(valueLabel) !== "number"
+  ) {
     return valueLabel;
   }
 
-  return valueLabel.replaceAll(/-?\d+(?:\.\d+)?/g, (match, offset) => {
-    const textAfterMatch = valueLabel.slice(offset + match.length).trimStart();
+  const separator = getSliderValueUnitSeparator(normalizedUnit);
+  const unitPattern = new RegExp(
+    `(-?\\d+(?:\\.\\d+)?)(?:\\s*${escapeRegExp(normalizedUnit)})?`,
+    "g",
+  );
 
-    return textAfterMatch.startsWith(unit) ? match : `${match}${unit}`;
-  });
+  return valueLabel.replaceAll(
+    unitPattern,
+    (_match, value: string) => `${value}${separator}${normalizedUnit}`,
+  );
 }
 
 export function formatSliderValueWithUnit(

package/templates/ui/components/primitives/editable-slider-value-label.tsx

@@ -40,6 +40,7 @@ export function EditableSliderValueLabel({
   const [editing, setEditing] = useState(false);
   const editorRef = useRef<HTMLSpanElement>(null);
   const valueLabelRef = useRef(valueLabel);
+  const isEditableValueLabel = hasEditableNumericValueLabel(valueLabel);
   const valueTextClassName = getEditableValueTextClassName({ layout, textAlign });
   const widestValueLabel = getWidestValueLabel(valueLabel, maxValueLabel);
 
@@ -61,7 +62,7 @@ export function EditableSliderValueLabel({
     }
   }, [editing]);
 
-  if (disabled || !onCommit) {
+  if (disabled || !onCommit || !isEditableValueLabel) {
     const valueTextToneClassName = disabled
       ? "text-[color:color-mix(in_oklab,var(--foreground)_60%,transparent)] opacity-60"
       : "text-[color:var(--muted-foreground)]";
@@ -323,6 +324,10 @@ function getWidestValueLabel(valueLabel: string, maxValueLabel?: string): string
   return maxValueLabel;
 }
 
+function hasEditableNumericValueLabel(valueLabel: string): boolean {
+  return /-?\d+(?:\.\d+)?/.test(valueLabel);
+}
+
 function selectEditableText(node: HTMLElement): void {
   const selection = window.getSelection();