@pixel-point/toolcraft 0.0.2

package/templates/starter/AGENTS.md

@@ -0,0 +1,186 @@
+# Toolcraft App Template Assembly Guide
+
+This is a standalone Toolcraft template app generated from the base starter.
+
+## Required Preflight
+
+Treat this `AGENTS.md` as the active project contract. Before planning or editing app code, runtime code, controls, canvas, panels, renderer, timeline, layers, export, or tests, you must read:
+
+1. `docs/toolcraft/workflow.md`
+
+Then follow `workflow.md` to choose the required contract docs and verification tier. Do not edit implementation files until this preflight is complete.
+
+## Quick Entry Contract
+
+1. Build through `defineToolcraft` and `ToolcraftApp`.
+2. Keep app state in Toolcraft runtime schema and commands.
+3. Keep product output in `canvasContent`; never render app UI there.
+4. Use built-in Toolcraft controls before custom controls.
+5. Do not hand-compose runtime surfaces or render built-in control components directly in app code; use `ToolcraftApp`, schema controls, `canvasContent`, `controlRenderers`, `onPanelAction`, and runtime commands.
+6. Before writing controls, make a Control Section Inventory that groups controls by product entity or workflow stage, not by UI component type.
+7. Keep control `label` short but semantically sufficient with the nearest visible section/group context, and put product-specific behavior help in schema `description`; runtime renders the label help tooltip only when that description adds meaning beyond the label.
+8. Enable layers and timeline only when product behavior requires them, then test the real UI.
+9. Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions, then resume without changing user playback state.
+10. If a Figma URL is provided, inspect the Figma file through MCP and rebuild from its structure; never implement from a screenshot or by eye.
+11. Choose an explicit persistence policy; use schema `persistence` for user-edited app settings that should survive reload, and test real reload restoration when localStorage is enabled.
+12. Use schema `settingsTransfer: "auto"` for complex apps that need import/export of control settings; never implement settings import/export through `panelActions` or route-local file inputs. After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Visible `Canvas width` and `Canvas height` inputs are owned by `editable-output` canvas sizing, not by settings transfer. When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section contains `Export Settings`, `Import Settings`, `Canvas width`, and `Canvas height` in that order and renders without a visible section heading.
+13. Product apps expose `Background` color and `Include background` controls and wire them into PNG export; live preview, workspace canvas backing, and video export keep the background.
+14. Keep `docs/toolcraft/agent-worklog.md` current with a decision trail, product decisions, evidence, verification, and risks.
+15. Prove every visible entity through acceptance, browser, and performance coverage.
+16. Workload performance scenarios must declare `stressFixture`; browser perf tests must use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values.
+17. Classify every implementation pass with a verification tier before editing. Use targeted checks for incremental edits and the full final gate only for final delivery, exports, or architecture/runtime/template changes.
+
+## Starter Baseline
+
+The generated folder starts as a neutral Toolcraft shell: canvas upload plus toolbar. It intentionally does not include demo controls, prompt fields, layers, or timeline. Do not treat test fixtures or documentation examples as product requirements. Add controls, timeline, layers, sticky actions, persistence, and custom renderers only after the requested product or reference app requires them.
+
+When the folder becomes a real product, update `src/app/app-acceptance.ts` from `appProductReadiness.mode: "starter"` to `mode: "product"` and fill `productName`, `productSummary`, and `requestedBehavior`. Renamed product folders are not allowed to keep neutral starter readiness.
+
+## License
+
+This project includes Toolcraft source code governed by the Toolcraft Designer License in `LICENSE.md`. `NOTICE.md` explains that generated apps include Toolcraft runtime, starter, UI component, documentation, and template source code. Designer client work is permitted under the license, and using AI coding assistants or agents such as Codex, Claude, ChatGPT, Cursor, or similar tools to work on generated apps is permitted. Platform, generator, AI software product, app-builder, website-builder, template-marketplace, and resale uses require a separate commercial license from Pixel Point.
+
+## Local Reference Docs
+
+Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app must remain buildable without the website.
+
+- `docs/toolcraft/workflow.md` — required preflight, task routing, worklog gate, and verification routing.
+- `docs/toolcraft/assembly-workflow.md` — runtime assembly, canvas output, and reference clone path.
+- `docs/toolcraft/decision-contract.md` — rule ids, levels, and enforcement expectations.
+- `docs/toolcraft/schema-reference.md` — schema authoring rules for `src/app/app-schema.ts`.
+- `docs/toolcraft/component-rules.md` — slider, segmented, color, upload, image picker, vector, layers, timeline, and footer action rules.
+- `docs/toolcraft/acceptance-testing.md` — app entity matrix and browser acceptance for `src/app/app-acceptance.ts`.
+- `docs/toolcraft/performance.md` — performance roles, scenarios, and workload coverage for `src/app/app-performance.ts`.
+- `docs/toolcraft/renderer-technique.md` — DOM, SVG, Canvas 2D, WebGL, and mixed renderer choices.
+- `docs/toolcraft/agent-worklog.md` — implementation decision trail, evidence, verification, and remaining risks.
+- `docs/toolcraft/custom-controls.md` — custom control registration through `controlRenderers`.
+
+## Edit Surface
+
+- Build the product by editing `src/app/app-schema.ts` and app-specific files under `src/app` and `src/routes`.
+- Keep route files thin: routes compose schema-backed app screens and product renderers.
+- Keep `src/app/app-acceptance.ts` aligned with every visible product entity.
+- Keep `src/app/app-performance.ts` as app-specific performance matrix config only.
+- Do not paste, restore, or duplicate runtime validators inside `src/app/app-performance.ts`.
+- Do not edit `src/toolcraft` unless you are intentionally changing the local copied Toolcraft runtime.
+- Before final delivery, replace the starter worklog with `Mode: product`, add `Decision Trail` entries for significant implementation passes, and record concrete decisions for renderer, timeline, layers, controls, export, and performance. Each decision-trail iteration must name the user-visible result, source/reference checked, contract rules applied, rejected alternatives, and state/output mapping. `pnpm test` fails if the worklog is missing, lacks the decision trail, or still describes the neutral starter.
+- `pnpm test` includes Toolcraft source integrity and local docs checks. If a desired control style is missing, fix the schema or regenerate from the upstream template/runtime; do not patch copied `src/toolcraft` files for one app.
+
+## Decision Contract Rule IDs
+
+These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep this list synced so standalone instructions do not drift from runtime validators.
+
+- `runtime-shell-required`
+- `canvas-no-app-ui`
+- `canvas-surface-preserved`
+- `canvas-handle-placement`
+- `panel-host-behavior`
+- `layers-enable-only-when-needed`
+- `layers-enabled-behavior`
+- `timeline-mode-choice`
+- `timeline-enabled-behavior`
+- `controls-product-coverage`
+- `output-export-required`
+- `controls-layout-heuristics`
+- `renderer-technique-inventory`
+- `reference-clone-source-of-truth`
+- `acceptance-product-observable`
+- `performance-coverage-levels`
+- `persistence-policy-explicit`
+- `workflow-required`
+
+## Runtime Contract
+
+- Use `defineToolcraft` from `@/toolcraft/runtime`.
+- Render the app through `ToolcraftApp` from `@/toolcraft/runtime/react`.
+- Use `<ToolcraftApp schema={appSchema} />` for schema-only apps.
+- Use `<ToolcraftApp schema={appSchema} canvasContent={<ProductRenderer />} />` for custom product renderers.
+- Use `renderDefaultCanvasMedia={false}` when a custom renderer replaces the default media preview.
+- Use `ToolcraftApp onPanelAction` for sticky footer product actions such as Generate, Apply, Export, Copy, or Download.
+- Keep final app behavior in the schema and runtime command bus, not in isolated local control state.
+- For animated products, write an Animation Intent Inventory before coding: use top playback timeline for product transport, keyframes timeline for editable property animation, and no timeline only for explicitly autonomous decorative output.
+- For keyframes timeline apps, renderers read keyframed settings through Toolcraft evaluated-value helpers/hooks. Do not parse timeline `valueLabel` strings or read raw `state.values` for keyframed targets.
+- Use schema `defaultValue` for every resettable control.
+- Route editor-owned actions through runtime commands such as `controls.reset`, `media.import`, `media.delete`, `canvas.center`, `history.undo`, and `history.redo`.
+
+## Required AI Workflow Skills
+
+AI must work on this app through the required workflow skills when the environment supports Codex skills. These skills are part of the task process, not optional reading.
+
+- Before writing or changing an app spec, use `brainstorming` to decide product behavior, canvas sizing mode, panels, media flow, controls, export/copy behavior, renderer technique, timeline/layer choice, and ambiguous requirements.
+- Before editing code from an approved spec, use `writing-plans` to produce a deterministic implementation plan focused on app files, tests, build, and browser verification.
+- Before fixing any broken control, failed test, build failure, visual mismatch, export issue, or runtime regression, use `systematic-debugging` to find the root cause first.
+- When the prompt includes a Figma URL, use Figma MCP/design context before implementation. Read the actual node, layer, component, variable, and asset structure; screenshots are only for final visual QA, not the source of truth.
+- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The automated browser gates are `pnpm test:browser` and `pnpm test:browser:perf`.
+- Run `pnpm ai:check` before app generation or major changes.
+- If a required skill is missing and the environment supports skill installation, install it before implementation and restart or refresh the session if the skill list does not update.
+- If skill installation is not available, stop before implementation and tell the user exactly which required skills are missing.
+- Do not silently skip required workflow skills, and do not replace them with an ad hoc plan.
+- The Toolcraft app contract overrides generic brainstorming approval and visual-companion rituals. If the user asks to build or port an app, that request is approval to produce the spec, plan, implementation, tests, build, and local run unless a product-critical ambiguity remains.
+- Do not ask the user to confirm decisions already covered by this contract, the prompt, or the reference app. Record the decision in the spec and continue.
+- Do not ask whether to enable a browser companion during brainstorming. Browser verification is mandatory after the app runs locally.
+- In standalone folders that are not git repositories, save spec/plan files without asking about commit requirements.
+
+## Verification Tier Classifier
+
+Before editing, write a short verification note:
+
+```md
+Verification tier: Tier N
+Reason: <changed surface and expected blast radius>
+Run: <commands and browser checks>
+Skip: <checks not needed for this pass and why>
+```
+
+Choose the tier by blast radius, not by line count. If uncertain, move one tier higher, not automatically to the full final gate.
+
+| Tier | Use When | Required Checks |
+| --- | --- | --- |
+| 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. |
+
+Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
+
+Do not run the full browser performance suite for Tier 0-2 edits unless a performance checkpoint trigger applies.
+
+Run a full performance checkpoint with `pnpm verify:perf` when the first working version of an app exists, when renderer/canvas/animation/export/timeline/layers change, after fixing a bug that previously broke functionality, after any performance optimization, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+
+Fast feature loops may defer full performance only when none of the checkpoint triggers above apply. Record the deferred check and reason in the verification note or worklog.
+
+## Required Checks
+
+For final delivery, run:
+
+```bash
+pnpm verify:final
+pnpm dev
+```
+
+Use `pnpm install` before this final gate when the folder is fresh or dependencies changed.
+
+`pnpm test` must include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output. `pnpm verify:perf` / `pnpm test:browser:perf` must run the performance browser suite sequentially so budgets are measured without parallel e2e noise.
+
+Do not stop or kill existing local servers to free a port. `pnpm dev`, `pnpm preview`, and browser verification prefer port `3002`, but automatically move to the next free port when it is busy. Use `TOOLCRAFT_PORT`, `TOOLCRAFT_DEV_PORT`, or `TOOLCRAFT_TEST_PORT` only to change the preferred starting port.
+
+## App Completion Bar
+
+The app is complete only when:
+
+- the Toolcraft runtime shell is present;
+- `canvasContent` contains product output only;
+- the runtime canvas backing remains visible behind product output;
+- every visible control affects runtime state and product output or a command side effect;
+- reset returns schema controls to `defaultValue`;
+- sticky footer export actions operate on final product output at `state.canvas.size`;
+- still products expose Export PNG; animated products expose Export Video plus Export PNG;
+- PNG export uses `Background` and `Include background` runtime controls with the standard export helper, while live preview, workspace canvas backing, and video keep background;
+- all export paths use retina output dimensions from the standard export helper;
+- layers are absent for single-layer apps and fully working when enabled;
+- timeline is absent, playback, keyframes, or custom reference timeline according to product behavior;
+- performance checks cover workload and responsiveness for all relevant controls;
+- detail-heavy or animated custom renderers pass real viewport drag and zoom stress checks;
+- workload browser perf tests use the declared `stressFixture` value from `app-performance.ts`;
+- browser tests verify upload/clear, controls, canvas sizing, toolbar, timeline/layers when enabled, sticky actions, output dimensions, and viewport stability.

package/templates/starter/LICENSE.md

@@ -0,0 +1,98 @@
+# Toolcraft Designer License
+
+Copyright (c) 2026 Pixel Point
+
+This license governs Toolcraft, including the CLI, starter template, runtime,
+UI components, documentation, and any generated application code that includes
+Toolcraft source code.
+
+## 1. Permitted Designer Use
+
+You may use Toolcraft for personal, educational, internal evaluation, and
+designer client work.
+
+Designer client work means using Toolcraft as part of paid design, development,
+consulting, or creative services to create a custom application for a specific
+client.
+
+Designers, freelancers, agencies, and studios may deliver generated
+applications to their clients, and those clients may use the delivered
+application for their own business, website, marketing, internal workflows, or
+product presentation.
+
+## 2. Generated Applications
+
+A generated application may be modified, deployed, and used by the designer or
+the designer's client as a custom client deliverable.
+
+You may not sell, sublicense, redistribute, publish, or offer generated
+applications as standalone products, stock templates, starter kits, theme packs,
+marketplace items, or reusable application templates.
+
+## 3. AI-Assisted Development
+
+You may use AI coding assistants, AI agents, design assistants, large language
+models, editors, IDE assistants, and similar tools to create, inspect, modify,
+refactor, test, document, deploy, or maintain generated applications for any use
+permitted by this license.
+
+This includes tools such as Codex, Claude, ChatGPT, Cursor, and similar
+assistants. Using those tools to work on Toolcraft projects or generated
+applications does not, by itself, make your use a prohibited AI software, AI app
+builder, AI design tool, code generation platform, or competing generator tool.
+
+This section does not allow you to package, embed, host, or provide Toolcraft or
+generated applications as part of a paid AI software product, AI app builder, AI
+design tool, code generation platform, or competing generator service.
+
+## 4. Prohibited Uses
+
+You may not use Toolcraft, generated applications, or any Toolcraft runtime,
+starter, UI, or template code as part of:
+
+- paid AI software;
+- AI app builders;
+- AI design tools;
+- website builders;
+- app builders;
+- design-to-code SaaS products;
+- code generation platforms;
+- template marketplaces;
+- competing generator tools;
+- any product or service whose primary purpose is to let third parties generate,
+  resell, or reuse applications based on Toolcraft.
+
+These uses require a separate commercial license from Pixel Point.
+
+## 5. No Hosted Generator or Resale Rights
+
+You may not provide Toolcraft or substantially similar functionality to third
+parties as a hosted service, API, plugin, marketplace product, or downloadable
+generator without a separate commercial license.
+
+## 6. No Trademark Rights
+
+This license does not grant rights to use the Pixel Point or Toolcraft names,
+logos, branding, or trademarks except to identify Toolcraft as the tool used to
+create a project.
+
+## 7. Ownership
+
+You own the original design, content, configuration, and product-specific code
+that you create.
+
+Pixel Point retains ownership of Toolcraft, including the CLI, starter template,
+runtime, UI components, documentation, and copied Toolcraft source code included
+in generated applications.
+
+## 8. Commercial Licensing
+
+If your intended use is not allowed by this license, you must obtain a separate
+commercial license before using Toolcraft for that purpose.
+
+Contact: licensing@pixel-point.com
+
+## 9. No Warranty
+
+Toolcraft is provided "as is", without warranty of any kind. Pixel Point is not
+liable for damages arising from use of Toolcraft or generated applications.

package/templates/starter/NOTICE.md

@@ -0,0 +1,8 @@
+# Toolcraft Notice
+
+This application was generated with Toolcraft and includes Toolcraft runtime,
+starter, UI component, documentation, and template source code.
+
+Use of that Toolcraft code is governed by `LICENSE.md`. Product-specific design,
+content, configuration, and application code that you create remain yours, but
+the Toolcraft source copied into this project remains owned by Pixel Point.

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

@@ -0,0 +1,41 @@
+# Toolcraft Template Local Docs
+
+This folder is the local operational reference for a standalone Toolcraft template app.
+
+Use `../../AGENTS.md` as the entry contract, then read `workflow.md` before planning or editing app work. Use the remaining docs when a decision needs more detail:
+
+The starter app itself is intentionally neutral. It should show the Toolcraft canvas/upload/toolbar baseline only until the product schema is authored. Demo controls, prompt inputs, layers, and timeline belong in tests/docs or in a real generated product that needs them.
+
+1. `workflow.md` — required preflight, task routing, worklog gate, and verification routing.
+2. `assembly-workflow.md` — how the app must be assembled.
+3. `decision-contract.md` — hard rules, defaults, heuristics, and escape hatches.
+4. `schema-reference.md` — how to write `src/app/app-schema.ts`.
+5. `component-rules.md` — component-specific layout and behavior rules.
+6. `acceptance-testing.md` — how every visible entity proves it works.
+7. `performance.md` — performance matrix and responsiveness gates.
+8. `renderer-technique.md` — how to choose DOM, SVG, Canvas 2D, WebGL, WebGPU, or mixed rendering.
+9. `agent-worklog.md` — implementation decision trail, evidence, verification, and risks.
+10. `custom-controls.md` — how to register custom controls without editing `src/toolcraft`.
+
+`agent-worklog.md` starts as a neutral starter template. Once the folder becomes a product, change it to `Mode: product`, add `Decision Trail` entries for significant implementation passes, and record concrete renderer, timeline, layers, controls, export, and performance decisions with evidence. Each iteration must explain the user-visible result, source/reference checked, contract rules applied, rejected alternatives, and state/output mapping so later debugging can reconstruct why the app was built that way. The final test gate fails if this worklog is missing, stale, lacks decision-trail fields, or lacks verification.
+
+Every implementation pass must choose a verification tier before editing. Use the smallest tier that covers the changed surface, and move one tier higher when unsure.
+
+| Tier | Use for | Typical command |
+| --- | --- | --- |
+| Tier 0 | Docs/copy only | targeted docs/typecheck |
+| Tier 1 | One control or panel visual state | targeted test + focused browser check |
+| Tier 2 | Schema, defaults, persistence, actions, product mapping | `pnpm verify:quick` + relevant browser acceptance |
+| Tier 3 | Renderer, canvas, timeline, layers, upload, export, zoom, heavy controls, or a performance checkpoint trigger | `pnpm verify:quick` + targeted browser/perf scenarios |
+| Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final` |
+
+Run `pnpm verify:perf` when a performance checkpoint is triggered: first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+
+Fresh folders or dependency changes need `pnpm install` before verification. Final delivery still starts the local app after the gate:
+
+```bash
+pnpm verify:final
+pnpm dev
+```
+
+Do not kill existing local servers to free `3002`. Dev, preview, and browser verification prefer `3002`, then move to the next free port automatically.

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

@@ -0,0 +1,205 @@
+# Acceptance Testing
+
+Every visible product entity must prove it works. A control is not accepted because it renders; it is accepted only when tests prove user interaction changes runtime state and the final product output, command side effect, timeline frame, layer result, media lifecycle, or canvas viewport.
+
+## Required Files
+
+- `src/app/app-acceptance.ts`
+- `src/app/app-acceptance.test.ts`
+- `src/app/app-performance.ts`
+- `src/app/app-performance.test.ts`
+- `docs/toolcraft/agent-worklog.md`
+- `e2e/app-browser-acceptance.spec.ts`
+- `e2e/app-controls.spec.ts`
+- `e2e/app-performance.spec.ts`
+- `e2e/product-observable-helpers.ts`
+
+`pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add `pnpm verify:perf` whenever a performance checkpoint is triggered.
+
+A performance checkpoint is triggered by the first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+
+## Product Readiness
+
+The exported starter may keep `appProductReadiness.mode: "starter"` only while it is still a neutral template. A real product must switch it to `mode: "product"` and fill:
+
+- `productName`;
+- `productSummary`;
+- `requestedBehavior`.
+
+Product readiness also requires product surface: controls, layers, timeline, `canvasContent`, or acceptance coverage. A renamed product folder must not pass tests as a neutral starter.
+
+## Implementation Worklog
+
+Product apps must update `docs/toolcraft/agent-worklog.md` before final delivery. The file records why the app chose its renderer, timeline mode, layer policy, control grouping, export behavior, and performance strategy.
+
+The worklog must declare `Mode: product`. Every `Decision Trail` iteration must include `Request:`, `Task type:`, `User-visible result:`, `Source/reference checked:`, `Docs/contracts read:`, `Contract rules applied:`, `Decision:`, `Alternatives rejected:`, `State/output mapping:`, `Files changed:`, `Verification:`, `Skipped checks:`, and `Risks:`. `State/output mapping:` names how controls, commands, timeline, layers, media, or renderer state reaches the visible product or export. Each decision section (`Renderer`, `Timeline`, `Layers`, `Controls`, `Export`, `Performance`) must include `Decision:`, `Reason:`, and `Evidence:` entries. `Evidence` should name files, reference behavior, contract rules, browser checks, performance checks, or exact commands. `Verification` must list concrete checks such as `pnpm verify:quick`, `pnpm verify:perf`, browser tests, or Playwright scenarios. `Risks` must include either `Risk:` entries or `None:` with a reason.
+
+The acceptance gate fails if the worklog is missing, still says `Mode: starter`, or lacks concrete decision evidence.
+
+## Acceptance Rows
+
+Every visible schema control, custom renderer feature, media lifecycle, timeline behavior, layer behavior, canvas sizing behavior, toolbar command, sticky action, and product editing handle needs an acceptance row.
+
+Each row should name:
+
+- stable `id`;
+- `kind`;
+- runtime `target` when the entity edits state;
+- `componentType`;
+- fixture data;
+- real user action;
+- expected product-level observable;
+- evidence type;
+- exact `automatedTestName`;
+- exact `browserTestName`.
+- `controlPartCoverage` when the control is compound.
+- `canvasSizingCoverage: "fixed-output-size"` when `canvas.sizing.mode` is `fixed-output`.
+- `persistenceCoverage: "reload"` when schema `persistence.storage` is `"localStorage"`.
+
+The test gate rejects rows without matching automated and browser test names.
+
+`fixed-output` canvas sizing must be deliberate. Its runtime acceptance row must explain why width and height are non-editable. A default size from the prompt should use `editable-output`, which keeps the runtime Canvas width and Canvas height controls.
+
+When localStorage persistence is enabled, add a runtime acceptance row that proves reload behavior. The browser test must change a real user-facing setting, wait for persistence to write, call a real page reload, and verify the restored control value or product output. Importing a settings JSON file is not persistence coverage.
+
+## Compound Controls
+
+Compound controls have multiple semantic value parts inside one visible control. Their acceptance row must declare `controlPartCoverage`, and the browser test must explicitly exercise each required part against product output.
+
+Required parts:
+
+| Control | Required `controlPartCoverage` |
+| --- | --- |
+| `anchorGrid` | `anchorGrid.position` |
+| `channelMixer` | `channelMixer.activeChannel`, `channelMixer.values`; only for RGB channel matrix behavior |
+| `colorOpacity` | `colorOpacity.hex`, `colorOpacity.opacity` |
+| `curves` | RGB variant: `curves.activeChannel`, `curves.points`; `variant: "single"`: `curves.points` |
+| `fontPicker` | `fontPicker.fontId`, `fontPicker.fontWeight`, `fontPicker.fontSize`, `fontPicker.letterSpacing`, `fontPicker.lineHeight`, `fontPicker.textCase`, `fontPicker.color`, `fontPicker.opacity` |
+| `gradient` | `gradient.gradientType`, `gradient.angle`, `gradient.stops.position`, `gradient.stops.color`, `gradient.stops.opacity` |
+| `palette` | `palette.family`, `palette.shade` |
+| `rangeInput` | `rangeInput.start`, `rangeInput.end` |
+| `rangeSlider` | `rangeSlider.lower`, `rangeSlider.upper` |
+| `vector` | `vector.x`, `vector.y` |
+
+Testing only one sub-control is not enough. For example, a `gradient` test that changes only a stop color must fail if the app also renders Gradient type, Angle, Position, or Opacity controls.
+
+For `curves`, the acceptance row must match the intended variant. Semantic one-dimensional curves such as acceleration, bend, easing, response, depth, mask, opacity, threshold, or remap curves must set `variant: "single"` and prove `curves.points`; RGB active-channel coverage is reserved for color-correction or channel-specific curves.
+
+For `fontPicker`, product output evidence must come from actual rendered/exported product text after changing the font, weight, size, letter spacing, line height, text case, color, and opacity. Runtime value changes, selected labels, or popup font previews are preflight checks, not final acceptance.
+
+## Control Selection Gates
+
+Acceptance must catch wrong-substitution failures. If the prompt, spec, or app behavior needs a value model owned by a built-in control, the schema must use that built-in or include a documented built-in fit check.
+
+High-confidence wrong-substitution cases:
+
+- gradient, stops, angle, fill transition, or adjustable gradient without `gradient`;
+- typography without `fontPicker`;
+- sibling typography controls that split case, color, opacity, size, weight, letter spacing, or line height away from `fontPicker`;
+- color plus opacity without `colorOpacity`;
+- from/to range without `rangeSlider` or `rangeInput`;
+- curve, remap, easing, or response without `curves`;
+- position, direction, focus, or vector without `vector`;
+- source upload without `fileDrop`;
+- app-wide transport in the controls panel instead of timeline;
+- segmented choices that clip instead of falling back to `select`;
+- custom controls recreating built-ins.
+
+Rows that use custom controls must include `customControlCoverage` and typed `builtInFitCheck`.
+
+```ts
+builtInFitCheck: {
+  checkedBuiltIns: ["fileDrop", "imagePicker", "select"],
+  closestBuiltIn: "fileDrop",
+  whyInsufficient:
+    "FileDrop imports source files, but it does not provide ordering, preview, remove, and density mapping in one runtime value.",
+  productObservable:
+    "Ordering uploaded glyphs changes the rendered glyph ramp output.",
+}
+```
+
+The fit check names real checked built-ins, the closest built-in or `"none"`, why it is insufficient, and the product-observable evidence that proves the custom control works.
+
+## Valid Evidence
+
+Valid acceptance evidence includes:
+
+- rendered product pixels;
+- exported image/video bytes;
+- canvas hash or DOM-visible product result;
+- clipboard, file, or blob payload;
+- cleared media preview and canvas;
+- selected layer output;
+- changed canvas viewport;
+- changed timeline playback state plus rendered frame.
+- restored persisted value or product output after browser reload.
+
+Product apps must include output delivery acceptance. Still-output apps need `Export PNG` evidence. Animated apps need both `Export Video` evidence and `Export PNG` evidence. Clipboard copy can be tested as an additional behavior, but it cannot replace export coverage.
+
+Async Export, Download, Copy, Generate, or Apply acceptance must prove the sticky footer top accent indicator is visible while the returned `onPanelAction` Promise is pending, advances when `reportProgress(0..1)` is called, and hides after it settles. Video export acceptance must prove frame-based progress updates during render/encode instead of only toggling a pending state.
+
+Animated app acceptance must also exercise the separate `Video Export` section: choose at least two `export.video.format` values, choose at least two `export.video.resolution` values, verify unsupported MIME/container choices fall back safely, and assert exported video bytes, dimensions, MIME/container, and duration match runtime timeline state. The duration assertion must load the exported blob as a video, wait for metadata, and compare `video.duration` with the edited timeline duration; `blobSize > 0`, `blobType`, WebM parser fallback, or assigning the expected duration when metadata is missing are not enough.
+
+Footer action acceptance must not include Reset. Reset is already available in the controls panel header and uses schema `defaultValue`; duplicating it in sticky `panelActions` fails acceptance.
+
+Local `actions` acceptance must click every visible action and prove the nearby entity changed through runtime state or product output. A section-level `Randomize palette` must change palette output, `Normalize weights` must change weights/output, and `Clear selection` must clear only the scoped selection. Do not accept a test that only proves the button rendered.
+
+PNG export tests must prove runtime background behavior: changing the background color affects preview/export, turning `export.includeBackground` off creates transparent PNG output while live preview, workspace canvas backing, and video keep the background, turning it on includes the current background color in PNG, and exported pixel dimensions are retina size, at least `state.canvas.size * 2`.
+
+Invalid final acceptance evidence:
+
+- control exists;
+- `data-*` attribute changed;
+- runtime state was mutated directly;
+- DOM text changed but product output did not;
+- shader uniform changed without output proof;
+- helper fixture proves a function but not the app behavior.
+
+If a behavior cannot be proven through product output or a side effect, remove the entity or ask whether it is required.
+
+## Browser Gate
+
+Browser tests must open the running app and interact with the real UI by pointer, keyboard, file upload, canvas drag, toolbar click, timeline scrub, or layer drag.
+
+Do not dispatch runtime commands directly for browser acceptance unless the entity is itself a command API. Browser tests must exercise what the user actually sees.
+
+Every browser test should prove:
+
+- the interaction is possible;
+- runtime state changes through the expected target;
+- product output or command side effect changes;
+- canvas zoom, offset, and output dimensions do not jump unexpectedly.
+
+Acceptance rows with `product-output`, `rendered-pixels`, or `timeline-output` evidence must use `expectToolcraftProductObservableToChange` or explicit before/after snapshots from `getToolcraftProductObservableSnapshot` in `e2e/product-observable-helpers.ts`. Runtime state, selected labels, row counts, canvas existence, or generic hashes without the shared product observable helper are not final proof.
+
+Animated viewport tests must also prove that canvas drag, pan, pinch, zoom, and radar/center interactions suspend or coalesce non-essential animation preview work without changing the user's play/pause state. After the interaction, the renderer must resume from the correct timeline or autonomous time and keep canvas zoom/offset stable.
+
+## Timeline And Layers
+
+When animation controls exist without `panels.timeline`, acceptance validation requires `starterTransferMode.animationIntent.mode = "autonomous"`. That intent must explain why the animation is decorative/self-running and must cover no user-facing transport, no play/pause, no scrub, no duration control, no loop control, and no export-at-time.
+
+Playback timeline coverage must prove play/pause, scrub, duration, loop, restart when exposed, non-looping Play at the end restarts from 0, and export/copy at selected time when relevant. Duration coverage must edit the real `Edit timeline duration` control, prove the playback range changes, and prove the renderer maps one full product animation cycle to `state.timeline.durationSeconds`. Tests should compare visible or exported output at 0, midpoint, and end after changing the timeline duration. Do not accept a renderer that uses a separate fixed local duration while the timeline displays another duration, and do not accept a renderer effect that watches `state.timeline.durationSeconds` only to dispatch `timeline.setDuration` back to a computed local value.
+
+Keyframe timeline coverage must prove diamond creation, expanded rows, keyframe updates on control change, scrub/playback evaluation, and product output changes for every inferred keyframe-capable control. Tests must prove renderers consume typed evaluated values from the Toolcraft keyframe evaluator; checking `valueLabel`, row count, or source strings is not enough.
+
+Layer browser coverage must use the real LayersPanel UI: click rows, toggle visibility, drag rows to reorder, and drag rows into groups.
+
+## Component Variants
+
+Component variants are acceptance requirements.
+
+- Discrete sliders must render `[data-slot="slider"][data-variant="discrete"]`, show the expected full-width markers, and remain smooth while dragging.
+- Schema sliders must stay full-width and stacked; only `fontPicker` may pair its internal letter-spacing and line-height footer sliders.
+- Continuous stepped sliders must not render discrete markers.
+- Range sliders must stay full-width, start with different lower and upper defaults, and accept built-in manual range separators such as slash, hyphen, spaces, and dashes.
+- Segmented controls must preserve cell padding and avoid label collision.
+- Select, segmented, and image-picker controls should cover every visible option unless options come from separately tested runtime data.
+- Custom controls must declare `customControlCoverage` and `builtInFitCheck`. Coverage proves the custom control is not a built-in replacement, uses kit chrome, keeps only necessary UI, writes through runtime state, and changes product output; the fit check proves which built-ins were considered and why the custom interaction is necessary.
+
+Performance browser tests must assert budgets through `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)`. Workload browser tests must apply values from `getToolcraftPerformanceStressValue(appPerformance, scenarioId)`. Do not hardcode budget numbers or toy workload values in e2e tests; `app-performance.ts` is the single source of truth.
+
+## Fixtures
+
+Use fixtures that make each behavior visible. For example, background character-size controls need visible background characters, transparency needs alpha-sensitive pixels, selected-layer controls need multiple layers, timeline controls need deterministic playback or keyframe fixtures, and mode-specific controls need fixtures for every mode branch. Conditional coverage must prove visible controls, hidden controls, disabled controls, preserved values after switching away and back, and renderer output for the active branch. Count-controlled control banks must test both the low-count UI state and the expanded-count UI state; the test fails if inactive controls remain visible while the renderer ignores them.
+
+Generic hash differences are not enough for semantic controls. If a control promises a direction, test that direction.

package/templates/starter/docs/toolcraft/agent-worklog.md

@@ -0,0 +1,81 @@
+# Implementation Worklog
+
+This file records product decisions and the evidence behind them. Keep it short, factual, and current. Update it after schema, renderer, timeline, layer, export, performance, or acceptance decisions.
+
+## Status
+
+Mode: starter
+
+The neutral starter has no product renderer, timeline, layers, export behavior, or performance workload yet. Replace this status with `Mode: product` when the folder becomes a real app.
+
+## Decision Trail
+
+No product iterations yet. When this folder becomes a product, replace this note with iteration entries:
+
+### Iteration 1 — <short task name>
+
+- Request:
+- Task type:
+- User-visible result:
+- Source/reference checked:
+- Docs/contracts read:
+- Contract rules applied:
+- Decision:
+- Alternatives rejected:
+- State/output mapping:
+- Files changed:
+- Verification:
+- Skipped checks:
+- Risks:
+
+## Decisions
+
+### Renderer
+
+- Decision: No product renderer yet.
+- Reason: The starter is intentionally neutral.
+- Evidence: No `canvasContent` product renderer is declared.
+
+### Timeline
+
+- Decision: No timeline yet.
+- Reason: The starter has no product animation behavior.
+- Evidence: `panels.timeline` is omitted.
+
+### Layers
+
+- Decision: No layers yet.
+- Reason: The starter has no layer workflow.
+- Evidence: `panels.layers` is omitted.
+
+### Controls
+
+- Decision: No product controls yet.
+- Reason: Controls are added only after the requested product behavior is known.
+- Evidence: The starter schema exposes no product control sections.
+
+### Export
+
+- Decision: No product export yet.
+- Reason: Export actions are added when the app has product output.
+- Evidence: No sticky product `panelActions` are declared.
+
+### Performance
+
+- Decision: No product performance workload yet.
+- Reason: Performance scenarios depend on renderer and control workload.
+- Evidence: The starter performance matrix is a neutral baseline.
+
+## Evidence
+
+- Source reviewed: neutral starter schema and local Toolcraft docs.
+- Contract applied: starter baseline remains neutral until product behavior exists.
+
+## Verification
+
+- Run: `pnpm verify:quick` for starter baseline checks.
+- Run: `pnpm verify:final` after turning this folder into a product app.
+
+## Risks
+
+- Risk: This template must be replaced with product-specific decisions before final delivery.