@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/runtime/contracts/performance-verification-policy.ts

@@ -6,21 +6,21 @@ export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY = {
   complaintRouting:
     "Performance authority and path localization are separate decisions. Classifier output establishes complaint authority only and never path localization. A localized complaint lets the agent select canonical affected paths and run one targeted iteration without asking the user. An ambiguous or unresolved localization requires one user-facing clarification naming visible operations and offering targeted diagnosis or a complete review; never ask the user for internal path ids. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. A broad or honestly unlocalizable problem may justify recommending the complete review immediately, but only the user's explicit request or acceptance authorizes it. A direct request for a complete review runs the full audit without another clarification.",
   deliveryBatch:
-    "Classify and verify one coherent user-visible delivery batch instead of treating each internal implementation pass or steering correction as a separate aggregate verification boundary.",
+    "Run complete protected functional proof once for the first product version. Later ordinary edits are focused development work and never create another aggregate delivery boundary.",
   deliveryCommand:
-    "Use the protected pnpm verify:delivery command once at the delivery boundary; it derives selectors automatically. Tier, filename, subsystem, complaint repetition, and command selectors cannot authorize proof.",
+    "Use pnpm verify:delivery for the first complete product proof or one exact request-authorized performance iteration. On a proven product without new performance authority it exits before inventory, tests, build, browser work, or checkpoint writes.",
   demandOnlyPerformance:
     "Only exact request authority can create a performance-iteration plan and run measured targeted performance. Changed files, verification tier, ownership classification, affected pass or path ids, and touched subsystems never authorize measured performance.",
   functionalChangeEvidence:
-    "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes require targeted functional/browser evidence. Those changes never authorize measured performance.",
+    "After first delivery, renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and control changes use only focused evidence for the functionality being edited. Those changes never authorize an aggregate functional gate or measured performance.",
   fullAuditDiscovery:
     "The complete performance matrix remains outside conversational delivery. Complaints, repetition, tier, filename, and touched subsystem never launch it automatically. After two consecutive compatible protected performance iterations, the agent must offer a slower complete audit if the user remains unsatisfied; a demonstrably broad or unlocalizable cross-system problem may justify the same offer earlier. An explicit natural-language request for the complete audit, or explicit acceptance of the agent's offer, authorizes the agent acting as operator to run pnpm verify:perf; the user does not need to know the command name. After the audit, repair and rerun failed paths with focused checks, then run the complete matrix only once at the requested certification boundary.",
   performanceIterationDelivery:
     "The runtime request classifier is a tri-state guard, not a replacement for AI semantic judgment: high-confidence runtime complaints, responsiveness optimization, or excessive CPU, GPU, memory, or resource use classify as performance-iteration; high-confidence product motion, speed, freeze, terminology, or locally negated complaint commands classify as ordinary-product-work; ambiguous or unrecognized wording classifies as needs-agent-judgment and the AI decides from the actual user request. Ordinary work is rejected only for a high-confidence performance iteration. Every performance-iteration worklog intent quotes a nontrivial exact raw substring of Request; whitespace and Unicode code units must match before normalized tri-state classification. Invented, whitespace-collapsed, NFKC-equivalent, or mismatched evidence is rejected; high-confidence ordinary evidence is rejected; exact high-confidence performance-iteration evidence, or needs-agent-judgment evidence after semantic resolution, is accepted under agent ownership. Classifier output establishes complaint authority only and never path localization. Each performance iteration requires an exact reachable development fixture and fails with a configuration error instead of falling back to maximum. Only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. Each repeated localized request may create one new bounded targeted iteration over its affected paths; repetition alone never expands scope or selects the complete performance matrix, creates or refreshes a durable baseline, or grants full-performance certification authority.",
   functionalInitialDelivery:
     'A functional delivery plan with basis "initial" runs complete functional proof and no measured performance. It preserves any independent full-performance baseline and cannot claim targeted or full performance evidence.',
-  functionalTargetedDelivery:
-    'A functional delivery plan with basis "changed" runs exact affected ownership-derived functional proof and no measured performance. Functional delivery cannot silently invoke targeted performance, the full performance matrix, or create or refresh a performance baseline.',
+  focusedLaterEdits:
+    "A proven product has no later functional delivery plan. Ordinary edits run only feature-focused tests or browser inspection chosen from the edited behavior; commit, push, deploy, and preview do not authorize aggregate proof.",
   renderScaleFidelity:
     'canvas.renderScale is visible functional fidelity. Raster products declare typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled, and prove real canvas backing pixels in every declared state. Every measured path in a render-scale-enabled raster product proves actual CSS × devicePixelRatio × 2 backing after each measured phase. Never downsample, stretch a lower-resolution backing canvas, blur output, or clamp the selected render scale to pass a performance budget.',
 } as const;
@@ -28,8 +28,8 @@ export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY = {
 export const TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE = {
   delivery: {
     command: "verify:delivery",
-    modes: ["functional", "performance-iteration"],
-    selectors: "automatic",
+    modes: ["initial-functional", "performance-iteration"],
+    selectors: "initial-complete-or-authority-exact",
   },
   fullPerformance: {
     command: "verify:perf",
@@ -45,7 +45,7 @@ export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT = [
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.demandOnlyPerformance,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalChangeEvidence,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalInitialDelivery,
-  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalTargetedDelivery,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.focusedLaterEdits,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.performanceIterationDelivery,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.fullAuditDiscovery,

package/templates/runtime/export/artifact-download.ts

@@ -7,6 +7,7 @@ export type ToolcraftArtifactFileExtension =
   | ".jpg"
   | ".mp4"
   | ".png"
+  | ".svg"
   | ".webm";
 
 type ToolcraftDownloadAnchor = {

package/templates/runtime/export/artifact-frame-renderer.ts

@@ -6,6 +6,7 @@ import {
   ToolcraftArtifactExportError,
 } from "./export-error";
 import type { ToolcraftProductExportFrameRenderer } from "./product-export-renderer";
+import { getToolcraftArtifactTimelineProgress } from "./artifact-frame-state";
 
 export type ToolcraftArtifactFrameRenderRequest = Readonly<{
   backgroundColor: string;
@@ -23,20 +24,6 @@ export type ToolcraftArtifactFrameRenderRequest = Readonly<{
   state: ToolcraftState;
 }>;
 
-function getTimelineProgress(state: ToolcraftState): number {
-  if (state.timeline.durationSeconds <= 0) {
-    return 0;
-  }
-
-  return Math.max(
-    0,
-    Math.min(
-      1,
-      state.timeline.currentTimeSeconds / state.timeline.durationSeconds,
-    ),
-  );
-}
-
 export async function renderToolcraftArtifactFrame(
   request: ToolcraftArtifactFrameRenderRequest,
 ): Promise<void> {
@@ -83,7 +70,7 @@ export async function renderToolcraftArtifactFrame(
       rendererPipeline: request.rendererPipeline,
       state: request.state,
       timeSeconds: request.state.timeline.currentTimeSeconds,
-      timelineProgress: getTimelineProgress(request.state),
+      timelineProgress: getToolcraftArtifactTimelineProgress(request.state),
     });
   } catch (error) {
     throw normalizeToolcraftExportError(error, {

package/templates/runtime/export/artifact-frame-state.ts

@@ -9,6 +9,22 @@ export type ToolcraftVideoArtifactFramePlanEntry = Readonly<{
   state: ToolcraftArtifactFrameState;
 }>;
 
+export function getToolcraftArtifactTimelineProgress(
+  state: ToolcraftState,
+): number {
+  if (state.timeline.durationSeconds <= 0) {
+    return 0;
+  }
+
+  return Math.max(
+    0,
+    Math.min(
+      1,
+      state.timeline.currentTimeSeconds / state.timeline.durationSeconds,
+    ),
+  );
+}
+
 export function createToolcraftArtifactFrameState(
   baseState: ToolcraftState,
   timeSeconds: number,

package/templates/runtime/export/artifact-scene-frame.test.ts

@@ -5,7 +5,7 @@ import { createToolcraftState } from "../state/create-template-state";
 import { createToolcraftRuntimeSceneVisibility } from "../scene";
 import { ToolcraftSceneExportError } from "./export-frame";
 import {
-  resolveToolcraftImageArtifactFrame,
+  resolveToolcraftStillArtifactFrame,
   resolveToolcraftVideoArtifactFrame,
 } from "./artifact-scene-frame";
 import { createToolcraftVideoArtifactFramePlan } from "./artifact-frame-state";
@@ -29,7 +29,7 @@ describe("artifact scene frame", () => {
     const boundsProvider = vi.fn(() => []);
 
     expect(
-      resolveToolcraftImageArtifactFrame({
+      resolveToolcraftStillArtifactFrame({
         boundsProvider,
         productSceneRequired: true,
         state,
@@ -73,7 +73,7 @@ describe("artifact scene frame", () => {
 
   it("fails visibly when an infinite product scene has no bounds provider", () => {
     expect(() =>
-      resolveToolcraftImageArtifactFrame({
+      resolveToolcraftStillArtifactFrame({
         boundsProvider: undefined,
         productSceneRequired: true,
         state: createState("infinite"),

package/templates/runtime/export/artifact-scene-frame.ts

@@ -21,7 +21,7 @@ type ToolcraftArtifactSceneFrameBaseRequest = Readonly<{
   visibility: ToolcraftRuntimeSceneVisibility;
 }>;
 
-export type ToolcraftImageArtifactSceneFrameRequest =
+export type ToolcraftStillArtifactSceneFrameRequest =
   ToolcraftArtifactSceneFrameBaseRequest &
     Readonly<{ state: ToolcraftState }>;
 
@@ -68,8 +68,8 @@ function isFiniteCanvas(state: ToolcraftState): boolean {
   return getToolcraftCanvasFrame(state.canvas).kind === "finite";
 }
 
-export function resolveToolcraftImageArtifactFrame(
-  request: ToolcraftImageArtifactSceneFrameRequest,
+export function resolveToolcraftStillArtifactFrame(
+  request: ToolcraftStillArtifactSceneFrameRequest,
 ): ToolcraftExportFrame {
   if (isFiniteCanvas(request.state)) {
     return requireFrame(resolveToolcraftExportFrame(request.state, null));

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

@@ -8,6 +8,11 @@ export type ToolcraftArtifactExportFailure = Readonly<{
     | "invalid-export-setting"
     | "product-frame-render-failed"
     | "runtime-scene-render-failed"
+    | "svg-content-empty"
+    | "svg-content-invalid"
+    | "svg-document-invalid"
+    | "svg-render-failed"
+    | "svg-serialization-failed"
     | "video-artifact-too-large"
     | "video-encode-failed"
     | "video-encoder-unavailable";

package/templates/runtime/export/export-renderer-coverage.ts

@@ -0,0 +1,54 @@
+import {
+  getToolcraftArtifactExportActions,
+} from "../schema/artifact-export-actions";
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type { ToolcraftProductExportRenderer } from "./product-export-renderer";
+import type { ToolcraftProductSvgExportRenderer } from "./product-svg-export-renderer";
+
+export function getToolcraftExportRendererCoverageErrors({
+  exportRenderer,
+  productSceneRequired,
+  schema,
+  svgExportRenderer,
+}: Readonly<{
+  exportRenderer: ToolcraftProductExportRenderer | undefined;
+  productSceneRequired: boolean;
+  schema: ResolvedToolcraftAppSchema;
+  svgExportRenderer: ToolcraftProductSvgExportRenderer | undefined;
+}>): string[] {
+  const errors: string[] = [];
+  const exportRoles = new Set(
+    getToolcraftArtifactExportActions(schema).map(({ role }) => role),
+  );
+  const hasRasterExportAction =
+    exportRoles.has("export-image") || exportRoles.has("export-video");
+  const hasSvgExportAction = exportRoles.has("export-svg");
+
+  if (hasRasterExportAction && productSceneRequired && !exportRenderer) {
+    errors.push("Product-owned image/video export actions require exportRenderer.");
+  }
+  if (exportRenderer && !productSceneRequired) {
+    errors.push("exportRenderer requires a product-owned scene.");
+  }
+  if (exportRenderer && !hasRasterExportAction) {
+    errors.push("exportRenderer requires a typed image or video export action.");
+  }
+  if (exportRenderer && exportRenderer.baseFileName.trim().length === 0) {
+    errors.push("exportRenderer.baseFileName must not be blank.");
+  }
+
+  if (hasSvgExportAction && !svgExportRenderer) {
+    errors.push("A typed SVG export action requires svgExportRenderer.");
+  }
+  if (svgExportRenderer && !hasSvgExportAction) {
+    errors.push("svgExportRenderer requires a typed SVG export action.");
+  }
+  if (
+    svgExportRenderer &&
+    svgExportRenderer.baseFileName.trim().length === 0
+  ) {
+    errors.push("svgExportRenderer.baseFileName must not be blank.");
+  }
+
+  return errors;
+}

package/templates/runtime/export/image-artifact-export.ts

@@ -11,7 +11,7 @@ import {
 import type { ToolcraftArtifactExportRequest } from "./artifact-export-request";
 import { resolveToolcraftImageExportSettings } from "./artifact-export-settings";
 import { renderToolcraftArtifactFrame } from "./artifact-frame-renderer";
-import { resolveToolcraftImageArtifactFrame } from "./artifact-scene-frame";
+import { resolveToolcraftStillArtifactFrame } from "./artifact-scene-frame";
 import { createToolcraftArtifactFrameState } from "./artifact-frame-state";
 import {
   ToolcraftSceneExportError,
@@ -80,7 +80,7 @@ export async function exportToolcraftImageArtifact(
     request.state,
     request.state.timeline.currentTimeSeconds,
   );
-  const frame = resolveToolcraftImageArtifactFrame({
+  const frame = resolveToolcraftStillArtifactFrame({
     boundsProvider: request.boundsProvider,
     productSceneRequired: request.productSceneRequired,
     state: frameState,

package/templates/runtime/export/index.ts

@@ -42,3 +42,16 @@ export type {
   ToolcraftProductExportFrameRenderer,
   ToolcraftProductExportRenderer,
 } from "./product-export-renderer";
+export type {
+  ToolcraftProductSvgExportFrameContext,
+  ToolcraftProductSvgExportFrameRenderer,
+  ToolcraftProductSvgExportRenderer,
+} from "./product-svg-export-renderer";
+export {
+  TOOLCRAFT_FORBIDDEN_SVG_ELEMENTS,
+  TOOLCRAFT_SVG_BACKGROUND_ATTRIBUTE,
+  TOOLCRAFT_SVG_NAMESPACE,
+  TOOLCRAFT_SVG_NON_RENDERING_CONTAINERS,
+  TOOLCRAFT_SVG_PRODUCT_SCENE_ATTRIBUTE,
+  TOOLCRAFT_SVG_VECTOR_PRIMITIVES,
+} from "./svg-policy";

package/templates/runtime/export/product-export-renderer.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
 
 import { defineToolcraft } from "../schema/define-toolcraft";
-import { getToolcraftExportRendererCoverageErrors } from "./product-export-renderer";
+import { getToolcraftExportRendererCoverageErrors } from "./export-renderer-coverage";
 
-function createSchema(role?: "export-image" | "export-video") {
+function createSchema(role?: "export-image" | "export-svg" | "export-video") {
   return defineToolcraft({
     canvas: { enabled: true },
     panels: role
@@ -37,8 +37,9 @@ describe("export renderer coverage", () => {
         exportRenderer: undefined,
         productSceneRequired: true,
         schema: createSchema("export-image"),
+        svgExportRenderer: undefined,
       }),
-    ).toContain("Product-owned export actions require exportRenderer.");
+    ).toContain("Product-owned image/video export actions require exportRenderer.");
   });
 
   it("allows runtime-only scenes to use runtime composition", () => {
@@ -47,6 +48,7 @@ describe("export renderer coverage", () => {
         exportRenderer: undefined,
         productSceneRequired: false,
         schema: createSchema("export-video"),
+        svgExportRenderer: undefined,
       }),
     ).toEqual([]);
   });
@@ -57,6 +59,7 @@ describe("export renderer coverage", () => {
         exportRenderer: renderer,
         productSceneRequired: false,
         schema: createSchema("export-image"),
+        svgExportRenderer: undefined,
       }),
     ).toContain("exportRenderer requires a product-owned scene.");
     expect(
@@ -64,6 +67,7 @@ describe("export renderer coverage", () => {
         exportRenderer: { ...renderer, baseFileName: "   " },
         productSceneRequired: true,
         schema: createSchema("export-image"),
+        svgExportRenderer: undefined,
       }),
     ).toContain("exportRenderer.baseFileName must not be blank.");
     expect(
@@ -71,7 +75,37 @@ describe("export renderer coverage", () => {
         exportRenderer: renderer,
         productSceneRequired: true,
         schema: createSchema(),
+        svgExportRenderer: undefined,
       }),
-    ).toContain("exportRenderer requires a typed export action.");
+    ).toContain("exportRenderer requires a typed image or video export action.");
+  });
+
+  it("requires SVG actions and renderers to correspond", () => {
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        schema: createSchema("export-svg"),
+        svgExportRenderer: undefined,
+      }),
+    ).toContain("A typed SVG export action requires svgExportRenderer.");
+
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        schema: createSchema(),
+        svgExportRenderer: renderer,
+      }),
+    ).toContain("svgExportRenderer requires a typed SVG export action.");
+
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        schema: createSchema("export-svg"),
+        svgExportRenderer: { ...renderer, baseFileName: "   " },
+      }),
+    ).toContain("svgExportRenderer.baseFileName must not be blank.");
   });
 });

package/templates/runtime/export/product-export-renderer.ts

@@ -1,5 +1,4 @@
 import type { ToolcraftRendererPipelineClient } from "../rendering";
-import type { ResolvedToolcraftAppSchema } from "../schema/types";
 import type { ToolcraftState } from "../state/types";
 import type { ToolcraftExportFrame } from "./export-frame";
 
@@ -21,43 +20,3 @@ export type ToolcraftProductExportRenderer = Readonly<{
   baseFileName: string;
   renderFrame: ToolcraftProductExportFrameRenderer;
 }>;
-
-function hasTypedExportAction(schema: ResolvedToolcraftAppSchema): boolean {
-  return (schema.panels.controls?.sections ?? []).some((section) =>
-    Object.values(section.controls).some((control) =>
-      (control.actions ?? []).some(
-        (action) =>
-          typeof action !== "string" &&
-          (action.role === "export-image" || action.role === "export-video"),
-      ),
-    ),
-  );
-}
-
-export function getToolcraftExportRendererCoverageErrors({
-  exportRenderer,
-  productSceneRequired,
-  schema,
-}: Readonly<{
-  exportRenderer: ToolcraftProductExportRenderer | undefined;
-  productSceneRequired: boolean;
-  schema: ResolvedToolcraftAppSchema;
-}>): string[] {
-  const errors: string[] = [];
-  const hasExportAction = hasTypedExportAction(schema);
-
-  if (hasExportAction && productSceneRequired && !exportRenderer) {
-    errors.push("Product-owned export actions require exportRenderer.");
-  }
-  if (exportRenderer && !productSceneRequired) {
-    errors.push("exportRenderer requires a product-owned scene.");
-  }
-  if (exportRenderer && !hasExportAction) {
-    errors.push("exportRenderer requires a typed export action.");
-  }
-  if (exportRenderer && exportRenderer.baseFileName.trim().length === 0) {
-    errors.push("exportRenderer.baseFileName must not be blank.");
-  }
-
-  return errors;
-}

package/templates/runtime/export/product-svg-export-renderer.ts

@@ -0,0 +1,21 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+
+export type ToolcraftProductSvgExportFrameContext = Readonly<{
+  container: SVGGElement;
+  frame: ToolcraftExportFrame;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  state: Readonly<ToolcraftState>;
+  timeSeconds: number;
+  timelineProgress: number;
+}>;
+
+export type ToolcraftProductSvgExportFrameRenderer = (
+  context: ToolcraftProductSvgExportFrameContext,
+) => PromiseLike<void> | void;
+
+export type ToolcraftProductSvgExportRenderer = Readonly<{
+  baseFileName: string;
+  renderFrame: ToolcraftProductSvgExportFrameRenderer;
+}>;

package/templates/runtime/export/svg-artifact-export.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createToolcraftRuntimeSceneVisibility } from "../scene";
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import type {
+  ToolcraftArtifactDownloadRequest,
+  ToolcraftArtifactDownloadResult,
+} from "./artifact-download";
+import { exportToolcraftSvgArtifact } from "./svg-artifact-export";
+import { TOOLCRAFT_SVG_NAMESPACE } from "./svg-policy";
+
+const visibility = createToolcraftRuntimeSceneVisibility({
+  renderDefaultImages: true,
+  suppressedModelTargets: [],
+});
+
+function createState() {
+  return createToolcraftState(
+    defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+  );
+}
+
+describe("exportToolcraftSvgArtifact", () => {
+  it("renders current vectors, downloads SVG, and reports monotonic progress", async () => {
+    const progress: number[] = [];
+    const downloadArtifact = vi.fn(
+      (
+        _request: ToolcraftArtifactDownloadRequest,
+      ): ToolcraftArtifactDownloadResult => ({
+        fileName: "column-graph.svg",
+      }),
+    );
+    const state = createState();
+
+    const result = await exportToolcraftSvgArtifact({
+      boundsProvider: undefined,
+      downloadArtifact,
+      productSceneRequired: true,
+      rendererPipeline: null,
+      reportProgress: (value) => progress.push(value),
+      state,
+      svgExportRenderer: {
+        baseFileName: "column-graph",
+        renderFrame: ({ container, frame, state: frameState }) => {
+          expect(frameState).not.toBe(state);
+          const rect = container.ownerDocument.createElementNS(
+            TOOLCRAFT_SVG_NAMESPACE,
+            "rect",
+          );
+          rect.setAttribute("width", String(frame.width));
+          rect.setAttribute("height", String(frame.height));
+          rect.setAttribute("data-column-graph-background", "true");
+          container.append(rect);
+        },
+      },
+      visibility,
+    });
+
+    expect(progress).toEqual([0.1, 0.65, 0.9, 1]);
+    expect(result).toMatchObject({
+      extension: ".svg",
+      mediaType: "image/svg+xml",
+      vectorElementCount: 1,
+    });
+    expect(result.byteLength).toBeGreaterThan(0);
+    expect(downloadArtifact).toHaveBeenCalledOnce();
+    const request = downloadArtifact.mock.calls[0]?.[0];
+    expect(request?.extension).toBe(".svg");
+    expect(request?.rawBaseFileName).toBe("column-graph");
+    expect(request?.blob.type).toBe("image/svg+xml;charset=utf-8");
+    await expect(request?.blob.text()).resolves.toContain(
+      'data-column-graph-background="true"',
+    );
+  });
+
+  it("normalizes product renderer failures", async () => {
+    await expect(
+      exportToolcraftSvgArtifact({
+        boundsProvider: undefined,
+        downloadArtifact: vi.fn(),
+        productSceneRequired: false,
+        rendererPipeline: null,
+        reportProgress: vi.fn(),
+        state: createState(),
+        svgExportRenderer: {
+          baseFileName: "broken",
+          renderFrame: () => {
+            throw new Error("renderer exploded");
+          },
+        },
+        visibility,
+      }),
+    ).rejects.toMatchObject({
+      feedback: { code: "svg-render-failed" },
+    });
+  });
+});

package/templates/runtime/export/svg-artifact-export.ts

@@ -0,0 +1,120 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type {
+  ToolcraftProductSceneBoundsProvider,
+  ToolcraftRuntimeSceneVisibility,
+} from "../scene";
+import {
+  getToolcraftRuntimeBackgroundColor,
+  isToolcraftRuntimeBackgroundEnabled,
+} from "../state/canvas-background-state";
+import type { ToolcraftState } from "../state/types";
+import {
+  downloadToolcraftArtifact,
+  type ToolcraftArtifactDownloadRequest,
+  type ToolcraftArtifactDownloadResult,
+} from "./artifact-download";
+import {
+  createToolcraftArtifactFrameState,
+  getToolcraftArtifactTimelineProgress,
+} from "./artifact-frame-state";
+import { resolveToolcraftStillArtifactFrame } from "./artifact-scene-frame";
+import {
+  ToolcraftSceneExportError,
+  validateToolcraftArtifactSize,
+} from "./export-frame";
+import { normalizeToolcraftExportError } from "./export-error";
+import type { ToolcraftProductSvgExportRenderer } from "./product-svg-export-renderer";
+import {
+  createToolcraftSvgDocument,
+  createToolcraftSvgProductContainer,
+  serializeToolcraftSvgDocument,
+} from "./svg-document";
+
+export type ToolcraftSvgArtifactExportResult = Readonly<{
+  byteLength: number;
+  extension: ".svg";
+  height: number;
+  mediaType: "image/svg+xml";
+  vectorElementCount: number;
+  width: number;
+}>;
+
+export type ToolcraftSvgArtifactExportRequest = Readonly<{
+  boundsProvider: ToolcraftProductSceneBoundsProvider | undefined;
+  downloadArtifact?: (
+    request: ToolcraftArtifactDownloadRequest,
+  ) => ToolcraftArtifactDownloadResult;
+  productSceneRequired: boolean;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  reportProgress: (progress: number) => void;
+  state: ToolcraftState;
+  svgExportRenderer: ToolcraftProductSvgExportRenderer;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;
+
+export async function exportToolcraftSvgArtifact(
+  request: ToolcraftSvgArtifactExportRequest,
+): Promise<ToolcraftSvgArtifactExportResult> {
+  const frameState = createToolcraftArtifactFrameState(
+    request.state,
+    request.state.timeline.currentTimeSeconds,
+  );
+  const frame = resolveToolcraftStillArtifactFrame({
+    boundsProvider: request.boundsProvider,
+    productSceneRequired: request.productSceneRequired,
+    state: frameState,
+    visibility: request.visibility,
+  });
+  const sizeValidation = validateToolcraftArtifactSize(frame);
+  if (!sizeValidation.ok) {
+    throw new ToolcraftSceneExportError(sizeValidation);
+  }
+
+  const { document: svgDocument } = createToolcraftSvgDocument(frame);
+  const { container } = createToolcraftSvgProductContainer();
+  request.reportProgress(0.1);
+  try {
+    await request.svgExportRenderer.renderFrame({
+      container,
+      frame,
+      rendererPipeline: request.rendererPipeline,
+      state: frameState,
+      timeSeconds: frameState.timeline.currentTimeSeconds,
+      timelineProgress: getToolcraftArtifactTimelineProgress(frameState),
+    });
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, {
+      code: "svg-render-failed",
+      message: "Toolcraft could not render product vectors for SVG export.",
+    });
+  }
+  request.reportProgress(0.65);
+
+  const serialized = serializeToolcraftSvgDocument({
+    backgroundColor: isToolcraftRuntimeBackgroundEnabled(frameState)
+      ? (getToolcraftRuntimeBackgroundColor(frameState) ?? "#000000")
+      : null,
+    container,
+    document: svgDocument,
+    frame,
+  });
+  const blob = new Blob([serialized.source], {
+    type: "image/svg+xml;charset=utf-8",
+  });
+  request.reportProgress(0.9);
+  (request.downloadArtifact ?? downloadToolcraftArtifact)({
+    blob,
+    extension: ".svg",
+    rawBaseFileName: request.svgExportRenderer.baseFileName,
+  });
+  request.reportProgress(1);
+
+  return Object.freeze({
+    byteLength: blob.size,
+    extension: ".svg",
+    height: frame.height,
+    mediaType: "image/svg+xml",
+    vectorElementCount: serialized.vectorElementCount,
+    width: frame.width,
+  });
+}