@pixel-point/toolcraft 0.0.15 → 0.0.17

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

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS } from "./component-contracts.runtime";
+import { getToolcraftDecisionRule } from "./decision-contracts";
+import {
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+} from "./performance-verification-policy";
+
+describe("Toolcraft canonical performance verification policy", () => {
+  it("is consumed verbatim by component and decision contract surfaces", () => {
+    const componentRules =
+      TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS.performanceAcceptance.aiUsageRules;
+    const decisionRule = getToolcraftDecisionRule("performance-coverage-levels");
+
+    expect(componentRules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+    );
+    expect(decisionRule?.desiredBehavior).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+    );
+  });
+
+  it("keeps request-driven performance work bounded to targeted iterations", () => {
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY).toEqual({
+      agentBrowser:
+        "Agent-controlled browser checks are limited to diagnosis and targeted visual investigation; they do not mint durable performance baselines or receipts.",
+      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.",
+      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.",
+      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.",
+      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.',
+      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.',
+    });
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE).toEqual({
+      delivery: {
+        command: "verify:delivery",
+        modes: ["functional", "performance-iteration"],
+        selectors: "automatic",
+      },
+      fullPerformance: {
+        command: "verify:perf",
+        authority: "explicit-user-request-or-accepted-offer",
+      },
+    });
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /one coherent user-visible delivery batch/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /verify:delivery/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /tier, filename, subsystem, complaint repetition, and command selectors cannot authorize proof/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /functional delivery plan with basis "initial"[\s\S]*complete functional proof[\s\S]*no measured performance/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /functional delivery cannot silently invoke targeted performance/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /only exact request authority can create a performance-iteration plan and run measured targeted performance/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /functional delivery plan with basis "changed"[\s\S]*exact affected ownership-derived functional proof[\s\S]*no measured performance/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /tri-state guard, not a replacement for AI semantic judgment/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /CPU, GPU, memory, or resource use/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /ambiguous or unrecognized wording classifies as needs-agent-judgment/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /exact high-confidence performance-iteration evidence, or needs-agent-judgment evidence after semantic resolution, is accepted under agent ownership/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /whitespace and Unicode code units must match/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /performance iteration requires an exact reachable development fixture/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /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/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /each repeated localized request may create one new bounded targeted iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).not.toMatch(
+      /one complaint maps to one exact authority-selected targeted performance iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).not.toMatch(
+      /direct and repeated performance complaints each start one bounded targeted iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /localized complaint[\s\S]*without asking the user/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /ambiguous or unresolved localization[\s\S]*one user-facing clarification[\s\S]*targeted diagnosis or a complete review/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /direct request for a complete review[\s\S]*without another clarification/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /repetition alone never expands scope or selects the complete performance matrix/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /two consecutive compatible protected performance iterations[\s\S]*must offer/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /explicit natural-language request[\s\S]*acceptance[\s\S]*authorizes[\s\S]*pnpm verify:perf/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /user does not need to know the command name/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /run the complete matrix only once at the requested certification boundary/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /renderer, canvas,[\s\S]*canvas\.renderScale[\s\S]*require targeted functional\/browser evidence[\s\S]*never authorize measured performance/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled/i,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /every measured path[\s\S]*devicePixelRatio × 2[\s\S]*each measured phase/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /never downsample[\s\S]*clamp the selected render scale to pass a performance budget/i,
+    );
+  });
+
+  it.each([
+    {
+      axis: "high-confidence but unlocalized complaint",
+      expected:
+        /classifier output establishes complaint authority only and never path localization[\s\S]*regardless of whether the classifier returned high-confidence performance-iteration[\s\S]*unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
+    },
+    {
+      axis: "localized complaint",
+      expected:
+        /localized complaint[\s\S]*one targeted iteration without asking the user/iu,
+    },
+    {
+      axis: "needs-agent-judgment with unresolved localization",
+      expected:
+        /regardless of whether the classifier returned[\s\S]*needs-agent-judgment[\s\S]*unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
+    },
+    {
+      axis: "post-clarification targeted choice",
+      expected:
+        /post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths/iu,
+    },
+  ])("routes $axis without coupling authority to localization", ({ expected }) => {
+    const canonicalRoutingPolicy = [
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.performanceIterationDelivery,
+    ].join(" ");
+
+    expect(canonicalRoutingPolicy).toMatch(expected);
+  });
+});

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

@@ -0,0 +1,52 @@
+export * from "./performance-request-classifier";
+
+export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY = {
+  agentBrowser:
+    "Agent-controlled browser checks are limited to diagnosis and targeted visual investigation; they do not mint durable performance baselines or receipts.",
+  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.",
+  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.",
+  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.",
+  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.',
+  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;
+
+export const TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE = {
+  delivery: {
+    command: "verify:delivery",
+    modes: ["functional", "performance-iteration"],
+    selectors: "automatic",
+  },
+  fullPerformance: {
+    command: "verify:perf",
+    authority: "explicit-user-request-or-accepted-offer",
+  },
+} as const;
+
+export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT = [
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.agentBrowser,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.deliveryBatch,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.deliveryCommand,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.demandOnlyPerformance,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalChangeEvidence,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalInitialDelivery,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalTargetedDelivery,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.performanceIterationDelivery,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.fullAuditDiscovery,
+].join(" ");

package/templates/runtime/contracts/segmented-control-fit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getToolcraftSegmentedStaticFitError,
+  renderToolcraftSegmentedStaticFitDocumentationSentence,
+  TOOLCRAFT_SEGMENTED_STATIC_FIT,
+} from "./segmented-control-fit";
+
+const SEGMENTED_STATIC_FIT_ERROR = `segmented controls must preserve cell padding: use at most ${TOOLCRAFT_SEGMENTED_STATIC_FIT.maxOptions} short options (max ${TOOLCRAFT_SEGMENTED_STATIC_FIT.maxOptionLabelLength} characters per label and ${TOOLCRAFT_SEGMENTED_STATIC_FIT.maxTotalLabelLength} total) or shorten labels first; if the compact names still exceed the budget, use a select dropdown instead.`;
+
+describe("Toolcraft segmented static-fit policy", () => {
+  it("publishes the canonical immutable limits", () => {
+    expect(TOOLCRAFT_SEGMENTED_STATIC_FIT).toEqual({
+      maxOptionLabelLength: 9,
+      maxOptions: 4,
+      maxTotalLabelLength: 24,
+    });
+    expect(Object.isFrozen(TOOLCRAFT_SEGMENTED_STATIC_FIT)).toBe(true);
+  });
+
+  it("renders the canonical policy-derived documentation sentence", () => {
+    expect(renderToolcraftSegmentedStaticFitDocumentationSentence()).toBe(
+      "Text segmented controls allow at most 4 options, no option label longer than 9 characters, and no more than 24 total option-label characters.",
+    );
+  });
+
+  it("accepts labels at every static-fit boundary", () => {
+    expect(
+      getToolcraftSegmentedStaticFitError({
+        options: [
+          { label: "Ink Drops" },
+          { label: "Default" },
+          { label: "Solar" },
+          { label: "RGB" },
+        ],
+        type: "segmented",
+      }),
+    ).toBeNull();
+  });
+
+  it.each([
+    {
+      name: "more than four options",
+      options: ["One", "Two", "Three", "Four", "Five"],
+    },
+    {
+      name: "a trimmed label longer than nine characters",
+      options: ["  Ten letters  "],
+    },
+    {
+      name: "a trimmed total label length longer than 24 characters",
+      options: ["123456789", "123456789", "1234567"],
+    },
+  ])("rejects $name", ({ options }) => {
+    expect(
+      getToolcraftSegmentedStaticFitError({
+        options: options.map((label) => ({ label })),
+        type: "segmented",
+      }),
+    ).toBe(SEGMENTED_STATIC_FIT_ERROR);
+  });
+
+  it("does not apply segmented limits to select controls", () => {
+    expect(
+      getToolcraftSegmentedStaticFitError({
+        options: [{ label: "A label beyond every segmented limit" }],
+        type: "select",
+      }),
+    ).toBeNull();
+  });
+});

package/templates/runtime/contracts/segmented-control-fit.ts

@@ -0,0 +1,38 @@
+export const TOOLCRAFT_SEGMENTED_STATIC_FIT = Object.freeze({
+  maxOptionLabelLength: 9,
+  maxOptions: 4,
+  maxTotalLabelLength: 24,
+});
+
+export function renderToolcraftSegmentedStaticFitDocumentationSentence(): string {
+  const { maxOptionLabelLength, maxOptions, maxTotalLabelLength } =
+    TOOLCRAFT_SEGMENTED_STATIC_FIT;
+
+  return `Text segmented controls allow at most ${maxOptions} options, no option label longer than ${maxOptionLabelLength} characters, and no more than ${maxTotalLabelLength} total option-label characters.`;
+}
+
+type ToolcraftSegmentedStaticFitInput = {
+  readonly options?: readonly { readonly label: string }[];
+  readonly type: string;
+};
+
+export function getToolcraftSegmentedStaticFitError(
+  control: ToolcraftSegmentedStaticFitInput,
+): string | null {
+  if (control.type !== "segmented") return null;
+
+  const { maxOptionLabelLength, maxOptions, maxTotalLabelLength } =
+    TOOLCRAFT_SEGMENTED_STATIC_FIT;
+  const labelLengths = (control.options ?? []).map(
+    (option) => option.label.trim().length,
+  );
+  const exceedsStaticFit =
+    labelLengths.length > maxOptions ||
+    labelLengths.some((length) => length > maxOptionLabelLength) ||
+    labelLengths.reduce((total, length) => total + length, 0) >
+      maxTotalLabelLength;
+
+  return exceedsStaticFit
+    ? `segmented controls must preserve cell padding: use at most ${maxOptions} short options (max ${maxOptionLabelLength} characters per label and ${maxTotalLabelLength} total) or shorten labels first; if the compact names still exceed the budget, use a select dropdown instead.`
+    : null;
+}

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

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { downloadToolcraftArtifact } from "./artifact-download";
+
+describe("downloadToolcraftArtifact", () => {
+  it("sanitizes the filename and revokes the object URL after the click", () => {
+    const events: string[] = [];
+    const anchor = {
+      click: vi.fn(() => events.push("click")),
+      download: "",
+      href: "",
+      remove: vi.fn(() => events.push("remove")),
+    };
+    const schedule = vi.fn((callback: () => void) => {
+      events.push("schedule-revoke");
+      callback();
+      return 1;
+    });
+
+    const result = downloadToolcraftArtifact({
+      appendAnchor: () => events.push("append"),
+      blob: new Blob(["png"], { type: "image/png" }),
+      createAnchor: () => anchor,
+      createObjectUrl: () => "blob:artifact",
+      extension: ".png",
+      rawBaseFileName: "  Unsafe / name  ",
+      revokeObjectUrl: () => events.push("revoke"),
+      schedule,
+    });
+
+    expect(result.fileName).toBe("Unsafe-name.png");
+    expect(anchor.download).toBe("Unsafe-name.png");
+    expect(events).toEqual([
+      "append",
+      "click",
+      "remove",
+      "schedule-revoke",
+      "revoke",
+    ]);
+  });
+
+  it("types click failures and still removes and revokes", () => {
+    const remove = vi.fn();
+    const revoke = vi.fn();
+
+    expect(() =>
+      downloadToolcraftArtifact({
+        appendAnchor: vi.fn(),
+        blob: new Blob(["png"]),
+        createAnchor: () => ({
+          click: () => {
+            throw new Error("blocked");
+          },
+          download: "",
+          href: "",
+          remove,
+        }),
+        createObjectUrl: () => "blob:artifact",
+        extension: ".png",
+        rawBaseFileName: "",
+        revokeObjectUrl: revoke,
+        schedule: (callback) => {
+          callback();
+          return 1;
+        },
+      }),
+    ).toThrow("could not start the artifact download");
+    expect(remove).toHaveBeenCalledOnce();
+    expect(revoke).toHaveBeenCalledWith("blob:artifact");
+  });
+});

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

@@ -0,0 +1,80 @@
+import {
+  normalizeToolcraftExportError,
+  type ToolcraftArtifactExportFailure,
+} from "./export-error";
+
+export type ToolcraftArtifactFileExtension =
+  | ".jpg"
+  | ".mp4"
+  | ".png"
+  | ".webm";
+
+type ToolcraftDownloadAnchor = {
+  click: () => void;
+  download: string;
+  href: string;
+  remove: () => void;
+};
+
+export type ToolcraftArtifactDownloadRequest = Readonly<{
+  appendAnchor?: (anchor: ToolcraftDownloadAnchor) => void;
+  blob: Blob;
+  createAnchor?: () => ToolcraftDownloadAnchor;
+  createObjectUrl?: (blob: Blob) => string;
+  extension: ToolcraftArtifactFileExtension;
+  rawBaseFileName: string;
+  revokeObjectUrl?: (url: string) => void;
+  schedule?: (callback: () => void, delay: number) => unknown;
+}>;
+
+export type ToolcraftArtifactDownloadResult = Readonly<{ fileName: string }>;
+
+export function sanitizeToolcraftArtifactBaseFileName(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "");
+
+  return sanitized || "toolcraft-export";
+}
+
+const downloadFailure: ToolcraftArtifactExportFailure = Object.freeze({
+  code: "artifact-download-failed",
+  message: "Toolcraft could not start the artifact download.",
+});
+
+export function downloadToolcraftArtifact(
+  request: ToolcraftArtifactDownloadRequest,
+): ToolcraftArtifactDownloadResult {
+  const createAnchor =
+    request.createAnchor ?? (() => document.createElement("a"));
+  const appendAnchor =
+    request.appendAnchor ??
+    ((anchor) => document.body.append(anchor as HTMLAnchorElement));
+  const createObjectUrl = request.createObjectUrl ?? URL.createObjectURL;
+  const revokeObjectUrl = request.revokeObjectUrl ?? URL.revokeObjectURL;
+  const schedule = request.schedule ?? globalThis.setTimeout;
+  const fileName = `${sanitizeToolcraftArtifactBaseFileName(
+    request.rawBaseFileName,
+  )}${request.extension}`;
+  let anchor: ToolcraftDownloadAnchor | null = null;
+  let objectUrl: string | null = null;
+
+  try {
+    objectUrl = createObjectUrl(request.blob);
+    anchor = createAnchor();
+    anchor.download = fileName;
+    anchor.href = objectUrl;
+    appendAnchor(anchor);
+    anchor.click();
+    return { fileName };
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, downloadFailure);
+  } finally {
+    anchor?.remove();
+    if (objectUrl) {
+      const urlToRevoke = objectUrl;
+      schedule(() => revokeObjectUrl(urlToRevoke), 0);
+    }
+  }
+}

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

@@ -0,0 +1,23 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type {
+  ToolcraftProductSceneBoundsProvider,
+  ToolcraftRuntimeSceneVisibility,
+} from "../scene";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+import type { ToolcraftProductExportRenderer } from "./product-export-renderer";
+
+export type ToolcraftArtifactExportRequest = Readonly<{
+  boundsProvider: ToolcraftProductSceneBoundsProvider | undefined;
+  exportRenderer: ToolcraftProductExportRenderer | undefined;
+  productSceneRequired: boolean;
+  renderRuntimeScene: (
+    canvas: HTMLCanvasElement,
+    frame: ToolcraftExportFrame,
+    state: ToolcraftState,
+  ) => Promise<unknown>;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  reportProgress: (progress: number) => void;
+  state: ToolcraftState;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;

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

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import {
+  resolveToolcraftImageExportSettings,
+  resolveToolcraftVideoExportSettings,
+  toolcraftImageExportFormatTarget,
+  toolcraftImageExportResolutionTarget,
+  toolcraftVideoExportFormatTarget,
+  toolcraftVideoExportResolutionTarget,
+} from "./artifact-export-settings";
+import { ToolcraftArtifactExportError } from "./export-error";
+
+function createState() {
+  return createToolcraftState(
+    defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+  );
+}
+
+describe("artifact export settings", () => {
+  it("uses canonical defaults when controls are absent", () => {
+    const state = createState();
+
+    expect(resolveToolcraftImageExportSettings(state)).toEqual({
+      format: "png",
+      resolution: "4k",
+    });
+    expect(resolveToolcraftVideoExportSettings(state)).toEqual({
+      format: "mp4",
+      resolution: "current",
+    });
+  });
+
+  it("prefers current values over normalized defaults", () => {
+    const state = createState();
+    Object.assign(state.defaults, {
+      [toolcraftImageExportFormatTarget]: "png",
+      [toolcraftImageExportResolutionTarget]: "4k",
+      [toolcraftVideoExportFormatTarget]: "mp4",
+      [toolcraftVideoExportResolutionTarget]: "current",
+    });
+    Object.assign(state.values, {
+      [toolcraftImageExportFormatTarget]: "jpg",
+      [toolcraftImageExportResolutionTarget]: "8k",
+      [toolcraftVideoExportFormatTarget]: "webm",
+      [toolcraftVideoExportResolutionTarget]: "4k",
+    });
+
+    expect(resolveToolcraftImageExportSettings(state)).toEqual({
+      format: "jpg",
+      resolution: "8k",
+    });
+    expect(resolveToolcraftVideoExportSettings(state)).toEqual({
+      format: "webm",
+      resolution: "4k",
+    });
+  });
+
+  it("rejects unsupported present values with the exact target", () => {
+    const state = createState();
+    state.values[toolcraftVideoExportFormatTarget] = "mov";
+
+    try {
+      resolveToolcraftVideoExportSettings(state);
+      throw new Error("Expected invalid export setting.");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ToolcraftArtifactExportError);
+      expect((error as ToolcraftArtifactExportError).feedback).toMatchObject({
+        code: "invalid-export-setting",
+        target: toolcraftVideoExportFormatTarget,
+      });
+    }
+  });
+});