@pixel-point/toolcraft 0.0.8 → 0.0.9

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

@@ -49,6 +49,8 @@ getToolcraftPerformanceStressValue(appPerformance, "scenario-id")
 
 For workload sliders, use `dragToolcraftSliderToPerformanceStressValue(page, label, appPerformance, "scenario-id")` so the test applies the exact numeric value through the real slider min/max range. Do not divide a stress value by the slider max, type a separate short value, or hardcode a ratio in the Playwright test. If a test uses a toy value while `app-performance.ts` claims a heavy fixture, `pnpm verify:perf` must fail.
 
+Slider and range slider performance scenarios must preserve live product feedback. The browser test should drag the real thumb and verify the canvas/product output changes during drag. If that drag misses budget, keep the live control semantics and optimize the renderer path first: cache expensive inputs, update uniforms or stable buffers, coalesce preview work to `requestAnimationFrame`, cancel stale async renders, move work off React renders, reuse GPU resources, or change renderer strategy. Do not pass performance by making the slider update only after pointer release or Apply.
+
 When a scenario declares `workloadFixture`, apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
 
 For combined worst cases, put every relevant independent baseline value in `workloadFixture.value` for control scenarios, such as `{ sourceMedia: { width: 3840, height: 2160 }, renderScale: 2 }`, and put the tested control value in `stressFixture.value`. For preview, zoom, drag, animation, or export scenarios that stress the entire state instead of one control, use `stressFixture.value`, such as `{ detail: 96, scale: 0.6, renderScale: 2 }`. Testing workload controls one-by-one is not enough when the product exposes combinations that multiply render cost.
@@ -91,11 +93,13 @@ Custom renderers should:
 - initialize contexts, programs, shaders, pipelines, textures, and large buffers once;
 - update uniforms or stable buffers when controls change;
 - cache decoded media;
-- debounce, coalesce, or defer heavy preview work;
+- coalesce high-frequency preview work and split lightweight live feedback from heavier refinement when needed;
 - cancel stale async renders;
 - avoid re-decoding media on every control change;
 - cancel scheduled frames during cleanup.
 
+Coalescing may reduce redundant renders during high-frequency slider drags, but it must not make the slider feel deferred or leave the canvas unchanged until release.
+
 Custom renderers must declare `rendererPipeline` in `src/app/app-performance.ts`. This is the machine-checkable Render Pipeline Inventory:
 
 - every render pass has an `id`, `kind`, `runsOn`, `output`, `quality`, `inputs`, and `invalidatedBy`;
@@ -131,6 +135,8 @@ Use real interactions for:
 - `viewport-zoom-stress` for detail-heavy or animated custom renderers;
 - `viewport-stability`.
 
+For `slider` and `rangeSlider`, the required performance scenario is `control-drag`. A `control-change` scenario can cover selects, inputs, toggles, and other non-drag controls, but it does not prove live canvas feedback or drag smoothness for sliders.
+
 Animated custom renderers also need `animation-viewport-drag`. Animation-only frame sampling and viewport-only stability are not enough: the browser test must sample frames while physically dragging or panning the canvas viewport. If SVG/DOM cannot pass that combined budget, choose a different renderer strategy from evidence instead of loosening the budget.
 
 Detail-heavy or animated custom renderers also need `viewport-zoom-stress`. This test must apply the combined worst-case stress fixture first, then use the real toolbar zoom controls while sampling frame gaps and long tasks. Do not satisfy it by calling `canvas.zoom`, mutating runtime state directly, checking only the final zoom value, or zooming a default/lightweight output.

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

@@ -129,18 +129,18 @@ Use `MediaRecorder.isTypeSupported(...)` or an explicit encoder/transcoder capab
 Choose sizing from product context:
 
 - `intrinsic-media`: a single uploaded or generated source defines `canvas.size`.
-- `editable-output`: exportable output where users should edit width and height.
-- `fixed-output`: product-defined output size that users must not edit.
+- `editable-output`: product/export output where users always see aspect ratio, width, and height.
+- `fixed-output`: non-product/internal output size that users must not edit.
 
-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`.
+For product output, export, copy, download, shader rendering, procedural rendering, reference clones, or no single intrinsic source image, use `editable-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). 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"`.
+A prompt-provided, reference, fixed-format, or 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. Generated product/export apps do not use `fixed-output` to preserve a reference baseline; fixed dimensions stay visible as editable defaults.
 
-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.
+Resolved `canvas.size` exists for every canvas app, but visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are mandatory through `editable-output` sizing for product/export apps. 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.
+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 `1` to `2`, defaults to `2`, 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
 
@@ -157,7 +157,7 @@ Use built-ins before custom controls. Unknown `type` values render nothing unles
 
 | `type` | Renders | Key fields |
 | --- | --- | --- |
-| `actions` | Inline local action buttons for the current section or nearby entity | `actions`, `target`, `label` |
+| `actions` | Local action buttons for the current section or nearby entity, rendered below the label in a two-column grid | `actions`, `target`, `label` |
 | `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` |
@@ -179,14 +179,20 @@ Use built-ins before custom controls. Unknown `type` values render nothing unles
 | `slider` | Single-value slider | `defaultValue`, `min`, `max`, `step`, `unit`, `variant` |
 | `switch` | Binary switch | `defaultValue`, `target`, `label` |
 | `text` | Single-line input | `defaultValue`, `target`, `label`, `commitMode` |
-| `vector` | X/Y vector pad and fields | `defaultValue: { x, y }`, `xLabel`, `yLabel`, `variant` |
+| `vector` | X/Y vector pad and fields | `defaultValue: { x, y }`, `xLabel`, `yLabel`, `variant`, `coordinateMode` |
 
-`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.
+`text` defaults to `commitMode: "content"` and applies while typing for short real content such as button labels, canvas labels, names, titles, captions, tokens, compact prompts, and other one-line 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 for long, multiline, or structured values, applies while typing, and is capped at 12 visible lines. Long content scrolls inside the textarea instead of making the controls panel taller. Do not use `code` for short single-line button/canvas text unless `description` explicitly proves the field is intended for long or structured input.
 
-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`).
+For `slider` and `rangeSlider`, `unit` is a real measurement suffix, not the entity being counted and not a generic multiplier. Use units such as `%`, `px`, `°`, `s`, `ms`, `fps`, `rows`, or `cols` only when they clarify the number. Do not use `unit: "x"`; scale, multiplier, intensity, opacity, strength, depth, and shader amount values display plain numbers unless a real measurement unit applies. 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`).
+
+`slider` and `rangeSlider` are live controls. Dragging must update runtime state and product output while the drag is in progress, not only on pointer release, blur, Apply, or a final commit. Treat a non-live slider as a broken product mapping unless an extreme measured performance ceiling is documented; even then, keep immediate lightweight canvas feedback and refine the heavy output after coalescing/caching.
+
+For `vector`, the default/spatial variant uses `coordinateMode: "screen"` by default: dragging left/up lowers `x` and `y`, so canvas objects move left/up without renderer-side Y inversion. Use `coordinateMode: "cartesian"` only for intentional mathematical Y-up coordinates. Color variants keep their color-axis semantics by default.
 
 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`, `rangeInput`, and `fontPicker`; item controls still follow normal density rules, so plain colors use equal 50% columns when they fit. Use `fontPicker` as the item control when each repeated item is a text style or typography entity; do not split its font, weight, size, case, color/opacity, letter spacing, or line height into sibling collection fields.
 
+Segmented controls are full-width compact choices. Do not place `segmented` in inline half-width rows beside Switch, Color, Select, or another control; use `select` when a finite choice must occupy a half-width column.
+
 ## Control Selection Inventory
 
 Before writing schema controls, map product needs to built-ins by value model, not visual similarity.
@@ -221,15 +227,38 @@ If the user asks for product animation and does not explicitly say it is decorat
 
 ## Control Section Inventory
 
-Before editing `panels.controls.sections`, write a short inventory in the spec or plan:
+Before editing `panels.controls.sections`, define and export `starterControlSectionInventory` beside `starterAcceptance` in `src/app/starter-acceptance.ts`. This is the machine-checkable version of the section plan.
 
 - section title;
 - product entity or workflow stage;
 - included schema targets;
 - reason these controls belong together or reason for a real workflow split.
 
+```ts
+export const starterControlSectionInventory = [
+  {
+    entity: "Text block",
+    groupingReason:
+      "These controls edit the text content, typography, and visible text fill together.",
+    targets: ["text.content", "text.font"],
+    title: "Text",
+  },
+  {
+    entity: "Object shape",
+    groupingReason: "Structure controls tune the physical footprint of the object.",
+    splitReason:
+      "Structure and density are separate workflow stages in this editor.",
+    targets: ["object.shape.size"],
+    title: "Shape Structure",
+    workflowStage: "structure",
+  },
+] as const;
+```
+
 Group controls by product meaning, not by component type. Do not create sections named `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, or `Colors`.
 
+The inventory must match the rendered schema: every product control target in every product section appears exactly once, and every inventory target renders in the section named by `title`. Runtime technical `Setup` controls, sticky footer `Export` actions, `settingsTransfer`, and runtime canvas sizing controls do not need inventory entries. If one target entity is split across sections, every split section must declare `workflowStage` and a concrete `splitReason`; otherwise the validator treats the split as accidental section drift.
+
 Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created setup/settings sections use the technical title `Setup` but render without a visible heading; sticky footer action sections use the technical title `Export` but render without a visible heading.
 
 Every visible section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon. Do not hand-build section headers in generated apps.
@@ -242,7 +271,7 @@ Ordinary section headers expose the runtime section reset action before the coll
 
 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.
+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 it is the last item in that section, render only its top internal divider and remove the bottom 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.
 
 Controls for the same product entity stay in the same section. For example, `squares.right.connections`, `squares.right.hoverRadius`, and `squares.right.color` belong in `Square 1 (Right)` with `Color` as the field label. A standalone color section is only valid when the color is the whole product entity, such as `Background`, `Accent`, `Connector`, or `Brand`.
 
@@ -254,7 +283,7 @@ If a target prefix has to be split across sections, the spec must name the workf
 
 Switch and checkbox labels name the setting context only. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead. If the nearest section title already names the context, do not duplicate it as the visible toggle label. Use a short contextual label such as `Include` or, only for icon-only visual toggles, `label: false` with the product meaning in `target` and `description`.
 
-Inline two-column groups are preferred when controls tune one close product meaning and labels/values fit. Short numeric text pairs can be inline. Related short `select` pairs can be inline, especially workflow pairs such as `Format` + `Resolution`, `Codec` + `Profile`, or `Width unit` + `Height unit`. Use stacked one-control rows only as a fit fallback when a label, selected value, or option text would clip, truncate, or lose padding; record that fallback reason in the spec or worklog. A short numeric/text field may also pair with one related plain `color` field when both configure the same entity, such as `Mask size` and `Color` inside `Mask`. `colorOpacity` never renders in inline two-column groups; if either color control has opacity, keep the controls stacked. Color labels are semantic, not automatic: decide once for the whole color group, omit per-item labels such as `Color 1` for palette variation banks like `Accent Shades` or `Bead Colors`, and do not mix labeled and unlabeled items inside that bank. Sibling controls like `Spread` or `Randomness` do not force item labels; keep visible labels only when colors edit distinct roles such as `Fill`, `Stroke`, `Background`, `Connector`, or `Object`. Related plain color banks render two per row, and an odd trailing plain color remains half-width instead of stretching to a full row. Mixed inline rows require visible labels on every field except the required Background row and palette variation color banks whose group/section label already names the bank. Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when both visible labels fit without truncation; the runtime auto-pairs safe adjacent toggles by target entity, and schemas should stack them only when either label is too long. A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and both controls edit the same entity; shorten the toggle label when the section title already supplies context. Toggle plus parameter rows are equal-width two-column rows: each control occupies one half, never intrinsic toggle width plus remaining space. The required Background row uses `Include` plus unlabeled background color. Schema `slider` and `rangeSlider` controls always stay stacked at full width; the only built-in exception is the paired letter-spacing and line-height footer sliders inside `fontPicker`. Do not place sibling controls for case, color, opacity, size, weight, letter spacing, or line height when the same text entity already uses `fontPicker`.
+Inline two-column groups are preferred when controls tune one close product meaning and labels/values fit. Short numeric text pairs can be inline. Related short `select` pairs can be inline, especially workflow pairs such as `Format` + `Resolution`, `Codec` + `Profile`, or `Width unit` + `Height unit`. Use stacked one-control rows only as a fit fallback when a label, selected value, or option text would clip, truncate, or lose padding; record that fallback reason in the spec or worklog. A short numeric/text field may also pair with one related plain `color` field when both configure the same entity, such as `Mask size` and `Color` inside `Mask`. `colorOpacity` never renders in inline two-column groups; if either color control has opacity, keep the controls stacked. Color labels are semantic, not automatic: decide once for the whole color group, omit per-item labels such as `Color 1` for palette variation banks like `Accent Shades` or `Bead Colors`, and do not mix labeled and unlabeled items inside that bank. Sibling controls like `Spread` or `Randomness` do not force item labels; keep visible labels only when colors edit distinct roles such as `Fill`, `Stroke`, `Background`, `Connector`, or `Object`. Related plain color banks render two per row, and an odd trailing plain color remains half-width instead of stretching to a full row. Mixed inline rows usually require visible labels on every field, except toggle-plus-parameter rows, the required Background row, and palette variation color banks whose group/section label already names the bank. All 50/50 inline rows use the same horizontal column gap as paired `select` controls; do not create a wider or narrower gap for toggle-plus-parameter rows. Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when both visible labels fit without truncation; the runtime auto-pairs safe adjacent toggles by target entity, and schemas should stack them only when either label is too long. A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and both controls edit the same entity; the non-toggle parameter uses `label: false`, and if that label is needed, stack the controls instead. Toggle plus parameter rows are equal-width two-column rows: each control occupies one half, never intrinsic toggle width plus remaining space. The required Background row uses `Include` plus unlabeled background color. Schema `slider` and `rangeSlider` controls always stay stacked at full width; the only built-in exception is the paired letter-spacing and line-height footer sliders inside `fontPicker`. Do not place sibling controls for case, color, opacity, size, weight, letter spacing, or line height when the same text entity already uses `fontPicker`.
 
 `rangeSlider` is always a full-width two-thumb control. Do not include it in `layoutGroups`. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the two handles do not collapse into one apparent slider. Manual range labels accept built-in separators such as slash, hyphen, spaces, and dashes.
 
@@ -309,6 +338,6 @@ After adding, removing, or reorganizing controls, sections, timeline, or layers,
 
 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.
+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 error to fix, not as a layout variant.
 
 Do not hand-write `settings-transfer.ts`, hidden file inputs, route handlers, or `panelActions` for settings import/export. Sticky footer `panelActions` remain product delivery only.

package/templates/starter/gitignore

@@ -19,6 +19,7 @@ playwright-report
 .env
 .env.*
 !.env.example
+.toolcraft
 
 # Logs
 logs

package/templates/starter/package.json

@@ -6,8 +6,10 @@
   "scripts": {
     "ai:check": "node scripts/check-ai-skills.mjs",
     "dev": "node scripts/run-vite-on-free-port.mjs dev",
+    "dev:restart": "node scripts/run-vite-on-free-port.mjs dev --toolcraft-restart",
     "build": "tsc -p tsconfig.json --noEmit && vite build",
     "preview": "node scripts/run-vite-on-free-port.mjs preview",
+    "preview:restart": "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
     "docs:check": "node scripts/check-toolcraft-docs.mjs",
     "test": "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
     "test:browser": "playwright install chromium && playwright test",

package/templates/starter/scripts/run-vite-on-free-port.mjs

@@ -2,21 +2,56 @@
 
 import { spawn } from "node:child_process";
 
-import { findAvailablePort, readPreferredPort } from "./toolcraft-port.mjs";
+import {
+  findAvailablePort,
+  isPortAvailableOnLoopback,
+  killListeningProcessesOnPort,
+  readPreferredPort,
+  readSavedToolcraftPort,
+  waitForPortAvailable,
+  writeSavedToolcraftPort,
+} from "./toolcraft-port.mjs";
 
 const viteCommand = process.argv[2] ?? "dev";
-const passthroughArgs = process.argv.slice(3).filter((arg) => arg !== "--");
+const restartArg = "--toolcraft-restart";
+const rawPassthroughArgs = process.argv.slice(3).filter((arg) => arg !== "--");
+const restartSamePort =
+  process.env.TOOLCRAFT_RESTART === "1" || rawPassthroughArgs.includes(restartArg);
+const passthroughArgs = rawPassthroughArgs.filter((arg) => arg !== restartArg);
 const preferredPort = readPreferredPort([
   "TOOLCRAFT_DEV_PORT",
   "TOOLCRAFT_PORT",
   "PORT",
 ]);
-const port = await findAvailablePort(preferredPort);
+const savedPort = restartSamePort ? await readSavedToolcraftPort() : null;
+const port = savedPort ?? (await findAvailablePort(preferredPort));
 
-if (port !== preferredPort) {
+if (savedPort) {
+  console.log(`[toolcraft] Restart mode: reusing port ${savedPort}.`);
+
+  if (!(await isPortAvailableOnLoopback(savedPort))) {
+    console.log(`[toolcraft] Port ${savedPort} is busy; stopping the existing listener first.`);
+    await killListeningProcessesOnPort(savedPort);
+
+    if (!(await waitForPortAvailable(savedPort))) {
+      console.log(`[toolcraft] Port ${savedPort} is still busy; forcing listener shutdown.`);
+      await killListeningProcessesOnPort(savedPort, { signal: "SIGKILL" });
+
+      if (!(await waitForPortAvailable(savedPort, { timeoutMs: 1_000 }))) {
+        throw new Error(`Port ${savedPort} is still busy after forced restart cleanup.`);
+      }
+    }
+  }
+} else if (restartSamePort) {
+  console.log("[toolcraft] Restart mode requested, but no saved port exists yet.");
+}
+
+if (!savedPort && port !== preferredPort) {
   console.log(`[toolcraft] Port ${preferredPort} is busy; using ${port} instead.`);
 }
 
+await writeSavedToolcraftPort(port);
+
 const pnpmCommand = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
 const child = spawn(pnpmCommand, ["exec", "vite", viteCommand, "--port", String(port), ...passthroughArgs], {
   env: {

package/templates/starter/scripts/toolcraft-port.mjs

@@ -1,7 +1,14 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
 import net from "node:net";
+import path from "node:path";
+import { promisify } from "node:util";
 
 export const DEFAULT_TOOLCRAFT_PORT = 3002;
 const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
+const execFileAsync = promisify(execFile);
+const PORT_STATE_DIR = ".toolcraft";
+const PORT_STATE_FILE = "server-port.json";
 
 export function readPreferredPort(names, fallback = DEFAULT_TOOLCRAFT_PORT, env = process.env) {
   for (const name of names) {
@@ -52,3 +59,98 @@ export async function findAvailablePort(startPort = DEFAULT_TOOLCRAFT_PORT) {
 
   throw new Error(`No free port found at or above ${startPort}.`);
 }
+
+function isValidPort(port) {
+  return Number.isInteger(port) && port > 0 && port <= 65_535;
+}
+
+export function getToolcraftPortStatePath(cwd = process.cwd()) {
+  return path.join(cwd, PORT_STATE_DIR, PORT_STATE_FILE);
+}
+
+export async function readSavedToolcraftPort(cwd = process.cwd()) {
+  try {
+    const source = await fs.readFile(getToolcraftPortStatePath(cwd), "utf8");
+    const state = JSON.parse(source);
+
+    return isValidPort(state.port) ? state.port : null;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+export async function writeSavedToolcraftPort(port, cwd = process.cwd()) {
+  if (!isValidPort(port)) {
+    throw new Error(`Cannot save invalid Toolcraft port: ${port}.`);
+  }
+
+  const statePath = getToolcraftPortStatePath(cwd);
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(
+    statePath,
+    `${JSON.stringify({ port, updatedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+}
+
+export async function getListeningProcessIds(port, execFileImpl = execFileAsync) {
+  if (!isValidPort(port)) {
+    return [];
+  }
+
+  try {
+    const { stdout } =
+      process.platform === "win32"
+        ? await execFileImpl("powershell", [
+            "-NoProfile",
+            "-Command",
+            `Get-NetTCPConnection -LocalPort ${port} -State Listen | Select-Object -ExpandProperty OwningProcess -Unique`,
+          ])
+        : await execFileImpl("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]);
+
+    return [...new Set(String(stdout).split(/\s+/).map(Number).filter(Number.isInteger))].filter(
+      (pid) => pid > 0 && pid !== process.pid,
+    );
+  } catch {
+    return [];
+  }
+}
+
+export async function killListeningProcessesOnPort(port, options = {}) {
+  const {
+    execFileImpl = execFileAsync,
+    killProcess = process.kill,
+    signal = "SIGTERM",
+  } = options;
+  const pids = await getListeningProcessIds(port, execFileImpl);
+
+  for (const pid of pids) {
+    try {
+      killProcess(pid, signal);
+    } catch (error) {
+      if (error?.code !== "ESRCH") {
+        throw error;
+      }
+    }
+  }
+
+  return pids;
+}
+
+export async function waitForPortAvailable(port, options = {}) {
+  const { intervalMs = 100, timeoutMs = 3_000 } = options;
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() <= deadline) {
+    if (await isPortAvailableOnLoopback(port)) {
+      return true;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  return false;
+}

package/templates/starter/scripts/toolcraft-port.test.mjs

@@ -1,8 +1,17 @@
 import assert from "node:assert/strict";
+import fs from "node:fs/promises";
 import net from "node:net";
+import os from "node:os";
+import path from "node:path";
 import test from "node:test";
 
-import { findAvailablePort } from "./toolcraft-port.mjs";
+import {
+  findAvailablePort,
+  getListeningProcessIds,
+  killListeningProcessesOnPort,
+  readSavedToolcraftPort,
+  writeSavedToolcraftPort,
+} from "./toolcraft-port.mjs";
 
 function listen(host) {
   return new Promise((resolve, reject) => {
@@ -71,3 +80,53 @@ test("findAvailablePort skips ports occupied on IPv4 localhost", async (t) => {
     "A port occupied on 127.0.0.1 must be treated as unavailable for localhost URLs.",
   );
 });
+
+test("saved Toolcraft port round-trips through local project state", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+
+  assert.equal(await readSavedToolcraftPort(cwd), null);
+
+  await writeSavedToolcraftPort(4123, cwd);
+
+  assert.equal(await readSavedToolcraftPort(cwd), 4123);
+});
+
+test("getListeningProcessIds parses unique listening process ids", async () => {
+  const pids = await getListeningProcessIds(4123, async () => ({
+    stderr: "",
+    stdout: "123\n456\n123\nnot-a-pid\n",
+  }));
+
+  assert.deepEqual(pids, [123, 456]);
+});
+
+test("killListeningProcessesOnPort targets listeners found on the port", async () => {
+  const killed = [];
+  const pids = await killListeningProcessesOnPort(4123, {
+    execFileImpl: async () => ({ stderr: "", stdout: "123\n456\n" }),
+    killProcess: (pid, signal) => {
+      killed.push({ pid, signal });
+    },
+  });
+
+  assert.deepEqual(pids, [123, 456]);
+  assert.deepEqual(killed, [
+    { pid: 123, signal: "SIGTERM" },
+    { pid: 456, signal: "SIGTERM" },
+  ]);
+});
+
+test("killListeningProcessesOnPort supports forced restart cleanup", async () => {
+  const killed = [];
+  const pids = await killListeningProcessesOnPort(4123, {
+    execFileImpl: async () => ({ stderr: "", stdout: "789\n" }),
+    killProcess: (pid, signal) => {
+      killed.push({ pid, signal });
+    },
+    signal: "SIGKILL",
+  });
+
+  assert.deepEqual(pids, [789]);
+  assert.deepEqual(killed, [{ pid: 789, signal: "SIGKILL" }]);
+});