@pixel-point/toolcraft 0.0.17 → 0.0.18

package/templates/starter/e2e/app-browser-semantic-evidence.spec.ts

@@ -1,8 +1,6 @@
 import { expect, test } from "@playwright/test";
-import {
-  expectToolcraftBackgroundOutputSemantics,
-  expectToolcraftConditionalControlVisibility,
-} from "./browser-conditional-output-evidence-helpers";
+import { expectToolcraftBackgroundOutputSemantics } from "./browser-background-output-evidence";
+import { expectToolcraftControlApplicabilityState } from "./browser-control-applicability-evidence";
 import {
   expectToolcraftLayerReorder,
   expectToolcraftLayerSelection,
@@ -12,6 +10,7 @@ import {
   attachedEvidenceTypes,
   setProofState,
   setSyntheticControlOwner,
+  setSyntheticSwitchControlOwner,
 } from "./browser-semantic-evidence-test-helpers";
 import {
   expectToolcraftMediaLifecycle,
@@ -315,34 +314,81 @@ test("timeline recipes bind duration to renderer, keyframes to output, and loops
   ]);
 });
 
-test("conditional visibility recipe proves target absence and restoration through the gating control", async ({
+test("control applicability recipe proves exact target absence and presence", async ({
   page,
 }, testInfo) => {
   await page.goto("/");
   const session = await createToolcraftBrowserProofSession(page);
   const attachmentCount = testInfo.attachments.length;
-  await setSyntheticControlOwner(page, "feature.enabled", true);
+  await setSyntheticSwitchControlOwner(page, "feature.enabled", false);
   await setSyntheticControlOwner(page, "feature.conditional", true);
 
-  await expectToolcraftConditionalControlVisibility(
+  const hiddenCase = {
+    expectation: "hidden" as const,
+    selectorControlType: "switch" as const,
+    selectorLabel: "feature.enabled",
+    selectorTarget: "feature.enabled",
+    selectorValue: false,
+    target: "feature.conditional",
+  };
+  const visibleCase = {
+    ...hiddenCase,
+    expectation: "visible" as const,
+    selectorValue: true,
+  };
+  const mismatchedAction = session.controlAction(
+    "feature.other",
+    () => undefined,
+  );
+
+  await expect(
+    expectToolcraftControlApplicabilityState(
+      session,
+      mismatchedAction,
+      hiddenCase,
+      { baseRequirementId: "feature.conditional", timeoutMs: 50 },
+    ),
+  ).rejects.toThrow(/target-scoped selector action/);
+  expect(testInfo.attachments).toHaveLength(attachmentCount);
+
+  await expect(
+    expectToolcraftControlApplicabilityState(
+      session,
+      session.controlAction("feature.enabled", () => undefined),
+      hiddenCase,
+      { baseRequirementId: "feature.conditional", timeoutMs: 50 },
+    ),
+  ).rejects.toThrow(/should be hidden/);
+  expect(testInfo.attachments).toHaveLength(attachmentCount);
+
+  await expectToolcraftControlApplicabilityState(
     session,
     session.controlAction("feature.enabled", (control, currentPage) => {
       expect(control).toBeTruthy();
-      return setSyntheticControlOwner(currentPage, "feature.conditional", false);
+      return Promise.all([
+        setSyntheticSwitchControlOwner(currentPage, "feature.enabled", false),
+        setSyntheticControlOwner(currentPage, "feature.conditional", false),
+      ]).then(() => undefined);
     }),
+    hiddenCase,
+    { baseRequirementId: "feature.conditional" },
+  );
+  await expectToolcraftControlApplicabilityState(
+    session,
     session.controlAction("feature.enabled", (control, currentPage) => {
       expect(control).toBeTruthy();
-      return setSyntheticControlOwner(currentPage, "feature.conditional", true);
+      return Promise.all([
+        setSyntheticSwitchControlOwner(currentPage, "feature.enabled", true),
+        setSyntheticControlOwner(currentPage, "feature.conditional", true),
+      ]).then(() => undefined);
     }),
-    {
-      requirementId: "feature.conditional",
-      target: "feature.conditional",
-    },
+    visibleCase,
+    { baseRequirementId: "feature.conditional" },
   );
 
   expect(attachedEvidenceTypes(testInfo, attachmentCount)).toEqual([
-    "conditional-control-hidden",
-    "conditional-control-visible",
+    "control-applicability-hidden",
+    "control-applicability-visible",
   ]);
 });
 

package/templates/starter/e2e/{browser-conditional-output-evidence-helpers.ts → browser-background-output-evidence.ts}

@@ -2,20 +2,12 @@ import { expect } from "@playwright/test";
 
 import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
 import {
-  countToolcraftControlOwnersByTarget,
-  getToolcraftControlFieldByTarget,
-} from "./browser-control-target-helpers";
-import {
-  assertToolcraftBrowserActionForSession,
   assertToolcraftBrowserProofSession,
   getToolcraftBrowserActionTarget,
-  getToolcraftBrowserProofPage,
   readToolcraftBrowserObservation,
-  runToolcraftBrowserAction,
   runToolcraftBrowserValueAction,
   type ToolcraftBrowserAction,
   type ToolcraftBrowserObservation,
-  type ToolcraftBrowserProofSession,
 } from "./browser-proof-session";
 import {
   assertToolcraftProducedArtifact,
@@ -77,66 +69,6 @@ function validateBackgroundPreviewObservation(
   ).not.toBe("");
 }
 
-export async function expectToolcraftConditionalControlVisibility(
-  session: ToolcraftBrowserProofSession,
-  hideControl: ToolcraftBrowserAction,
-  showControl: ToolcraftBrowserAction,
-  {
-    requirementId,
-    target,
-    timeoutMs = 5_000,
-  }: {
-    requirementId: string;
-    target: string;
-    timeoutMs?: number;
-  },
-): Promise<void> {
-  const normalizedTarget = target.trim();
-  expect(
-    normalizedTarget,
-    "Conditional-visibility evidence requires the dependent schema target.",
-  ).not.toBe("");
-  assertToolcraftBrowserActionForSession(session, hideControl);
-  assertToolcraftBrowserActionForSession(session, showControl);
-  const hideGateTarget = requireTargetScopedAction(
-    hideControl,
-    "Conditional-visibility hide evidence requires a target-scoped gating control action.",
-  );
-  expect(
-    requireTargetScopedAction(
-      showControl,
-      "Conditional-visibility show evidence requires a target-scoped gating control action.",
-    ),
-    "Conditional-visibility hide and show actions must exercise the same gating control.",
-  ).toBe(hideGateTarget);
-
-  const page = await getToolcraftBrowserProofPage(session);
-  await getToolcraftControlFieldByTarget(page, normalizedTarget);
-  await runToolcraftBrowserAction(hideControl);
-  await expect
-    .poll(
-      () => countToolcraftControlOwnersByTarget(page, normalizedTarget),
-      {
-        message: `Conditional control "${normalizedTarget}" should be absent while its gating state is unavailable.`,
-        timeout: timeoutMs,
-      },
-    )
-    .toBe(0);
-  await attachToolcraftBrowserRuntimeEvidence({
-    evidenceType: "conditional-control-hidden",
-    requirementId,
-    target: normalizedTarget,
-  });
-
-  await runToolcraftBrowserAction(showControl);
-  await getToolcraftControlFieldByTarget(page, normalizedTarget);
-  await attachToolcraftBrowserRuntimeEvidence({
-    evidenceType: "conditional-control-visible",
-    requirementId,
-    target: normalizedTarget,
-  });
-}
-
 export async function expectToolcraftBackgroundOutputSemantics<
   TImageArtifact,
   TVideoArtifact = never,

package/templates/starter/e2e/browser-control-applicability-evidence.ts

@@ -0,0 +1,114 @@
+import { expect, type Page } from "@playwright/test";
+
+import {
+  getToolcraftApplicabilityRequirementId,
+  type ToolcraftControlApplicabilityCase,
+} from "../src/app/starter-acceptance";
+import {
+  countToolcraftControlOwnersByTarget,
+  getToolcraftControlFieldByTarget,
+} from "./browser-control-target-helpers";
+import {
+  assertToolcraftBrowserActionForSession,
+  getToolcraftBrowserActionTarget,
+  getToolcraftBrowserProofPage,
+  runToolcraftBrowserAction,
+  type ToolcraftBrowserAction,
+  type ToolcraftBrowserProofSession,
+} from "./browser-proof-session";
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+
+function requireSelectorOptionLabel(
+  applicabilityCase: ToolcraftControlApplicabilityCase,
+): string {
+  if (!applicabilityCase.selectorOptionLabel) {
+    throw new Error(
+      `Applicability case for ${applicabilityCase.selectorTarget} requires a selector option label.`,
+    );
+  }
+
+  return applicabilityCase.selectorOptionLabel;
+}
+
+async function expectToolcraftApplicabilitySelectorState(
+  page: Page,
+  applicabilityCase: ToolcraftControlApplicabilityCase,
+): Promise<void> {
+  const control = await getToolcraftControlFieldByTarget(
+    page,
+    applicabilityCase.selectorTarget,
+  );
+
+  switch (applicabilityCase.selectorControlType) {
+    case "checkbox":
+    case "switch":
+      await expect(
+        control.getByRole(applicabilityCase.selectorControlType),
+      ).toHaveAttribute("aria-checked", String(applicabilityCase.selectorValue));
+      return;
+    case "imagePicker":
+    case "segmented":
+      await expect(
+        control.getByRole("button", {
+          name: requireSelectorOptionLabel(applicabilityCase),
+        }),
+      ).toHaveAttribute("aria-pressed", "true");
+      return;
+    case "select":
+      await expect(control.getByRole("combobox")).toContainText(
+        requireSelectorOptionLabel(applicabilityCase),
+      );
+      return;
+    case "slider":
+      await expect(control.getByRole("slider")).toHaveAttribute(
+        "aria-valuenow",
+        String(applicabilityCase.selectorValue),
+      );
+      return;
+    case "tabs":
+      await expect(
+        control.getByRole("tab", {
+          name: requireSelectorOptionLabel(applicabilityCase),
+        }),
+      ).toHaveAttribute("aria-selected", "true");
+  }
+}
+
+export async function expectToolcraftControlApplicabilityState(
+  session: ToolcraftBrowserProofSession,
+  selectBranch: ToolcraftBrowserAction,
+  applicabilityCase: ToolcraftControlApplicabilityCase,
+  options: { baseRequirementId: string; timeoutMs?: number },
+): Promise<void> {
+  const selectorTarget = getToolcraftBrowserActionTarget(selectBranch)?.trim();
+  expect(
+    selectorTarget,
+    "Control-applicability evidence requires a target-scoped selector action.",
+  ).toBe(applicabilityCase.selectorTarget);
+  assertToolcraftBrowserActionForSession(session, selectBranch);
+
+  const page = await getToolcraftBrowserProofPage(session);
+  await runToolcraftBrowserAction(selectBranch);
+  await expectToolcraftApplicabilitySelectorState(page, applicabilityCase);
+  await expect
+    .poll(
+      () => countToolcraftControlOwnersByTarget(page, applicabilityCase.target),
+      {
+        message: `Control "${applicabilityCase.target}" should be ${applicabilityCase.expectation} for ${applicabilityCase.selectorTarget}=${JSON.stringify(applicabilityCase.selectorValue)}.`,
+        timeout: options.timeoutMs ?? 5_000,
+      },
+    )
+    .toBe(applicabilityCase.expectation === "hidden" ? 0 : 1);
+
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType:
+      applicabilityCase.expectation === "hidden"
+        ? "control-applicability-hidden"
+        : "control-applicability-visible",
+    requirementId: getToolcraftApplicabilityRequirementId(
+      options.baseRequirementId,
+      applicabilityCase,
+    ),
+    target: applicabilityCase.target,
+  });
+}

package/templates/starter/e2e/browser-infinity-canvas-evidence.ts

@@ -18,6 +18,7 @@ export type InfinityCanvasObservation = Readonly<{
   finiteControlSize: { height: number; width: number } | null;
   finiteControlsPresent: boolean;
   overflow: string;
+  productSceneStatus: "empty" | "ready" | "unavailable" | null;
   sceneRect: { height: number; width: number; x: number; y: number } | null;
   viewportOffset: { x: number; y: number };
 }>;
@@ -91,18 +92,17 @@ export async function observeInfinityCanvasBackground(
 
 export async function observeInfinityCanvas(
   page: Page,
-  sceneSelector?: string,
 ): Promise<InfinityCanvasObservation> {
-  return page.evaluate((selector) => {
+  return page.evaluate(() => {
     const surface = document.querySelector<HTMLElement>(
       "[data-toolcraft-canvas-mode]",
     );
     const world = document.querySelector<HTMLElement>(
       "[data-toolcraft-canvas-world]",
     );
-    const scene = selector
-      ? document.querySelector<HTMLElement>(selector)
-      : null;
+    const productScene = document.querySelector<HTMLElement>(
+      "[data-toolcraft-product-scene]",
+    );
     const finiteControlsPresent = [
       "canvas.aspectRatio",
       "canvas.size.width",
@@ -138,7 +138,7 @@ export async function observeInfinityCanvas(
       const parsed = Number.parseFloat(value ?? "");
       return Number.isFinite(parsed) ? parsed : null;
     };
-    const style = scene?.style;
+    const style = productScene?.style;
     const sceneValues = style
       ? {
           height: read(style.height),
@@ -156,11 +156,11 @@ export async function observeInfinityCanvas(
             y: sceneValues.y!,
           }
         : null;
+    const productSceneStatus =
+      productScene?.dataset.toolcraftProductSceneStatus;
 
     return {
-      artboardPresent: Boolean(
-        editableCanvas,
-      ),
+      artboardPresent: Boolean(editableCanvas),
       canvasMode: surface?.getAttribute("data-toolcraft-canvas-mode") ?? null,
       finiteCanvasSize:
         canvasWidth === null || canvasHeight === null
@@ -172,13 +172,19 @@ export async function observeInfinityCanvas(
           : { height: controlHeight, width: controlWidth },
       finiteControlsPresent,
       overflow: surface ? getComputedStyle(surface).overflow : "missing",
+      productSceneStatus:
+        productSceneStatus === "ready" ||
+        productSceneStatus === "empty" ||
+        productSceneStatus === "unavailable"
+          ? productSceneStatus
+          : null,
       sceneRect,
       viewportOffset: {
         x: Number(world?.dataset.toolcraftCanvasOffsetX ?? 0),
         y: Number(world?.dataset.toolcraftCanvasOffsetY ?? 0),
       },
     };
-  }, sceneSelector);
+  });
 }
 
 export function expectInfiniteCanvasObservation(
@@ -191,7 +197,10 @@ export function expectInfiniteCanvasObservation(
   expect(observation.finiteControlSize).toEqual(null);
   expect(observation.finiteControlsPresent).toBe(false);
   expect(observation.overflow).toBe("visible");
-  if (expectedSceneRect) expect(observation.sceneRect).toEqual(expectedSceneRect);
+  if (expectedSceneRect) {
+    expect(observation.productSceneStatus).toBe("ready");
+    expect(observation.sceneRect).toEqual(expectedSceneRect);
+  }
   expect(Number.isFinite(observation.viewportOffset.x)).toBe(true);
   expect(Number.isFinite(observation.viewportOffset.y)).toBe(true);
 }

package/templates/starter/e2e/browser-orientation-gizmo-evidence-helpers.ts

@@ -26,6 +26,9 @@ import {
   getToolcraftOrientationAxisPosition,
   type ToolcraftOrientationAxis,
 } from "./browser-orientation-gizmo-actions";
+import {
+  expectToolcraftOrientationLiveDragPreconditions,
+} from "./browser-orientation-gizmo-live-preconditions";
 
 export type ToolcraftOrientationBrowserObservation = {
   outputSignature: string;
@@ -222,6 +225,7 @@ export async function expectToolcraftOrientationAxisDrag(
     message,
     options,
   );
+  await expectToolcraftOrientationLiveDragPreconditions(session);
   const before = snapshotToolcraftOutcome(await observe(), message);
 
   validateObservation(before, options);

package/templates/starter/e2e/browser-orientation-gizmo-live-preconditions.ts

@@ -0,0 +1,86 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+import {
+  countToolcraftControlOwnersByTarget,
+  getToolcraftControlFieldByTarget,
+} from "./browser-control-target-helpers";
+import {
+  getToolcraftBrowserProofPage,
+  type ToolcraftBrowserProofSession,
+} from "./browser-proof-session";
+
+const TOOLCRAFT_APP_ROOT_SELECTOR = '[data-slot="toolcraft-runtime-app"]';
+const RENDER_SCALE_TARGET = "canvas.renderScale";
+
+async function expectPausedPlaybackWhenPresent(page: Page): Promise<void> {
+  const root = page.locator(TOOLCRAFT_APP_ROOT_SELECTOR);
+  const play = root.getByRole("button", { name: "Play playback" });
+  const pause = root.getByRole("button", { name: "Pause playback" });
+  const playCount = await play.count();
+  const actionCount = playCount + (await pause.count());
+
+  if (actionCount === 0) return;
+
+  expect(
+    actionCount,
+    "Orientation axis-drag proof requires exactly one standard playback action.",
+  ).toBe(1);
+  expect(
+    playCount,
+    "Orientation axis-drag proof must be paused; Play playback must be visible before its baseline.",
+  ).toBe(1);
+  await expect(play).toBeVisible();
+}
+
+async function readFiniteAriaNumber(
+  slider: Locator,
+  name: "aria-valuemax" | "aria-valuenow",
+): Promise<number> {
+  const raw = await slider.getAttribute(name);
+  const value = raw === null || raw.trim() === "" ? Number.NaN : Number(raw);
+
+  expect(
+    Number.isFinite(value),
+    `Orientation axis-drag proof requires a finite ${name} on canvas.renderScale.`,
+  ).toBe(true);
+  return value;
+}
+
+async function expectMaximumRenderScaleWhenPresent(page: Page): Promise<void> {
+  const ownerCount = await countToolcraftControlOwnersByTarget(
+    page,
+    RENDER_SCALE_TARGET,
+  );
+
+  if (ownerCount === 0) return;
+
+  expect(
+    ownerCount,
+    "Orientation axis-drag proof requires exactly one canvas.renderScale owner.",
+  ).toBe(1);
+  const field = await getToolcraftControlFieldByTarget(
+    page,
+    RENDER_SCALE_TARGET,
+  );
+  const slider = field.getByRole("slider");
+  await expect(
+    slider,
+    "Orientation axis-drag proof requires one canvas.renderScale slider.",
+  ).toHaveCount(1);
+  await expect(slider).toBeVisible();
+
+  const value = await readFiniteAriaNumber(slider, "aria-valuenow");
+  const maximum = await readFiniteAriaNumber(slider, "aria-valuemax");
+  expect(
+    value,
+    "Orientation axis-drag proof requires canvas.renderScale at maximum quality before its baseline.",
+  ).toBe(maximum);
+}
+
+export async function expectToolcraftOrientationLiveDragPreconditions(
+  session: ToolcraftBrowserProofSession,
+): Promise<void> {
+  const page = await getToolcraftBrowserProofPage(session);
+  await expectPausedPlaybackWhenPresent(page);
+  await expectMaximumRenderScaleWhenPresent(page);
+}

package/templates/starter/e2e/browser-runtime-applicability-requirements.ts

@@ -0,0 +1,84 @@
+import type { ResolvedToolcraftAppSchema } from "@repo/toolcraft-runtime";
+
+import type { ToolcraftBrowserRuntimeRequirement } from "../src/app/test-evidence/browser-runtime-contract";
+import {
+  getToolcraftApplicabilityRequirementId,
+  getToolcraftControlApplicabilityCases,
+  type ToolcraftComponentAcceptance,
+  type ToolcraftControlSectionInventoryEntry,
+} from "../src/app/starter-acceptance";
+
+type ApplicabilityAcceptanceSource = Pick<
+  ToolcraftComponentAcceptance,
+  "browserTestName" | "id" | "kind" | "target"
+>;
+
+const layoutOnlyEvidenceTypes = new Set<
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>(["discrete-slider-layout", "segmented-control-layout"]);
+
+export function expandToolcraftControlApplicabilityRequirements({
+  entry,
+  schema,
+  sectionInventory,
+  templates,
+}: Readonly<{
+  entry: ApplicabilityAcceptanceSource;
+  schema?: Pick<ResolvedToolcraftAppSchema, "panels">;
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
+  templates: readonly ToolcraftBrowserRuntimeRequirement[];
+}>): ToolcraftBrowserRuntimeRequirement[] {
+  if (!schema || entry.kind !== "control" || !entry.target) {
+    return [...templates];
+  }
+
+  const cases = getToolcraftControlApplicabilityCases({
+    schema,
+    sectionInventory,
+    target: entry.target,
+  });
+
+  if (cases.length === 0) {
+    return [...templates];
+  }
+
+  const hasOutcomeRequirement = templates.some(
+    (requirement) => !layoutOnlyEvidenceTypes.has(requirement.evidenceType),
+  );
+
+  return cases.flatMap((applicabilityCase) => {
+    const visibilityRequirement = {
+      evidenceType:
+        applicabilityCase.expectation === "hidden"
+          ? ("control-applicability-hidden" as const)
+          : ("control-applicability-visible" as const),
+      requirementId: getToolcraftApplicabilityRequirementId(
+        entry.id,
+        applicabilityCase,
+      ),
+      target: entry.target,
+      testName: entry.browserTestName,
+    };
+
+    if (applicabilityCase.expectation === "hidden") {
+      return [visibilityRequirement];
+    }
+
+    if (!hasOutcomeRequirement) {
+      throw new Error(
+        `Visible applicability case for ${entry.id} has no product outcome requirement.`,
+      );
+    }
+
+    return [
+      visibilityRequirement,
+      ...templates.map((requirement) => ({
+        ...requirement,
+        requirementId: getToolcraftApplicabilityRequirementId(
+          requirement.requirementId,
+          applicabilityCase,
+        ),
+      })),
+    ];
+  });
+}

package/templates/starter/e2e/browser-runtime-evidence-reporter.ts

@@ -19,7 +19,10 @@ import {
   type ToolcraftBrowserRuntimeRequirement,
   type ToolcraftBrowserRuntimeTest,
 } from "../src/app/test-evidence/browser-runtime-contract";
-import { starterAcceptance } from "../src/app/starter-acceptance";
+import {
+  starterAcceptance,
+  starterControlSectionInventory,
+} from "../src/app/starter-acceptance";
 import { starterPerformance } from "../src/app/starter-performance";
 import { starterSchema } from "../src/app/starter-schema";
 import {
@@ -166,7 +169,11 @@ export default class ToolcraftBrowserRuntimeEvidenceReporter implements Reporter
     this.performanceSchema = this.performanceSchemaOverride ?? starterSchema;
     this.acceptanceRequirements =
       this.acceptanceRequirementsOverride ??
-      deriveToolcraftBrowserRuntimeRequirements(starterAcceptance, starterSchema);
+      deriveToolcraftBrowserRuntimeRequirements(
+        starterAcceptance,
+        starterSchema,
+        starterControlSectionInventory,
+      );
     this.canonicalPaths = deriveToolcraftPerformancePaths(
       this.performanceSchema,
       this.performanceConfig,