@pixel-point/toolcraft 0.0.2 → 0.0.4

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

@@ -766,7 +766,7 @@ function getToggleControlLabelError(
     normalizeToolcraftSemanticText(label) ===
       normalizeToolcraftSemanticText(sectionTitle)
   ) {
-    return `toggle label "${label}" duplicates section title "${sectionTitle}". Use label false for a visual-only toggle or rename the toggle to a more specific setting.`;
+    return `toggle label "${label}" duplicates section title "${sectionTitle}". Use a shorter contextual label such as "Include" or rename the toggle to a more specific setting.`;
   }
 
   return undefined;
@@ -893,6 +893,15 @@ function actionLooksLikePngExport(action: ToolcraftActionSchema | string): boole
   );
 }
 
+function actionLooksLikeVideoExport(action: ToolcraftActionSchema | string): boolean {
+  const text = getActionSearchText(action).replace(/([a-z])([A-Z])/g, "$1 $2");
+
+  return (
+    (/\b(export|download)\b/i.test(text) && /\b(video|mp4|webm|mov)\b/i.test(text)) ||
+    /\bexport\.video\b/i.test(text)
+  );
+}
+
 function schemaHasPngExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
   return (schema.panels.controls?.sections ?? []).some((section) =>
     Object.values(section.controls).some(
@@ -903,6 +912,57 @@ function schemaHasPngExportPanelAction(schema: ResolvedToolcraftAppSchema): bool
   );
 }
 
+function schemaHasVideoExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
+  return (schema.panels.controls?.sections ?? []).some((section) =>
+    Object.values(section.controls).some(
+      (control) =>
+        control.type === "panelActions" &&
+        getControlActions(control).some(actionLooksLikeVideoExport),
+    ),
+  );
+}
+
+function getFirstPanelActionsSectionIndex(schema: ResolvedToolcraftAppSchema): number {
+  return (schema.panels.controls?.sections ?? []).findIndex((section) =>
+    Object.values(section.controls).some((control) => control.type === "panelActions"),
+  );
+}
+
+function getSchemaControlsSectionByTitle(
+  schema: ResolvedToolcraftAppSchema,
+  title: string,
+): NonNullable<ResolvedToolcraftAppSchema["panels"]["controls"]>["sections"][number] | undefined {
+  const normalizedTitle = normalizeToolcraftSemanticText(title);
+
+  return (schema.panels.controls?.sections ?? []).find(
+    (section) => normalizeToolcraftSemanticText(section.title) === normalizedTitle,
+  );
+}
+
+function getSchemaControlsSectionIndexByTitle(
+  schema: ResolvedToolcraftAppSchema,
+  title: string,
+): number {
+  const normalizedTitle = normalizeToolcraftSemanticText(title);
+
+  return (schema.panels.controls?.sections ?? []).findIndex(
+    (section) => normalizeToolcraftSemanticText(section.title) === normalizedTitle,
+  );
+}
+
+function getSectionControlEntryByTarget(
+  section:
+    | NonNullable<ResolvedToolcraftAppSchema["panels"]["controls"]>["sections"][number]
+    | undefined,
+  target: string,
+): readonly [string, ToolcraftControlSchema] | undefined {
+  if (!section) {
+    return undefined;
+  }
+
+  return Object.entries(section.controls).find(([, control]) => control.target === target);
+}
+
 function schemaHasOutputBackgroundColorControl(
   controls: readonly ToolcraftVisibleControl[],
 ): boolean {
@@ -942,6 +1002,49 @@ function isOutputBackgroundToggleControl(visibleControl: ToolcraftVisibleControl
   );
 }
 
+function getOutputBackgroundColorEntry(
+  section:
+    | NonNullable<ResolvedToolcraftAppSchema["panels"]["controls"]>["sections"][number]
+    | undefined,
+): readonly [string, ToolcraftControlSchema] | undefined {
+  if (!section) {
+    return undefined;
+  }
+
+  return Object.entries(section.controls).find(([controlId, control]) => {
+    if (control.type !== "color") {
+      return false;
+    }
+
+    return /\b(background|backdrop|scene|canvas)\b/i.test(
+      [section.title, controlId, control.target, getControlLabelText(control)]
+        .join(" ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2"),
+    );
+  });
+}
+
+function sectionHasEqualWidthOutputBackgroundRow(
+  section:
+    | NonNullable<ResolvedToolcraftAppSchema["panels"]["controls"]>["sections"][number]
+    | undefined,
+  toggleControlId: string | undefined,
+  colorControlId: string | undefined,
+): boolean {
+  if (!section || !toggleControlId || !colorControlId) {
+    return false;
+  }
+
+  return (section.layoutGroups ?? []).some(
+    (layoutGroup) =>
+      layoutGroup.layout === "inline" &&
+      layoutGroup.columns === 2 &&
+      layoutGroup.controls.length === 2 &&
+      layoutGroup.controls[0] === toggleControlId &&
+      layoutGroup.controls[1] === colorControlId,
+  );
+}
+
 const SEGMENTED_CONTROL_MAX_OPTIONS = 4;
 const SEGMENTED_CONTROL_MAX_OPTION_LABEL_LENGTH = 9;
 const SEGMENTED_CONTROL_MAX_TOTAL_LABEL_LENGTH = 24;
@@ -1823,7 +1926,7 @@ export function validateToolcraftAcceptanceCoverage(
 
         if (unsafeBooleanLabels.length > 0) {
           errors.push(
-            `${sectionLabel} layoutGroups inline row "${layoutGroup.controls.join(", ")}" includes toggle label ${unsafeBooleanLabels.map(([controlId, control]) => `${controlId} "${getInlineSwitchLabelText(controlId, control)}"`).join(", ")} that is too long for a compact toggle-plus-parameter row. Keep the toggle label short, hide it when the section title supplies the context, or stack the controls.`,
+            `${sectionLabel} layoutGroups inline row "${layoutGroup.controls.join(", ")}" includes toggle label ${unsafeBooleanLabels.map(([controlId, control]) => `${controlId} "${getInlineSwitchLabelText(controlId, control)}"`).join(", ")} that is too long for a compact toggle-plus-parameter row. Keep the toggle label short, such as "Include" inside Background, or stack the controls.`,
           );
         }
       }
@@ -1861,15 +1964,199 @@ export function validateToolcraftAcceptanceCoverage(
   }
 
   if (schemaHasPngExportPanelAction(schema)) {
+    const backgroundSection = getSchemaControlsSectionByTitle(schema, "Background");
+    const backgroundSectionIndex = getSchemaControlsSectionIndexByTitle(schema, "Background");
+    const panelActionsSectionIndex = getFirstPanelActionsSectionIndex(schema);
+    const imageExportSectionIndex = getSchemaControlsSectionIndexByTitle(schema, "Image Export");
+    const videoExportSectionIndex = getSchemaControlsSectionIndexByTitle(schema, "Video Export");
+    const hasVideoExportAction = schemaHasVideoExportPanelAction(schema);
+    const expectedOutputSettingsIndex =
+      imageExportSectionIndex >= 0 ? imageExportSectionIndex : videoExportSectionIndex;
+    const finalExportSettingsIndex = hasVideoExportAction
+      ? videoExportSectionIndex
+      : imageExportSectionIndex;
+    const includeBackgroundEntry = getSectionControlEntryByTarget(
+      backgroundSection,
+      "export.includeBackground",
+    );
+    const backgroundColorEntry = getOutputBackgroundColorEntry(backgroundSection);
+    const imageExportSection = getSchemaControlsSectionByTitle(schema, "Image Export");
+    const imageFormatEntry = getSectionControlEntryByTarget(
+      imageExportSection,
+      "export.image.format",
+    );
+    const imageResolutionEntry = getSectionControlEntryByTarget(
+      imageExportSection,
+      "export.image.resolution",
+    );
+    const imageFormatControl = imageFormatEntry?.[1];
+    const imageResolutionControl = imageResolutionEntry?.[1];
+    const imageFormatOptionValues =
+      imageFormatControl?.options?.map((option) => option.value.toLowerCase()) ?? [];
+    const imageResolutionOptionValues =
+      imageResolutionControl?.options?.map((option) => option.value.toLowerCase()) ?? [];
+
+    if (!backgroundSection) {
+      errors.push(
+        'Product apps with Export PNG must expose a separate controls section titled "Background" directly before the first export settings section.',
+      );
+    }
+
+    if (
+      backgroundSectionIndex >= 0 &&
+      expectedOutputSettingsIndex >= 0 &&
+      backgroundSectionIndex !== expectedOutputSettingsIndex - 1
+    ) {
+      errors.push(
+        'The "Background" controls section must sit directly before the first export settings section: Image Export when PNG export exists, otherwise Video Export.',
+      );
+    }
+
+    if (
+      finalExportSettingsIndex >= 0 &&
+      panelActionsSectionIndex >= 0 &&
+      finalExportSettingsIndex !== panelActionsSectionIndex - 1
+    ) {
+      errors.push(
+        'Export settings must sit directly above sticky footer actions: Image Export for still apps, or Video Export after Image Export for animated apps.',
+      );
+    }
+
+    if (
+      hasVideoExportAction &&
+      imageExportSectionIndex >= 0 &&
+      videoExportSectionIndex >= 0 &&
+      imageExportSectionIndex !== videoExportSectionIndex - 1
+    ) {
+      errors.push(
+        'Animated apps with both Export PNG and Export Video must place Image Export immediately before Video Export.',
+      );
+    }
+
     if (!schemaHasOutputBackgroundColorControl(controls)) {
       errors.push(
         "Product apps with Export PNG must expose a user-facing background color control such as appearance.background or scene.background. Preview, PNG export, and video export must read that runtime value instead of hardcoding the product background.",
       );
     }
 
+    if (!backgroundColorEntry) {
+      errors.push(
+        'The "Background" section must contain the renderer-owned background color control, such as appearance.background or scene.background.',
+      );
+    } else {
+      const [, backgroundColorControl] = backgroundColorEntry;
+
+      if (backgroundColorControl.label !== false) {
+        errors.push(
+          'The background color control inside the required "Background" section must use label false; the section title already supplies the visible context.',
+        );
+      }
+    }
+
     if (!schemaHasOutputBackgroundToggleControl(controls)) {
       errors.push(
-        "Product apps with Export PNG must expose a user-facing Include background / Transparent background control such as export.includeBackground. PNG export must pass that runtime value to createToolcraftPngExportCanvas includeBackground; video export keeps the background.",
+        'Product apps with Export PNG must expose export.includeBackground inside the required "Background" section as a Switch labeled "Include". PNG export must pass that runtime value to createToolcraftPngExportCanvas includeBackground; video export keeps the background.',
+      );
+    }
+
+    if (!includeBackgroundEntry) {
+      errors.push(
+        'The "Background" section must contain export.includeBackground as the Include switch.',
+      );
+    } else {
+      const [, includeBackgroundControl] = includeBackgroundEntry;
+
+      if (includeBackgroundControl.type !== "switch") {
+        errors.push('export.includeBackground must be a Switch control labeled "Include".');
+      }
+
+      if (getControlLabelText(includeBackgroundControl) !== "Include") {
+        errors.push(
+          'export.includeBackground must use the short visible label "Include"; the Background section title already supplies the rest of the context.',
+        );
+      }
+    }
+
+    if (
+      !sectionHasEqualWidthOutputBackgroundRow(
+        backgroundSection,
+        includeBackgroundEntry?.[0],
+        backgroundColorEntry?.[0],
+      )
+    ) {
+      errors.push(
+        'The "Background" section must render export.includeBackground and the background color in one two-column inline layoutGroup, with Include on the left and the unlabeled background color on the right.',
+      );
+    }
+
+    if (!imageExportSection) {
+      errors.push(
+        'Apps with Export PNG must expose image export settings in a separate controls section titled "Image Export" directly above sticky footer export actions or directly before "Video Export" when video export also exists.',
+      );
+    }
+
+    if (!imageFormatControl) {
+      errors.push(
+        'The separate "Image Export" section must include a format control with target "export.image.format".',
+      );
+    } else {
+      if (imageFormatControl.type !== "select") {
+        errors.push(
+          'Image Export format must be a Select control so it matches the Video Export settings structure.',
+        );
+      }
+
+      if (!imageFormatOptionValues.includes("png") || !imageFormatOptionValues.includes("jpg")) {
+        errors.push('Image Export format options must include "png" and "jpg".');
+      }
+
+      if (imageFormatControl.defaultValue !== "png") {
+        errors.push('Image Export format must default to "png".');
+      }
+    }
+
+    if (!imageResolutionControl) {
+      errors.push(
+        'The separate "Image Export" section must include a resolution control with target "export.image.resolution".',
+      );
+    } else {
+      if (imageResolutionControl.type !== "select") {
+        errors.push(
+          'Image Export resolution must be a Select control so it matches the Video Export settings structure.',
+        );
+      }
+
+      if (
+        !imageResolutionOptionValues.includes("2k") ||
+        !imageResolutionOptionValues.includes("4k") ||
+        !imageResolutionOptionValues.includes("8k")
+      ) {
+        errors.push(
+          'Image Export resolution options must include "2k", "4k", and "8k".',
+        );
+      }
+
+      if (imageResolutionControl.defaultValue !== "4k") {
+        errors.push('Image Export resolution must default to "4k".');
+      }
+    }
+
+    const imageFormatControlId = imageFormatEntry?.[0];
+    const imageResolutionControlId = imageResolutionEntry?.[0];
+    const imageExportHasInlinePair =
+      imageExportSection === undefined ||
+      imageFormatControlId === undefined ||
+      imageResolutionControlId === undefined
+        ? false
+        : sectionHasInlineLayoutGroupForPair(
+            imageExportSection,
+            imageFormatControlId,
+            imageResolutionControlId,
+          );
+
+    if (!imageExportHasInlinePair) {
+      errors.push(
+        "Image Export format and resolution must render as one compact two-column inline row, matching Video Export settings.",
       );
     }
   }

package/templates/ui/components/control-layout/index.tsx

@@ -80,10 +80,10 @@ export function ControlInlineGroup({
   columns?: number;
   kind?: "default" | "slider" | "toggleParameter";
 }): React.JSX.Element {
-  const gridTemplateColumns =
-    kind === "toggleParameter"
-      ? "auto minmax(0, 1fr)"
-      : `repeat(${Math.max(1, Math.floor(columns))}, minmax(0, 1fr))`;
+  const gridTemplateColumns = `repeat(${Math.max(
+    1,
+    Math.floor(columns),
+  )}, minmax(0, 1fr))`;
 
   return (
     <div

package/templates/ui/components/controls/font-picker/font-picker-control.tsx

@@ -127,7 +127,7 @@ const textCaseOptions: Array<{
   label: string;
   value: FontPickerTextCasePreset;
 }> = [
-  { label: "Original", value: "original" },
+  { label: "As typed", value: "original" },
   { label: "Uppercase", value: "uppercase" },
   { label: "Lowercase", value: "lowercase" },
   { label: "Capitalize", value: "capitalize" },

package/toolcraft-skills/brainstorming/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: brainstorming
+description: Use before creating Toolcraft app features, changing behavior, or assembling app specs.
+---
+
+# Toolcraft Brainstorming
+
+Use this skill before changing a Toolcraft generated app spec, behavior, controls,
+canvas output, panels, export behavior, renderer technique, timeline, layers, or
+media flow.
+
+## Process
+
+1. Read the generated app `AGENTS.md` and relevant `docs/toolcraft/*` contract
+   files first.
+2. Identify the product goal, visible output, editable entities, required
+   controls, export behavior, and verification tier.
+3. Make a Control Section Inventory grouped by product entity or workflow stage,
+   not by UI component type.
+4. Decide whether layers, timeline, persistence, settings transfer, custom
+   controls, or a custom renderer are actually required.
+5. Record decisions in `docs/toolcraft/agent-worklog.md`.
+
+## Toolcraft Rule
+
+The local Toolcraft app contract is the source of truth. Do not ask the user to
+confirm decisions already covered by the prompt, `AGENTS.md`, or local
+Toolcraft docs. Continue when the product behavior is clear.

package/toolcraft-skills/browser/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: browser
+description: Use to verify Toolcraft generated apps in a real local browser after implementation.
+---
+
+# Toolcraft Browser Verification
+
+Use this skill after implementing generated app behavior that affects visible UI,
+canvas output, export behavior, upload/media flow, panels, controls, timeline,
+layers, or viewport interactions.
+
+## Process
+
+1. Run the app with `pnpm dev`.
+2. Open the local URL in a real browser.
+3. Verify the product output, canvas backing, controls, panel actions, upload or
+   export flow, responsive layout, and any timeline or layer behavior touched by
+   the change.
+4. For final delivery, run the generated app verification commands required by
+   `AGENTS.md`.
+
+## Toolcraft Rule
+
+Browser verification is part of the Toolcraft contract. A typecheck or build
+alone is not enough for visible app behavior.

package/toolcraft-skills/figma/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: figma
+description: Use when a Toolcraft task includes a Figma URL, node ID, or design-to-code requirement.
+---
+
+# Toolcraft Figma Workflow
+
+Use this skill when the user provides a Figma URL, node ID, or asks to implement
+or match a Figma design.
+
+## Process
+
+1. Inspect the Figma file through the available Figma MCP or design context
+   tooling.
+2. Read actual nodes, layers, components, variables, styles, assets, and layout
+   structure.
+3. Translate the design into Toolcraft schema controls, product renderer output,
+   canvas sizing, export behavior, and verification coverage.
+4. Use screenshots only for final visual QA, not as the source of truth.
+
+## Toolcraft Rule
+
+Do not implement a Figma task from a screenshot or by eye when Figma context is
+available. The Figma structure is the reference.

package/toolcraft-skills/figma-implement-design/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: figma-implement-design
+description: Use to translate inspected Figma structure into a production-ready Toolcraft generated app.
+---
+
+# Toolcraft Figma Implementation
+
+Use this skill after Figma context has been inspected and the task is to build or
+update a Toolcraft generated app from that design.
+
+## Process
+
+1. Map Figma sections, components, and visual entities to product output and
+   schema controls.
+2. Use built-in Toolcraft controls before custom controls.
+3. Keep app UI out of `canvasContent`; render product output there only.
+4. Preserve the Toolcraft runtime canvas backing.
+5. Add acceptance, browser, and performance coverage for every visible product
+   entity.
+
+## Toolcraft Rule
+
+Build through `defineToolcraft` and `ToolcraftApp`. Do not recreate Toolcraft
+panels, toolbar, controls, canvas, layers, or timeline by hand.

package/toolcraft-skills/systematic-debugging/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: systematic-debugging
+description: Use before fixing broken Toolcraft controls, tests, builds, visual mismatches, exports, or runtime regressions.
+---
+
+# Toolcraft Systematic Debugging
+
+Use this skill before fixing any Toolcraft generated app failure.
+
+## Process
+
+1. Reproduce the failure with the smallest command or browser action.
+2. Read the full error, stack trace, failing assertion, or visual mismatch.
+3. Identify whether the root cause is app schema, app renderer, acceptance data,
+   browser test setup, copied runtime source, dependencies, or generated docs.
+4. Compare the failure against the local Toolcraft docs and existing passing
+   patterns in the generated app.
+5. Make one targeted fix and rerun the relevant verification.
+
+## Toolcraft Rule
+
+Fix source behavior in the monorepo runtime or starter when the generated
+template is wrong. Do not patch copied `src/toolcraft` files inside one generated
+app unless the user explicitly wants a local fork.

package/toolcraft-skills/writing-plans/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: writing-plans
+description: Use before Toolcraft code changes once the product behavior or approved spec is clear.
+---
+
+# Toolcraft Writing Plans
+
+Use this skill before editing generated app code from a clear Toolcraft spec or
+user request.
+
+## Plan Content
+
+Write a concise implementation plan that names:
+
+1. Files to change under `src/app`, `src/routes`, docs, tests, or scripts.
+2. Schema controls, sections, panel actions, renderer output, timeline, layers,
+   persistence, settings transfer, and export paths affected by the work.
+3. Acceptance, browser, and performance coverage required by the selected
+   verification tier.
+4. Commands to run before completion.
+
+## Toolcraft Rule
+
+Keep implementation plans focused on app behavior and verification. Do not move
+runtime behavior into route-local state, do not patch copied `src/toolcraft`
+internals for one app, and do not replace built-in Toolcraft surfaces.