@pixel-point/toolcraft 0.0.15 → 0.0.16

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

@@ -13,11 +13,14 @@ import { getToolcraftControlOrderErrors } from "./control-order";
 import { getToolcraftControlSectionInventoryErrors } from "./control-section-inventory";
 import { isToolcraftVisibleAcceptanceControl } from "./controls";
 import { getToolcraftInlineLayoutErrors } from "./inline-layout";
+import { getToolcraftInfinityCanvasCoverageErrors } from "./infinity-canvas";
 import {
   getToolcraftOutputExportErrors,
   schemaHasVideoExportPanelAction,
 } from "./output-export";
+import { getToolcraftOrientationGizmoErrors } from "./orientation-gizmo";
 import { getToolcraftReferenceRuntimeCloneErrors } from "./reference-runtime";
+import { getToolcraftRenderScaleCoverageErrors } from "./render-scale";
 import {
   getToolcraftCanvasSizingCoverageErrors,
   getToolcraftLayerCoverageErrors,
@@ -26,9 +29,11 @@ import {
   getToolcraftTimelinePlaybackCoverageErrors,
 } from "./runtime-coverage";
 import { getToolcraftRuntimeSetupSectionErrors } from "./runtime-setup";
+import { getToolcraftInteractionOwnershipErrors } from "./interaction-ownership";
 import type {
   ToolcraftComponentAcceptance,
   ToolcraftControlSectionInventoryEntry,
+  ToolcraftProductReadiness,
   ToolcraftTransferMode,
   ToolcraftVisibleControl,
 } from "./types";
@@ -40,9 +45,11 @@ import {
   type ToolcraftAcceptanceValidator,
 } from "./validation-pipeline";
 import { getToolcraftVideoReferenceStudyErrors } from "./video-reference-study";
+import { getToolcraftViewInteractionErrors } from "./view-interaction";
 
 export type ToolcraftAcceptanceValidationInput = {
   acceptance: readonly ToolcraftComponentAcceptance[];
+  productReadiness: ToolcraftProductReadiness;
   schema: ResolvedToolcraftAppSchema;
   sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
   transferMode: ToolcraftTransferMode;
@@ -64,11 +71,13 @@ export function collectToolcraftVisibleAcceptanceControls(
 
 function createToolcraftAcceptanceValidationContext({
   acceptance,
+  productReadiness,
   schema,
   sectionInventory,
   transferMode,
 }: {
   acceptance: readonly ToolcraftComponentAcceptance[];
+  productReadiness: ToolcraftProductReadiness;
   schema: ResolvedToolcraftAppSchema;
   sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
   transferMode: ToolcraftTransferMode;
@@ -80,14 +89,37 @@ function createToolcraftAcceptanceValidationContext({
     controls,
     hasVideoExportAction: schemaHasVideoExportPanelAction(schema),
     layersEnabled: Boolean(schema.panels.layers),
+    productReadiness,
     schema,
     sectionInventory,
-    timelineMode: schema.panels.timeline?.enabled ? schema.panels.timeline.mode : null,
+    timelineMode: schema.panels.timeline?.enabled
+      ? schema.panels.timeline.mode
+      : null,
     transferMode,
   };
 }
 
 const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
+  {
+    path: "starterProductReadiness.interactionOwnership",
+    ruleId: "interaction-surface-ownership",
+    validate: ({ acceptance, controls, productReadiness }) =>
+      getToolcraftInteractionOwnershipErrors({
+        acceptance,
+        controls,
+        productReadiness,
+      }),
+  },
+  {
+    path: "starterProductReadiness.viewInteraction",
+    ruleId: "renderer-view-interaction",
+    validate: ({ productReadiness, schema, transferMode }) =>
+      getToolcraftViewInteractionErrors({
+        productReadiness,
+        schema,
+        transferMode,
+      }),
+  },
   {
     path: "schema.panels.controls.setup",
     ruleId: "output-export-required",
@@ -109,6 +141,11 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
     validate: ({ schema, sectionInventory }) =>
       getToolcraftControlSectionInvariantErrors(schema, sectionInventory),
   },
+  {
+    path: "schema.panels.controls.sections[].controls",
+    ruleId: "controls-product-coverage",
+    validate: ({ schema }) => getToolcraftOrientationGizmoErrors(schema),
+  },
   {
     path: "starterControlSectionInventory",
     ruleId: "controls-section-inventory-required",
@@ -124,7 +161,11 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
     path: "schema.export",
     ruleId: "output-export-required",
     validate: ({ controls, hasVideoExportAction, schema }) =>
-      getToolcraftOutputExportErrors({ controls, hasVideoExportAction, schema }),
+      getToolcraftOutputExportErrors({
+        controls,
+        hasVideoExportAction,
+        schema,
+      }),
   },
   {
     path: "starterTransferMode.videoReferenceStudy",
@@ -145,7 +186,12 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
     path: "starterTransferMode.referenceStudy",
     ruleId: "reference-clone-source-of-truth",
     validate: ({ acceptance, schema, timelineMode, transferMode }) =>
-      getToolcraftReferenceRuntimeCloneErrors({ acceptance, schema, timelineMode, transferMode }),
+      getToolcraftReferenceRuntimeCloneErrors({
+        acceptance,
+        schema,
+        timelineMode,
+        transferMode,
+      }),
   },
   {
     path: "acceptance.layerCoverage",
@@ -171,6 +217,22 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
     validate: ({ acceptance, schema }) =>
       getToolcraftCanvasSizingCoverageErrors({ acceptance, schema }),
   },
+  {
+    path: "acceptance.renderScaleCoverage",
+    ruleId: "acceptance-product-observable",
+    validate: ({ acceptance, schema }) =>
+      getToolcraftRenderScaleCoverageErrors({ acceptance, schema }),
+  },
+  {
+    path: "acceptance.infinityCanvasCoverage",
+    ruleId: "infinity-canvas-scene-bounds",
+    validate: ({ acceptance, productReadiness, schema }) =>
+      getToolcraftInfinityCanvasCoverageErrors({
+        acceptance,
+        productReadiness,
+        schema,
+      }),
+  },
   {
     path: "acceptance.persistenceCoverage",
     ruleId: "persistence-policy-explicit",
@@ -180,11 +242,19 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
   {
     path: "acceptance.controls",
     ruleId: "controls-product-coverage",
-    validate: ({ acceptance, controls, layersEnabled, schema, timelineMode }) =>
+    validate: ({
+      acceptance,
+      controls,
+      layersEnabled,
+      productReadiness,
+      schema,
+      timelineMode,
+    }) =>
       getToolcraftControlAcceptanceErrors({
         acceptance,
         controls,
         layersEnabled,
+        productReadiness,
         schema,
         timelineMode,
       }),
@@ -202,6 +272,7 @@ export function validateToolcraftAcceptanceDiagnostics(
 
 export function validateToolcraftAcceptanceCoverage({
   acceptance,
+  productReadiness,
   schema,
   sectionInventory,
   transferMode,
@@ -209,6 +280,7 @@ export function validateToolcraftAcceptanceCoverage({
   return getBlockingToolcraftAcceptanceMessages(
     validateToolcraftAcceptanceDiagnostics({
       acceptance,
+      productReadiness,
       schema,
       sectionInventory,
       transferMode,

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

@@ -1,7 +1,10 @@
 import { describe, expect, it } from "vitest";
 
 import { starterSchema } from "../starter-schema";
-import { starterTransferMode } from "../starter-acceptance-data";
+import {
+  starterProductReadiness,
+  starterTransferMode,
+} from "../starter-acceptance-data";
 import {
   getBlockingToolcraftAcceptanceMessages,
   runToolcraftAcceptanceValidators,
@@ -13,6 +16,7 @@ const context: ToolcraftAcceptanceValidationContext = {
   controls: [],
   hasVideoExportAction: false,
   layersEnabled: false,
+  productReadiness: starterProductReadiness,
   schema: starterSchema,
   sectionInventory: [],
   timelineMode: null,

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

@@ -9,6 +9,7 @@ import { getToolcraftDecisionDiagnosticSeverity } from "@repo/toolcraft-runtime"
 import type {
   ToolcraftComponentAcceptance,
   ToolcraftControlSectionInventoryEntry,
+  ToolcraftProductReadiness,
   ToolcraftTransferMode,
   ToolcraftVisibleControl,
 } from "./types";
@@ -18,6 +19,7 @@ export type ToolcraftAcceptanceValidationContext = {
   controls: readonly ToolcraftVisibleControl[];
   hasVideoExportAction: boolean;
   layersEnabled: boolean;
+  productReadiness: ToolcraftProductReadiness;
   schema: ResolvedToolcraftAppSchema;
   sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
   timelineMode: ToolcraftTimelineMode | null;

package/templates/starter/src/app/acceptance/view-interaction-intent.ts

@@ -0,0 +1,23 @@
+export type ToolcraftViewInteractionEvidenceSource =
+  | "explicit-user-request"
+  | "inspected-reference";
+
+export type ToolcraftViewInteractionIntent =
+  | {
+      mode: "non-spatial";
+      reason: string;
+    }
+  | {
+      mode: "orbit";
+      orientationTargets: readonly string[];
+    }
+  | {
+      evidence: string;
+      mode: "fixed-camera";
+      source: ToolcraftViewInteractionEvidenceSource;
+    }
+  | {
+      evidence: string;
+      mode: "timeline-camera";
+      source: ToolcraftViewInteractionEvidenceSource;
+    };

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

@@ -0,0 +1,148 @@
+import type { ResolvedToolcraftAppSchema } from "@repo/toolcraft-runtime";
+
+import type {
+  ToolcraftProductReadiness,
+  ToolcraftTransferMode,
+  ToolcraftViewInteractionEvidenceSource,
+  ToolcraftViewInteractionIntent,
+} from "./types";
+
+type ToolcraftViewInteractionValidationInput = {
+  productReadiness: ToolcraftProductReadiness;
+  schema: ResolvedToolcraftAppSchema;
+  transferMode: ToolcraftTransferMode;
+};
+
+const viewInteractionEvidenceSources = new Set<ToolcraftViewInteractionEvidenceSource>([
+  "explicit-user-request",
+  "inspected-reference",
+]);
+
+function collectOrientationTargets(schema: ResolvedToolcraftAppSchema): string[] {
+  return (schema.panels.controls?.sections ?? []).flatMap((section) =>
+    Object.values(section.controls).flatMap((control) =>
+      control.type === "orientationGizmo" ? [control.target] : [],
+    ),
+  );
+}
+
+function getEvidenceErrors({
+  evidence,
+  mode,
+  source,
+}: Extract<
+  ToolcraftViewInteractionIntent,
+  { mode: "fixed-camera" | "timeline-camera" }
+>): string[] {
+  const errors: string[] = [];
+
+  if (evidence.trim().length === 0) {
+    errors.push(
+      `${mode} evidence must be non-empty and identify the explicit request or inspected reference that owns the camera behavior.`,
+    );
+  }
+
+  if (!viewInteractionEvidenceSources.has(source)) {
+    errors.push(
+      `${mode} source must be explicit-user-request or inspected-reference; an agent-authored fixed camera is not an accepted default.`,
+    );
+  }
+
+  return errors;
+}
+
+export function getToolcraftViewInteractionErrors({
+  productReadiness,
+  schema,
+  transferMode,
+}: ToolcraftViewInteractionValidationInput): string[] {
+  if (productReadiness.mode !== "product") {
+    return [];
+  }
+
+  const intent = productReadiness.viewInteraction;
+
+  if (!intent) {
+    return [
+      "Product readiness must declare viewInteraction before controls or renderer code so spatial scenes cannot silently default to a fixed camera.",
+    ];
+  }
+
+  const schemaTargets = collectOrientationTargets(schema);
+  const errors: string[] = [];
+
+  if (intent.mode === "orbit") {
+    const normalizedIntentTargets = intent.orientationTargets.map((target) =>
+      target.trim(),
+    );
+    const uniqueIntentTargets = new Set(normalizedIntentTargets);
+
+    if (
+      normalizedIntentTargets.length === 0 ||
+      normalizedIntentTargets.some((target) => target.length === 0)
+    ) {
+      errors.push(
+        "orbit viewInteraction must list at least one non-empty orientation target.",
+      );
+    }
+
+    if (uniqueIntentTargets.size !== normalizedIntentTargets.length) {
+      errors.push("orbit orientationTargets must be unique.");
+    }
+
+    for (const target of uniqueIntentTargets) {
+      if (target.length > 0 && !schemaTargets.includes(target)) {
+        errors.push(
+          `orbit target "${target}" requires a matching orientationGizmo schema control.`,
+        );
+      }
+    }
+
+    for (const target of new Set(schemaTargets)) {
+      if (!uniqueIntentTargets.has(target)) {
+        errors.push(
+          `orientationGizmo target "${target}" is missing from orbit orientationTargets.`,
+        );
+      }
+    }
+
+    return errors;
+  }
+
+  if (schemaTargets.length > 0) {
+    errors.push(
+      `${intent.mode} viewInteraction cannot declare orientationGizmo controls; use orbit intent or remove direct 3D orientation UI.`,
+    );
+  }
+
+  if (intent.mode === "non-spatial") {
+    if (intent.reason.trim().length === 0) {
+      errors.push(
+        "non-spatial viewInteraction reason must explain why the product has no visible three-dimensional scene or model.",
+      );
+    }
+
+    return errors;
+  }
+
+  errors.push(...getEvidenceErrors(intent));
+
+  if (intent.mode === "timeline-camera") {
+    const animationMode = transferMode.animationIntent?.mode ?? "none";
+
+    if (
+      animationMode !== "timeline-playback" &&
+      animationMode !== "timeline-keyframes"
+    ) {
+      errors.push(
+        "timeline-camera requires timeline-playback or timeline-keyframes animation intent.",
+      );
+    }
+
+    if (!schema.panels.timeline?.enabled) {
+      errors.push("timeline-camera requires an enabled Toolcraft timeline.");
+    }
+  }
+
+  return errors;
+}

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

@@ -4,6 +4,12 @@ import type {
   ToolcraftProductReadiness,
   ToolcraftTransferMode,
 } from "./acceptance/types";
+import { starterSchema } from "./starter-schema";
+
+const starterPersistenceSlices =
+  starterSchema.persistence.storage === "localStorage"
+    ? starterSchema.persistence.include
+    : [];
 
 export const starterTransferMode: ToolcraftTransferMode = {
   animationIntent: { mode: "none" },
@@ -16,6 +22,27 @@ export const starterProductReadiness: ToolcraftProductReadiness = {
     "Neutral Toolcraft template before a product schema, renderer, and acceptance matrix are authored.",
 };
 
-export const starterAcceptance: readonly ToolcraftComponentAcceptance[] = [];
+export const starterAcceptance: readonly ToolcraftComponentAcceptance[] = [
+  {
+    automated: true,
+    automatedTestName:
+      "declares production reload coverage for the starter schema",
+    browser: true,
+    browserTestName:
+      "browser: app restores exact canvas, values, and panel workspace slices after reload",
+    componentType: "persistence",
+    evidence: "persistence-state",
+    expectedObservable:
+      "Canvas size and zoom, their runtime values, and the moved and collapsed Controls workspace remain visibly restored after a real browser reload.",
+    fixture: "starter runtime persisted workspace",
+    id: "persistence.reload",
+    kind: "runtime",
+    persistenceCoverage: "reload",
+    persistenceSlices: starterPersistenceSlices,
+    target: "canvas.size.width",
+    userAction: "Edit Canvas width and zoom, move and collapse Controls, wait for persistence, and reload the page.",
+  },
+];
 
+// Product entries use the same explicit stable section IDs as starterSchema.
 export const starterControlSectionInventory: readonly ToolcraftControlSectionInventoryEntry[] = [];

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

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { defineToolcraft } from "@repo/toolcraft-runtime";
 
 import {
   contractSchemaFixture,
+  defineContractSchemaFixture,
   validateContractAcceptance,
   validateContractAcceptanceDiagnostics,
 } from "./starter-acceptance.contract-fixtures";
@@ -45,6 +45,7 @@ describe("starter acceptance animation intent contract", () => {
                   type: "actions",
                 },
               },
+              id: "run",
               title: "Run",
             },
           ],
@@ -114,6 +115,7 @@ describe("starter acceptance animation intent contract", () => {
                   type: "switch",
                 },
               },
+              id: "animation",
               title: "Animation",
             },
           ],
@@ -169,6 +171,7 @@ describe("starter acceptance animation intent contract", () => {
                   unit: "%",
                 },
               },
+              id: "animation",
               title: "Animation",
             },
           ],
@@ -196,7 +199,7 @@ describe("starter acceptance animation intent contract", () => {
   });
 
   it("accepts explicit autonomous animation intent for decorative self-running output", () => {
-    const schemaWithAutonomousAnimation = defineToolcraft({
+    const schemaWithAutonomousAnimation = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -256,7 +259,7 @@ describe("starter acceptance animation intent contract", () => {
   });
 
   it("requires a top timeline when video export exists", () => {
-    const schemaWithVideoExportWithoutTimeline = defineToolcraft({
+    const schemaWithVideoExportWithoutTimeline = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -297,7 +300,7 @@ describe("starter acceptance animation intent contract", () => {
   });
 
   it("rejects autonomous animation intent when video export exists", () => {
-    const schemaWithAutonomousVideoExport = defineToolcraft({
+    const schemaWithAutonomousVideoExport = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },

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

@@ -1,7 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { defineToolcraft } from "@repo/toolcraft-runtime";
 
-import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import { defineContractSchemaFixture, validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
 import {
   makeBackgroundSection,
   makeImageExportSection,
@@ -10,7 +9,7 @@ import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 
 describe("Toolcraft background export acceptance contract", () => {
   it("requires png export apps to expose background color and png background toggle controls", () => {
-    const schemaWithoutBackgroundControls = defineToolcraft({
+    const schemaWithoutBackgroundControls = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -65,13 +64,15 @@ describe("Toolcraft background export acceptance contract", () => {
     ).toEqual(
       expect.arrayContaining([
         expect.stringContaining("must expose a user-facing background color control"),
-        expect.stringContaining('must expose export.includeBackground inside the required "Background" section'),
+        expect.stringContaining(
+          "must expose export.includeBackground in runtime Setup",
+        ),
       ]),
     );
   });
 
   it("rejects legacy output sections that mix background controls with export actions", () => {
-    const schemaWithLegacyBackgroundControls = defineToolcraft({
+    const schemaWithLegacyBackgroundControls = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -139,19 +140,18 @@ describe("Toolcraft background export acceptance contract", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        expect.stringContaining('separate controls section titled "Background"'),
         expect.stringContaining(
-          'The "Background" section must contain export.includeBackground as the Include switch.',
+          "Runtime Setup must contain export.includeBackground as the Background switch.",
         ),
         expect.stringContaining(
-          'The "Background" section must contain the renderer-owned background color control',
+          "Runtime Setup must contain the renderer-owned background color control",
         ),
       ]),
     );
   });
 
   it("accepts png export apps that wire background controls into the schema", () => {
-    const schemaWithBackgroundControls = defineToolcraft({
+    const schemaWithBackgroundControls = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -192,6 +192,7 @@ describe("Toolcraft background export acceptance contract", () => {
           backgroundOutputCoverage: [
             "preview-hidden-when-excluded",
             "image-transparent-when-excluded",
+            "infinity-viewport-color-and-dependency",
           ],
           expectedObservable: "Переключатель изменяет фон предпросмотра и растрового результата.",
           userAction: "Отключить фон и проверить оба результата.",
@@ -209,7 +210,7 @@ describe("Toolcraft background export acceptance contract", () => {
           id: "actions.output",
           kind: "control",
           target: "actions.output",
-          userAction: "Toggle Include background, change Background, then click Export PNG.",
+          userAction: "Toggle Background, change Color, then click Export PNG.",
         },
       ],
     });
@@ -217,13 +218,15 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(errors).not.toEqual(
       expect.arrayContaining([
         expect.stringContaining("must expose a user-facing background color control"),
-        expect.stringContaining('must expose export.includeBackground inside the required "Background" section'),
+        expect.stringContaining(
+          "must expose export.includeBackground in runtime Setup",
+        ),
       ]),
     );
   });
 
   it("requires include-background acceptance to hide preview background and keep video background", () => {
-    const schemaWithBackgroundControls = defineToolcraft({
+    const schemaWithBackgroundControls = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },
@@ -275,7 +278,7 @@ describe("Toolcraft background export acceptance contract", () => {
             id: "actions.output",
             kind: "control",
             target: "actions.output",
-            userAction: "Toggle Include background, change Background, then click Export PNG.",
+            userAction: "Toggle Background, change Color, then click Export PNG.",
           },
         ],
       }),
@@ -289,7 +292,7 @@ describe("Toolcraft background export acceptance contract", () => {
   });
 
   it("requires video background coverage only when video export is present", () => {
-    const schemaWithVideoExport = defineToolcraft({
+    const schemaWithVideoExport = defineContractSchemaFixture({
       canvas: {
         enabled: true,
         sizing: { mode: "editable-output" },

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

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   starterAcceptance,
   starterControlSectionInventory,
+  starterProductReadiness,
   starterTransferMode,
   validateProductAcceptanceCoverage,
   validateToolcraftAcceptanceCoverage,
@@ -20,10 +21,12 @@ describe("Toolcraft starter base acceptance coverage", () => {
     const clonedAcceptance = structuredClone(starterAcceptance);
     const clonedTransferMode = structuredClone(starterTransferMode);
     const clonedSectionInventory = structuredClone(starterControlSectionInventory);
+    const clonedProductReadiness = structuredClone(starterProductReadiness);
 
     expect(
       validateToolcraftAcceptanceCoverage({
         acceptance: clonedAcceptance,
+        productReadiness: clonedProductReadiness,
         schema: clonedSchema,
         sectionInventory: clonedSectionInventory,
         transferMode: clonedTransferMode,