@pixel-point/toolcraft 0.0.17 → 0.0.18

package/templates/runtime/contracts/decision-contracts.ts

@@ -58,7 +58,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     area: "runtime-shell",
     currentConstraint: "Apps must assemble through defineToolcraft and ToolcraftApp.",
     desiredBehavior:
-      "Generated apps use the Toolcraft runtime shell and keep product-specific rendering inside supported extension points: schema controls, canvasContent product output, controlRenderers for true custom controls, one shared ToolcraftAppComposition.exportRenderer for typed image/video actions, ToolcraftApp onPanelAction for non-export product actions, and runtime commands. App-specific code must not import or render low-level runtime surfaces or built-in control components directly, instantiate encoders, or own artifact download mechanics.",
+      "Generated apps use the Toolcraft runtime shell and keep product-specific rendering inside supported extension points: schema controls, bounded canvasContent product output, editor-only full-viewport infiniteCanvasContent product output, controlRenderers for true custom controls, one shared ToolcraftAppComposition.exportRenderer for typed image/video actions, ToolcraftApp onPanelAction for non-export product actions, and runtime commands. App-specific code must not import or render low-level runtime surfaces or built-in control components directly, instantiate encoders, or own artifact download mechanics.",
     enforcement: [
       "cli-integrity-check",
       "acceptance-validator",
@@ -87,7 +87,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "The Toolcraft canvas shell owns the visible workspace backing behind product output.",
     desiredBehavior:
-      "Generated apps preserve the runtime canvas surface and do not replace or hide it when product renderers customize their own background. In infinite mode the shell fills the complete viewport with the selected standard Background color, while bounded product background pixels remain suppressed.",
+      "Generated apps preserve the runtime canvas surface and do not replace or hide it when product renderers customize their own background. In infinite mode the shell fills the complete viewport with the selected standard Background color, while bounded product background pixels remain suppressed. Preview-only product environments may layer through infiniteCanvasContent across the complete viewport under the transformed world; that layer is pointer-transparent and excluded from scene bounds and export.",
     enforcement: ["browser-helper", "starter-agents", "spec-checklist"],
     id: "canvas-surface-preserved",
     level: "invariant",
@@ -99,7 +99,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Editable output can switch from a finite artboard to an unbounded workspace, but product renderers and export actions still need one canonical world-space frame contract.",
     desiredBehavior:
-      "Editable-output apps expose one runtime-owned Infinity canvas mode. Enabling it removes finite artboard clipping and size controls while preserving the dormant finite canvas size for exact restoration. When the standard Background pair exists, its selected color fills the complete infinite viewport and Background off atomically resolves finite mode and disables Infinity. Runtime image and model assets retain explicit world-space frames. ToolcraftAppComposition.sceneBoundsProvider supplies product-renderer bounds for one exact state through one direct composition boundary; image export resolves the current frame and video export unions every state from the runtime-owned timestamp schedule. Hidden layers, suppressed default consumers, and editor-only UI do not expand output bounds. Finite mode continues to export the full finite canvas size, while empty, unavailable, and unsafe oversized infinite exports return typed visible failures.",
+      "Editable-output apps expose one runtime-owned Infinity canvas mode. Enabling it removes finite artboard clipping and size controls while preserving the dormant finite canvas size for exact restoration. When the standard Background pair exists, its selected color fills the complete infinite viewport and Background off atomically resolves finite mode and disables Infinity. Runtime image and model assets retain explicit world-space frames. ToolcraftAppComposition.sceneBoundsProvider supplies product-renderer bounds for one exact state through one direct composition boundary. Runtime applies that same product frame to the live infinite preview, and custom raster/WebGL renderers consume useToolcraftProductSceneFrame for backing size and world-to-local translation instead of the dormant finite canvas size. ToolcraftAppComposition.infiniteCanvasContent is reserved for preview-only product environments that fill the complete Infinity viewport without world transforms, pointer input, scene-bounds participation, or export inclusion. Image export resolves the current frame and video export unions every state from the runtime-owned timestamp schedule. Hidden layers, suppressed default consumers, viewport environments, and editor-only UI do not expand preview or output bounds. Finite preview and export remain the full finite canvas and do not call the provider, while empty, unavailable, and unsafe oversized infinite exports return typed visible failures.",
     enforcement: [
       "acceptance-validator",
       "browser-helper",
@@ -203,9 +203,9 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "controls",
     currentConstraint:
-      "Every visible schema control must bind to runtime state, reset from schema defaults, and have acceptance and browser coverage.",
+      "Every product control explicitly declares always or conditional applicability; every visible finite sibling branch binds to runtime state, resets from schema defaults, and passes its accepted browser outcome.",
     desiredBehavior:
-      "Controls are not decorative; each visible control proves its product responsibility through runtime and output observables.",
+      "Non-applicable controls are absent with values preserved, and no always or conditional control remains visible in a finite product branch where its value is ignored.",
     enforcement: ["acceptance-validator", "browser-helper"],
     id: "controls-product-coverage",
     level: "invariant",
@@ -215,13 +215,13 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "controls",
     currentConstraint:
-      "Product-output apps expose final output delivery through sticky footer panelActions.",
+      "Product artifact delivery must match the required productReadiness.exportIntent declaration.",
     desiredBehavior:
-      'Product apps include Export PNG plus an "Image Export" section for format and 2K/4K/8K resolution. Apps whose requested delivery includes animation also include Export Video plus "Video Export" settings; a playback or keyframe timeline may exist for interactive preview without inventing video delivery. Copy can be secondary, but it does not replace export. Product apps declare the standard background pair and runtime places it in Setup: Background beside Infinity canvas, Color below, and Timeline last. One shared product exportRenderer draws deterministic scene-coordinate frames; runtime owns settings, scene crop, PNG/JPEG/video background semantics, visible runtime media/model composition, exact timestamped encoding, download, progress, and typed failures.',
+      'Every product declares productReadiness.exportIntent. Image export starts as the Toolcraft default and is removed only with explicit user-removal evidence; video export requires explicit user request evidence. Animation, playback, keyframes, or timeline presence never changes artifact delivery intent. Resolved intent capabilities correspond exactly to schema actions, settings sections, and acceptance coverage: image-only, image-plus-video, video-only, and explicit no-export products expose only the runtime-owned artifact surfaces their intent enables. Product apps declare the standard background pair and runtime places it in Setup: Background beside Infinity canvas, Color below, and Timeline last. One shared product exportRenderer draws deterministic scene-coordinate frames for enabled artifact types; runtime owns settings, scene crop, PNG/JPEG/video background semantics, visible runtime media/model composition, exact timestamped encoding, download, progress, and typed failures.',
     enforcement: ["acceptance-validator", "performance-validator", "browser-helper", "starter-agents"],
     id: "output-export-required",
     level: "invariant",
-    title: "Product output always has export",
+    title: "Product output follows artifact export intent",
     verdict: "move-to-validator",
   },
   {
@@ -229,7 +229,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Every product controls section must be represented in the exported Control Section Inventory before schema authoring.",
     desiredBehavior:
-      "Generated product apps publish a typed Control Section Inventory with section title, product entity or workflow stage, exact targets, and a concrete grouping reason so section ownership is machine-checkable without prescribing the final product layout.",
+      "Generated product apps publish a typed Control Section Inventory with stable entityId, human-readable entity, exact targets, and a concrete grouping reason. One entity stays in one section through ten controls; larger entities use balanced two-to-ten-control workflow stages with explicit split evidence, so section ownership and reset boundaries are machine-checkable without runtime rewriting.",
     enforcement: ["acceptance-validator", "docs", "starter-agents", "spec-checklist"],
     id: "controls-section-inventory-required",
     level: "invariant",
@@ -253,7 +253,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Labels, color placement, section grouping, selector order, and inline density need product-aware decisions.",
     desiredBehavior:
-      "Given a valid Control Section Inventory, ordering, section cohesion, labels, color placement, and compact density remain product-aware recommendations. Validators report questionable grouping without rejecting a coherent product-specific choice solely because it differs from a preferred heuristic.",
+      "Given a valid Control Section Inventory, ordering, labels, color placement, and compact density remain product-aware recommendations. The ten-control maximum and entity cohesion are inventory invariants; heuristics may report questionable presentation without rejecting a coherent product-specific choice solely because it differs from a preferred layout.",
     enforcement: ["acceptance-validator", "schema-normalization", "docs", "starter-agents"],
     id: "controls-layout-heuristics",
     level: "heuristic",

package/templates/runtime/export/export-background.ts

@@ -1,29 +1,10 @@
-import type { ResolvedToolcraftAppSchema } from "../schema/types";
 import type { ToolcraftState } from "../state/types";
 
-export type ToolcraftExportFormat = "png" | "video";
-
-export type ToolcraftExportBackgroundOptions = {
-  format: ToolcraftExportFormat;
-  schema: ResolvedToolcraftAppSchema;
-};
-
 export type ToolcraftPreviewBackgroundOptions = {
   includeBackgroundTarget?: string;
   state: ToolcraftState;
 };
 
-export function shouldIncludeToolcraftExportBackground({
-  format,
-  schema,
-}: ToolcraftExportBackgroundOptions): boolean {
-  if (format === "video") {
-    return true;
-  }
-
-  return schema.export.png.background !== "transparent";
-}
-
 export function shouldIncludeToolcraftPreviewBackground({
   includeBackgroundTarget = "export.includeBackground",
   state,

package/templates/runtime/export/export.test.ts

@@ -1,9 +1,18 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
 
+import * as toolcraftRuntimeRoot from "../index";
 import { defineToolcraft } from "../schema/define-toolcraft";
 import type { ToolcraftState } from "../state/types";
+import type {
+  ToolcraftArtifactSize,
+  ToolcraftExportFrame,
+  ToolcraftPreviewBackgroundOptions,
+  ToolcraftProductExportFrameContext,
+  ToolcraftProductExportFrameRenderer,
+  ToolcraftProductExportRenderer,
+  ToolcraftRetinaExportSize,
+} from "../index";
 import {
-  shouldIncludeToolcraftExportBackground,
   shouldIncludeToolcraftPreviewBackground,
 } from "./export-background";
 import {
@@ -50,29 +59,41 @@ function createState(schema = defineToolcraft({ canvas: { enabled: true }, panel
 }
 
 describe("Toolcraft export helpers", () => {
-  it("normalizes png export background to include by default", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      panels: {},
+  it("keeps the runtime root limited to product-safe export primitives", () => {
+    expect(toolcraftRuntimeRoot).toMatchObject({
+      getToolcraftImageExportSize: expect.any(Function),
+      getToolcraftRetinaExportPixelRatio: expect.any(Function),
+      getToolcraftRetinaExportSize: expect.any(Function),
+      getToolcraftVideoExportSize: expect.any(Function),
+      shouldIncludeToolcraftPreviewBackground: expect.any(Function),
+      TOOLCRAFT_MAX_EXPORT_EDGE_PX: 8192,
+      TOOLCRAFT_MAX_EXPORT_PIXELS: 8192 * 8192,
+      toolcraftImageExportFormatTarget: "export.image.format",
+      toolcraftImageExportResolutionTarget: "export.image.resolution",
+      toolcraftVideoExportFormatTarget: "export.video.format",
+      toolcraftVideoExportResolutionTarget: "export.video.resolution",
+      validateToolcraftArtifactSize: expect.any(Function),
     });
-
-    expect(schema.export.png.background).toBe("include");
-  });
-
-  it("preserves transparent png export background option", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
-
-    expect(schema.export.png.background).toBe("transparent");
-    expect(shouldIncludeToolcraftExportBackground({ format: "png", schema })).toBe(false);
-    expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
+    expect(toolcraftRuntimeRoot).not.toHaveProperty("exportToolcraftImageArtifact");
+    expect(toolcraftRuntimeRoot).not.toHaveProperty("exportToolcraftVideoArtifact");
+    expect(toolcraftRuntimeRoot).not.toHaveProperty(
+      "createToolcraftVideoEncoderBackend",
+    );
+    expect(toolcraftRuntimeRoot).not.toHaveProperty(
+      "createToolcraftVideoFrameSchedule",
+    );
+
+    expectTypeOf<ToolcraftArtifactSize>().toMatchTypeOf<
+      Readonly<{ height: number; width: number }>
+    >();
+    expectTypeOf<ToolcraftExportFrame>().toMatchTypeOf<
+      Readonly<{ height: number; width: number; x: number; y: number }>
+    >();
+    expectTypeOf<ToolcraftPreviewBackgroundOptions>().toHaveProperty("state");
+    expectTypeOf<ToolcraftProductExportFrameContext>().toHaveProperty("frame");
+    expectTypeOf<ToolcraftProductExportFrameRenderer>().toBeFunction();
+    expectTypeOf<ToolcraftProductExportRenderer>().toHaveProperty("renderFrame");
+    expectTypeOf<ToolcraftRetinaExportSize>().toHaveProperty("pixelRatio");
   });
 
   it("uses include-background runtime state for live preview background", () => {
@@ -103,24 +124,6 @@ describe("Toolcraft export helpers", () => {
     expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(true);
   });
 
-  it("keeps video export background independent from preview include state", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
-    const state = createState(schema);
-
-    state.values["export.includeBackground"] = false;
-
-    expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(false);
-    expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
-  });
-
   it("uses at least 2x pixel ratio for retina export", () => {
     expect(getToolcraftRetinaExportPixelRatio(1)).toBe(2);
     expect(getToolcraftRetinaExportPixelRatio(1.5)).toBe(2);

package/templates/runtime/export/index.ts

@@ -1,16 +1,44 @@
-export * from "./artifact-export-settings";
-export * from "./artifact-export-request";
-export * from "./artifact-download";
-export * from "./artifact-frame-renderer";
-export * from "./artifact-scene-frame";
-export * from "./artifact-frame-state";
-export * from "./export-error";
-export * from "./export-background";
-export * from "./export-frame";
-export * from "./export-sizing";
-export * from "./image-artifact-export";
-export * from "./product-export-renderer";
-export * from "./video-artifact-export";
-export * from "./video-encoding-backend";
-export * from "./video-encoding-policy";
-export * from "./video-frame-schedule";
+export {
+  toolcraftImageExportFormatTarget,
+  toolcraftImageExportResolutionTarget,
+  toolcraftVideoExportFormatTarget,
+  toolcraftVideoExportResolutionTarget,
+} from "./artifact-export-settings";
+export type {
+  ToolcraftImageExportFormat,
+  ToolcraftImageExportPresetResolution,
+  ToolcraftResolvedImageExportSettings,
+  ToolcraftResolvedVideoExportSettings,
+  ToolcraftVideoExportFormat,
+  ToolcraftVideoExportPresetResolution,
+} from "./artifact-export-settings";
+export { shouldIncludeToolcraftPreviewBackground } from "./export-background";
+export type { ToolcraftPreviewBackgroundOptions } from "./export-background";
+export {
+  TOOLCRAFT_MAX_EXPORT_EDGE_PX,
+  TOOLCRAFT_MAX_EXPORT_PIXELS,
+  validateToolcraftArtifactSize,
+} from "./export-frame";
+export type {
+  ToolcraftArtifactSize,
+  ToolcraftExportFrame,
+} from "./export-frame";
+export {
+  getToolcraftImageExportSize,
+  getToolcraftRetinaExportPixelRatio,
+  getToolcraftRetinaExportSize,
+  getToolcraftVideoExportSize,
+} from "./export-sizing";
+export type {
+  ToolcraftExportSizeOptions,
+  ToolcraftImageExportResolution,
+  ToolcraftImageExportSizeOptions,
+  ToolcraftRetinaExportSize,
+  ToolcraftVideoExportResolution,
+  ToolcraftVideoExportSizeOptions,
+} from "./export-sizing";
+export type {
+  ToolcraftProductExportFrameContext,
+  ToolcraftProductExportFrameRenderer,
+  ToolcraftProductExportRenderer,
+} from "./product-export-renderer";

package/templates/runtime/index.ts

@@ -13,6 +13,8 @@ export type {
 } from "./react/model-rendering/model-render-binding";
 export * from "./schema/define-toolcraft";
 export { TOOLCRAFT_CANVAS_RENDER_SCALE } from "./schema/canvas-render-scale";
+export * from "./schema/collection-item-controls";
+export * from "./schema/control-applicability";
 export * from "./schema/keyframe-capability";
 export * from "./schema/runtime-targets";
 export * from "./schema/types";

package/templates/runtime/model-import/model-import-limits.ts

@@ -1,5 +1,4 @@
 import type {
-  ResolvedToolcraftModelFileDropSchema,
   ToolcraftModelFormat,
   ToolcraftModelFileDropSchema,
   ToolcraftModelImportLimits,
@@ -143,9 +142,21 @@ function normalizeTopologyProfile(
   return normalizedProfile;
 }
 
-export function normalizeToolcraftModelFileDrop(
-  control: ToolcraftModelFileDropSchema,
-): ResolvedToolcraftModelFileDropSchema {
+type NormalizedToolcraftModelFileDropSchema<
+  TControl extends ToolcraftModelFileDropSchema,
+> = Omit<
+  TControl,
+  "modelFormats" | "modelLimits" | "multiple" | "topologyProfile"
+> & {
+  modelFormats: readonly ToolcraftModelFormat[];
+  modelLimits: ToolcraftModelImportLimits;
+  multiple: false;
+  topologyProfile: ToolcraftModelTopologyProfile;
+};
+
+export function normalizeToolcraftModelFileDrop<
+  TControl extends ToolcraftModelFileDropSchema,
+>(control: TControl): NormalizedToolcraftModelFileDropSchema<TControl> {
   const multiple: unknown = control.multiple;
 
   if (multiple !== undefined && multiple !== false) {

package/templates/runtime/react/app-shell/runtime-public-api.test.tsx

@@ -9,6 +9,7 @@ import * as ToolcraftReact from "../index";
 import {
   isToolcraftLayerVisibleInTree,
   useToolcraftMediaPresentationUrls,
+  useToolcraftProductSceneFrame,
 } from "../index";
 import { CanvasShell } from "../canvas/canvas-shell";
 import { ControlsPanel } from "../controls-panel/controls-panel";
@@ -53,6 +54,10 @@ describe("Toolcraft template runtime public API", () => {
       isToolcraftLayerVisibleInTree,
     );
     expect(isToolcraftLayerVisibleInTree).toEqual(expect.any(Function));
+    expect(ToolcraftReact.useToolcraftProductSceneFrame).toBe(
+      useToolcraftProductSceneFrame,
+    );
+    expect(useToolcraftProductSceneFrame).toEqual(expect.any(Function));
     expect(ToolcraftReact).not.toHaveProperty("ToolcraftStoreContext");
     expect(ToolcraftReact).not.toHaveProperty("useToolcraftStore");
   });
@@ -71,6 +76,7 @@ describe("Toolcraft template runtime public API", () => {
       | "canvasContent"
       | "controlRenderers"
       | "exportRenderer"
+      | "infiniteCanvasContent"
       | "modelPresentation"
       | "onPanelAction"
       | "renderDefaultCanvasMedia"
@@ -85,6 +91,7 @@ describe("Toolcraft template runtime public API", () => {
       | "className"
       | "controlRenderers"
       | "exportRenderer"
+      | "infiniteCanvasContent"
       | "modelPresentation"
       | "onPanelAction"
       | "renderDefaultCanvasMedia"
@@ -153,7 +160,9 @@ describe("Toolcraft template runtime public API", () => {
   it("keeps shell and panel host props separate", () => {
     expectTypeOf<
       keyof React.ComponentProps<typeof CanvasShell>
-    >().toEqualTypeOf<"children" | "renderDefaultMedia">();
+    >().toEqualTypeOf<
+      "children" | "infiniteCanvasContent" | "renderDefaultMedia"
+    >();
     expectTypeOf<React.ComponentProps<typeof PanelHost>>().toHaveProperty(
       "panelType",
     );
@@ -211,6 +220,7 @@ describe("Toolcraft template runtime public API", () => {
     };
     const canvasWithSlotProps: React.ComponentProps<typeof CanvasShell> = {
       children: <div />,
+      infiniteCanvasContent: <div />,
       renderDefaultMedia: false,
     };
     // @ts-expect-error Canvas upload belongs to schema.canvas.upload.

package/templates/runtime/react/app-shell/toolcraft-app.scene-export.test.tsx

@@ -10,6 +10,35 @@ afterEach(() => {
 });
 
 describe("ToolcraftApp scene export boundary", () => {
+  it("applies composition scene bounds to the live infinite product surface", () => {
+    const schema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 180, unit: "px", width: 320 },
+        sizing: { defaultMode: "infinite", mode: "editable-output" },
+      },
+      panels: {},
+      persistence: { storage: "none" },
+    });
+    const { container } = render(
+      <ToolcraftApp
+        canvasContent={<div data-testid="product-scene" />}
+        sceneBoundsProvider={() => [
+          { height: 240, width: 400, x: -200, y: -120 },
+        ]}
+        schema={schema}
+      />,
+    );
+    const productScene = container.querySelector<HTMLElement>(
+      "[data-toolcraft-product-scene]",
+    );
+
+    expect(productScene?.style.height).toBe("240px");
+    expect(productScene?.style.left).toBe("-200px");
+    expect(productScene?.style.top).toBe("-120px");
+    expect(productScene?.style.width).toBe("400px");
+  });
+
   it("fails before mount when a typed product export has no shared renderer", () => {
     const schema = defineToolcraft({
       canvas: {

package/templates/runtime/react/app-shell/toolcraft-app.tsx

@@ -12,8 +12,9 @@ import type { ToolcraftState } from "../../state/types";
 import {
   getToolcraftExportRendererCoverageErrors,
   type ToolcraftProductExportRenderer,
-} from "../../export";
+} from "../../export/product-export-renderer";
 import { CanvasShell } from "../canvas/canvas-shell";
+import { ToolcraftProductSceneBoundsBoundary } from "../canvas/product-scene-surface";
 import {
   ControlsPanel,
   type ToolcraftPanelActionHandler,
@@ -33,6 +34,7 @@ export type ToolcraftAppComposition = {
   canvasContent?: React.ReactNode;
   controlRenderers?: ToolcraftControlRendererMap;
   exportRenderer?: ToolcraftProductExportRenderer;
+  infiniteCanvasContent?: React.ReactNode;
   modelPresentation?: ToolcraftModelPresentationMode;
   onPanelAction?: ToolcraftPanelActionHandler;
   renderDefaultCanvasMedia?: boolean;
@@ -61,6 +63,7 @@ function ToolcraftAppContent({
   canvasContent,
   className,
   controlRenderers,
+  infiniteCanvasContent,
   onPanelAction,
   renderDefaultCanvasMedia = true,
   sceneExport,
@@ -100,7 +103,10 @@ function ToolcraftAppContent({
       }}
     >
       {surfaces.canvas.enabled ? (
-        <CanvasShell renderDefaultMedia={renderDefaultCanvasMedia}>
+        <CanvasShell
+          infiniteCanvasContent={infiniteCanvasContent}
+          renderDefaultMedia={renderDefaultCanvasMedia}
+        >
           {canvasContent}
         </CanvasShell>
       ) : null}
@@ -168,12 +174,16 @@ export function ToolcraftApp({
       rendererPipelineRegistration={rendererPipelineRegistration}
       schema={schema}
     >
-      <ToolcraftAppContent
-        {...props}
-        canvasContent={canvasContent}
-        renderDefaultCanvasMedia={renderDefaultCanvasMedia}
-        sceneExport={sceneExport}
-      />
+      <ToolcraftProductSceneBoundsBoundary
+        boundsProvider={sceneBoundsProvider}
+      >
+        <ToolcraftAppContent
+          {...props}
+          canvasContent={canvasContent}
+          renderDefaultCanvasMedia={renderDefaultCanvasMedia}
+          sceneExport={sceneExport}
+        />
+      </ToolcraftProductSceneBoundsBoundary>
     </ToolcraftRoot>
   );
 }

package/templates/runtime/react/canvas/canvas-shell-rendering.test.tsx

@@ -8,12 +8,49 @@ import {
   createUploadDefaultSchema,
   renderCanvasShell,
 } from "./canvas-shell-test-utils";
+import { useToolcraftProductSceneFrame } from "./product-scene-surface";
 
 afterEach(() => {
   cleanup();
 });
 
 describe("CanvasShell rendering", () => {
+  it("uses product bounds as the live infinite preview frame", () => {
+    function ProductFrameProbe(): React.JSX.Element {
+      const frame = useToolcraftProductSceneFrame();
+      return <output data-testid="product-frame">{JSON.stringify(frame)}</output>;
+    }
+
+    const { container } = renderCanvasShell({
+      children: <ProductFrameProbe />,
+      initialState: {
+        canvas: {
+          mode: "infinite",
+          offset: { x: 0, y: 0 },
+          size: { height: 200, unit: "px", width: 300 },
+          zoom: 100,
+        },
+      },
+      productSceneBoundsProvider: () => [
+        { height: 260, width: 420, x: -210, y: -130 },
+      ],
+    });
+    const productScene = container.querySelector<HTMLElement>(
+      "[data-toolcraft-product-scene]",
+    );
+
+    expect(productScene?.style.height).toBe("260px");
+    expect(productScene?.style.left).toBe("-210px");
+    expect(productScene?.style.top).toBe("-130px");
+    expect(productScene?.style.width).toBe("420px");
+    expect(screen.getByTestId("product-frame").textContent).toBe(
+      JSON.stringify({
+        kind: "infinite",
+        rect: { height: 260, width: 420, x: -210, y: -130 },
+      }),
+    );
+  });
+
   it("renders the editable canvas at the schema size", () => {
     const { container } = renderCanvasShell();
 
@@ -59,6 +96,45 @@ describe("CanvasShell rendering", () => {
     ).toBe("");
   });
 
+  it("mounts product viewport content only in Infinity behind the transformed world", () => {
+    const finite = renderCanvasShell({
+      infiniteCanvasContent: <div data-testid="infinite-viewport-content" />,
+    });
+
+    expect(
+      finite.container.querySelector("[data-toolcraft-infinite-canvas-content]"),
+    ).toBeNull();
+    finite.unmount();
+
+    const { container } = renderCanvasShell({
+      children: <div data-testid="bounded-product-content" />,
+      infiniteCanvasContent: <div data-testid="infinite-viewport-content" />,
+      initialState: {
+        canvas: {
+          mode: "infinite",
+          offset: { x: 42, y: -18 },
+          size: { height: 200, unit: "px", width: 300 },
+          zoom: 75,
+        },
+      },
+    });
+    const backdrop = container.querySelector<HTMLElement>(
+      "[data-toolcraft-infinite-canvas-content]",
+    );
+    const world = container.querySelector<HTMLElement>(
+      "[data-toolcraft-canvas-world]",
+    );
+
+    expect(backdrop).toBeTruthy();
+    expect(backdrop?.className).toContain("pointer-events-none");
+    expect(backdrop?.className).toContain("absolute");
+    expect(backdrop?.className).toContain("inset-0");
+    expect(backdrop?.style.transform).toBe("");
+    expect(backdrop?.nextElementSibling).toBe(world);
+    expect(screen.getByTestId("infinite-viewport-content")).toBeTruthy();
+    expect(screen.getByTestId("bounded-product-content")).toBeTruthy();
+  });
+
   it("fills the complete infinite viewport with the selected Background color", () => {
     const { container } = renderCanvasShell({
       initialState: {

package/templates/runtime/react/canvas/canvas-shell-test-utils.tsx

@@ -3,10 +3,12 @@ import type * as React from "react";
 import { vi } from "vitest";
 
 import { defineToolcraft } from "../../schema/define-toolcraft";
+import type { ToolcraftProductSceneBoundsProvider } from "../../scene";
 import type { ToolcraftInitialState } from "../../state/types";
 import { ToolcraftRoot } from "../app-shell/toolcraft-root";
 import { useToolcraft } from "../app-shell/use-toolcraft";
 import { CanvasShell } from "./canvas-shell";
+import { ToolcraftProductSceneBoundsBoundary } from "./product-scene-surface";
 
 export function createSchema() {
   return defineToolcraft({
@@ -121,7 +123,9 @@ type RenderCanvasShellOptions = {
   afterCanvas?: React.ReactNode;
   children?: React.ReactNode;
   frameProps?: React.HTMLAttributes<HTMLDivElement>;
+  infiniteCanvasContent?: React.ReactNode;
   initialState?: ToolcraftInitialState;
+  productSceneBoundsProvider?: ToolcraftProductSceneBoundsProvider;
   schema?: ReturnType<typeof defineToolcraft>;
 };
 
@@ -129,7 +133,9 @@ export function renderCanvasShell({
   afterCanvas,
   children,
   frameProps,
+  infiniteCanvasContent,
   initialState,
+  productSceneBoundsProvider,
   schema = createSchema(),
 }: RenderCanvasShellOptions = {}) {
   const { style, ...restFrameProps } = frameProps ?? {};
@@ -140,7 +146,13 @@ export function renderCanvasShell({
         {...restFrameProps}
         style={{ height: 640, position: "relative", width: 640, ...style }}
       >
-        <CanvasShell>{children}</CanvasShell>
+        <ToolcraftProductSceneBoundsBoundary
+          boundsProvider={productSceneBoundsProvider}
+        >
+          <CanvasShell infiniteCanvasContent={infiniteCanvasContent}>
+            {children}
+          </CanvasShell>
+        </ToolcraftProductSceneBoundsBoundary>
         {afterCanvas}
       </div>
     </ToolcraftRoot>,