@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/ui/components/primitives/scroll-fade-render.tsx

@@ -3,7 +3,11 @@
 import { useCallback } from "react";
 import type { Ref } from "react";
 import { cn } from "../../lib/utils";
-import type { ScrollFadeSide, ScrollFadeViewportStyle } from "./scroll-fade-types";
+import type {
+  ScrollFadeScrollBoundaryBehavior,
+  ScrollFadeSide,
+  ScrollFadeViewportStyle,
+} from "./scroll-fade-types";
 
 export function useScrollFadeViewportAttachment({
   setViewportElement,
@@ -36,6 +40,7 @@ export function ScrollFadeViewport({
   className,
   isHorizontal,
   props,
+  scrollBoundaryBehavior,
   side,
   viewportStyle,
   viewportVisible,
@@ -48,6 +53,7 @@ export function ScrollFadeViewport({
   props: Omit<React.ComponentProps<"div">, "children" | "className" | "style" | "ref"> & {
     "data-slot"?: string;
   };
+  scrollBoundaryBehavior: ScrollFadeScrollBoundaryBehavior;
   side: ScrollFadeSide;
   viewportStyle: ScrollFadeViewportStyle;
   viewportVisible: boolean;
@@ -59,9 +65,12 @@ export function ScrollFadeViewport({
       {...viewportProps}
       className={cn(
         isHorizontal ? "overflow-x-auto overflow-y-hidden" : "overflow-x-hidden overflow-y-auto",
-        "overscroll-contain",
+        scrollBoundaryBehavior === "chain"
+          ? "overscroll-auto"
+          : "overscroll-contain",
         className,
       )}
+      data-scroll-boundary-behavior={scrollBoundaryBehavior}
       data-side={side}
       data-slot={dataSlot ?? "scroll-fade-viewport"}
       data-scroll-fade-viewport=""

package/templates/ui/components/primitives/scroll-fade-types.ts

@@ -4,6 +4,7 @@ import type { CSSProperties, ReactNode, Ref } from "react";
 export type ScrollFadeSide = "top" | "bottom" | "left" | "right";
 export type ScrollFadeIntensity = "normal" | "medium" | "dense";
 export type ScrollFadePreset = "compact" | "default" | "large";
+export type ScrollFadeScrollBoundaryBehavior = "contain" | "chain";
 export type ScrollFadeVisibilityMode = "overflow" | "terminal";
 
 export interface ScrollFadeProps extends Omit<
@@ -21,6 +22,7 @@ export interface ScrollFadeProps extends Omit<
   intensity?: ScrollFadeIntensity;
   interactionWatch?: readonly unknown[];
   preset?: ScrollFadePreset;
+  scrollBoundaryBehavior?: ScrollFadeScrollBoundaryBehavior;
   side?: ScrollFadeSide;
   showOppositeSide?: boolean;
   visibilityMode?: ScrollFadeVisibilityMode;

package/templates/ui/components/primitives/scroll-fade.test.tsx

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ScrollFade } from "./scroll-fade";
+import type { ScrollFadePreset } from "./scroll-fade-types";
+
+afterEach(() => {
+  cleanup();
+});
+
+function getViewport(container: HTMLElement): HTMLElement {
+  const viewport = container.querySelector<HTMLElement>(
+    '[data-slot="scroll-fade-viewport"]',
+  );
+
+  if (!viewport) {
+    throw new Error("ScrollFade viewport was not rendered.");
+  }
+
+  return viewport;
+}
+
+describe("ScrollFade scroll boundary behavior", () => {
+  it("contains nested scrolling by default", () => {
+    const { container } = render(
+      <ScrollFade>
+        <div>Content</div>
+      </ScrollFade>,
+    );
+    const viewport = getViewport(container);
+
+    expect(viewport.className).toContain("overscroll-contain");
+    expect(viewport.className).not.toContain("overscroll-auto");
+    expect(viewport.dataset.scrollBoundaryBehavior).toBe("contain");
+  });
+
+  it.each([
+    ["compact", undefined],
+    ["default", undefined],
+    ["large", undefined],
+    ["default", 73],
+  ] satisfies readonly [ScrollFadePreset, number | undefined][])(
+    "chains %s image-list scrolling for height %s",
+    (preset, height) => {
+      const { container } = render(
+        <ScrollFade
+          height={height}
+          preset={preset}
+          scrollBoundaryBehavior="chain"
+        >
+          <div>Image grid</div>
+        </ScrollFade>,
+      );
+      const viewport = getViewport(container);
+
+      expect(viewport.className).toContain("overscroll-auto");
+      expect(viewport.className).not.toContain("overscroll-contain");
+      expect(viewport.dataset.scrollBoundaryBehavior).toBe("chain");
+    },
+  );
+});

package/templates/ui/components/primitives/scroll-fade.tsx

@@ -19,6 +19,7 @@ export function ScrollFade({
   intensity,
   interactionWatch = [],
   preset,
+  scrollBoundaryBehavior = "contain",
   side = "bottom",
   showOppositeSide = false,
   style,
@@ -61,6 +62,7 @@ export function ScrollFade({
         className={className}
         isHorizontal={isHorizontal}
         props={props}
+        scrollBoundaryBehavior={scrollBoundaryBehavior}
         side={side}
         viewportStyle={viewportStyle}
         viewportVisible={viewportVisible}

package/templates/ui/index.ts

@@ -27,6 +27,7 @@ export {
   Select,
   Slider,
   Switch,
+  TabsControl,
   TextInput,
   Vector,
 } from "./components/controls";

package/templates/runtime/react/controls-panel/layout/controls-panel-collapse-storage.ts

@@ -1,131 +0,0 @@
-import type {
-  ResolvedToolcraftAppSchema,
-  ToolcraftControlSectionSchema,
-  ToolcraftControlSchema,
-} from "../../../schema/types";
-import {
-  readToolcraftLocalStorageValue,
-  removeToolcraftLocalStorageValue,
-} from "../../app-shell/storage-key-migration";
-
-const controlsPanelSectionCollapseStorageVersion = 1;
-
-export function getControlsPanelSectionCollapseKey({
-  entries,
-  section,
-  sectionIndex,
-}: {
-  entries: readonly [string, ToolcraftControlSchema][];
-  section: ToolcraftControlSectionSchema;
-  sectionIndex: number;
-}): string {
-  const targets = entries.map(([id, control]) => `${id}:${control.target}`).join("|");
-
-  return `${section.title ?? "section"}:${sectionIndex}:${targets}`;
-}
-
-function hashStorageKeyPart(value: string): string {
-  let hash = 2166136261;
-
-  for (let index = 0; index < value.length; index += 1) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-
-  return (hash >>> 0).toString(36);
-}
-
-export function getControlsPanelSectionCollapseStorageKey(
-  schema: ResolvedToolcraftAppSchema,
-): string | null {
-  const controlsPanel = schema.panels.controls;
-
-  if (!controlsPanel) {
-    return null;
-  }
-
-  const appIdentity =
-    schema.persistence.storage === "localStorage"
-      ? `persistence:${schema.persistence.key}:v${schema.persistence.version}`
-      : JSON.stringify({
-          sections: controlsPanel.sections.map((section) => ({
-            controls: Object.entries(section.controls).map(([id, control]) => ({
-              id,
-              label: control.label,
-              target: control.target,
-              type: control.type,
-            })),
-            title: section.title,
-          })),
-          title: controlsPanel.title,
-        });
-
-  return `toolcraft:ui:controls-panel-sections:${hashStorageKeyPart(appIdentity)}:v${controlsPanelSectionCollapseStorageVersion}`;
-}
-
-export function readControlsPanelCollapsedSections(
-  storageKey: string | null,
-): Record<string, boolean> {
-  if (!storageKey || typeof window === "undefined") {
-    return {};
-  }
-
-  try {
-    const rawValue = readToolcraftLocalStorageValue(storageKey);
-
-    if (!rawValue) {
-      return {};
-    }
-
-    const payload: unknown = JSON.parse(rawValue);
-
-    if (
-      !payload ||
-      typeof payload !== "object" ||
-      !("version" in payload) ||
-      payload.version !== controlsPanelSectionCollapseStorageVersion ||
-      !("collapsed" in payload) ||
-      !Array.isArray(payload.collapsed)
-    ) {
-      return {};
-    }
-
-    return Object.fromEntries(
-      payload.collapsed
-        .filter((item): item is string => typeof item === "string" && item.length > 0)
-        .map((item) => [item, true]),
-    );
-  } catch {
-    return {};
-  }
-}
-
-export function writeControlsPanelCollapsedSections(
-  storageKey: string | null,
-  collapsedSectionByKey: Record<string, boolean>,
-): void {
-  if (!storageKey || typeof window === "undefined") {
-    return;
-  }
-
-  const collapsed = Object.entries(collapsedSectionByKey)
-    .filter(([, collapsedValue]) => collapsedValue)
-    .map(([key]) => key);
-
-  try {
-    if (collapsed.length === 0) {
-      removeToolcraftLocalStorageValue(storageKey);
-      return;
-    }
-
-    window.localStorage.setItem(
-      storageKey,
-      JSON.stringify({
-        collapsed,
-        version: controlsPanelSectionCollapseStorageVersion,
-      }),
-    );
-  } catch {
-    // UI preferences are best-effort; panel interaction stays authoritative.
-  }
-}

package/templates/runtime/testing/performance-browser-policy.test.ts

@@ -1,81 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { defineToolcraft } from "../schema/define-toolcraft";
-import {
-  collectToolcraftPerformanceSensitiveControls,
-  collectToolcraftUnclassifiedPerformanceControls,
-  defineToolcraftPerformance,
-  defaultToolcraftBrowserCheckPolicy,
-  type ToolcraftBrowserCheckPolicy,
-  validateToolcraftPerformanceCoverage,
-} from "./performance";
-import {
-  ordinarySliderSchema,
-} from "./performance-test-fixtures";
-
-describe("Toolcraft performance browser policy contract", () => {
-  it("defaults browser checks to agent browser with Playwright fallback", () => {
-    const config = defineToolcraftPerformance({
-      rendererStrategy: "none",
-      rendererWorkload: "none",
-      scenarios: [
-        {
-          automated: true,
-          automatedTestName: "perf: opacity drag stays responsive",
-          browser: true,
-          browserTestName: "browser perf: opacity drag stays responsive",
-          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
-          controlLabel: "Opacity",
-          expectedObservable: "Dragging Opacity stays responsive.",
-          fixture: "opacity responsiveness fixture",
-          id: "opacity-drag",
-          interaction: "control-drag",
-          target: "render.opacity",
-          workload: false,
-        },
-      ],
-      usesCustomRenderer: false,
-      workloadTargets: [],
-    });
-
-    expect(config.browserCheckPolicy).toEqual(defaultToolcraftBrowserCheckPolicy);
-    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toEqual([]);
-  });
-
-  it("rejects explicit Playwright-first browser check policies", () => {
-    const config = defineToolcraftPerformance({
-      browserCheckPolicy: {
-        fallbackRunner: "playwright",
-        fallbackWhen: ["agent-browser-unavailable"],
-        preferredRunner: "playwright",
-      } as unknown as ToolcraftBrowserCheckPolicy,
-      rendererStrategy: "none",
-      rendererWorkload: "none",
-      scenarios: [
-        {
-          automated: true,
-          automatedTestName: "perf: opacity drag stays responsive",
-          browser: true,
-          browserTestName: "browser perf: opacity drag stays responsive",
-          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
-          controlLabel: "Opacity",
-          expectedObservable: "Dragging Opacity stays responsive.",
-          fixture: "opacity responsiveness fixture",
-          id: "opacity-drag",
-          interaction: "control-drag",
-          target: "render.opacity",
-          workload: false,
-        },
-      ],
-      usesCustomRenderer: false,
-      workloadTargets: [],
-    });
-
-    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toEqual(
-      expect.arrayContaining([
-        'browserCheckPolicy.preferredRunner must be "agent-browser" so AI agents use their controlled browser before fallback automation.',
-        'browserCheckPolicy.fallbackWhen must include "ci" so CI/non-agent automation has a portable performance runner.',
-      ]),
-    );
-  });
-});

package/templates/runtime/testing/performance-browser-policy.ts

@@ -1,102 +0,0 @@
-import type {
-  ToolcraftBrowserCheckFallbackCondition,
-  ToolcraftBrowserCheckFallbackRunner,
-  ToolcraftBrowserCheckPolicy,
-  ToolcraftBrowserCheckPreferredRunner,
-  ToolcraftPerformanceConfig,
-} from "./performance-types";
-
-export const defaultToolcraftBrowserCheckPolicy: ToolcraftBrowserCheckPolicy = {
-  fallbackRunner: "playwright",
-  fallbackWhen: ["agent-browser-unavailable", "ci"],
-  preferredRunner: "agent-browser",
-};
-
-export function defineToolcraftPerformance(
-  config: ToolcraftPerformanceConfig,
-): ToolcraftPerformanceConfig & { browserCheckPolicy: ToolcraftBrowserCheckPolicy } {
-  return {
-    ...config,
-    browserCheckPolicy: {
-      ...defaultToolcraftBrowserCheckPolicy,
-      ...config.browserCheckPolicy,
-      fallbackWhen:
-        config.browserCheckPolicy?.fallbackWhen ??
-        defaultToolcraftBrowserCheckPolicy.fallbackWhen,
-    },
-  };
-}
-
-const browserCheckPreferredRunners = new Set<ToolcraftBrowserCheckPreferredRunner>([
-  "agent-browser",
-]);
-
-const browserCheckFallbackRunners = new Set<ToolcraftBrowserCheckFallbackRunner>([
-  "playwright",
-]);
-
-const browserCheckFallbackConditions = new Set<ToolcraftBrowserCheckFallbackCondition>([
-  "agent-browser-unavailable",
-  "ci",
-]);
-
-export function getBrowserCheckPolicyErrors(config: ToolcraftPerformanceConfig): string[] {
-  const errors: string[] = [];
-  const policy = config.browserCheckPolicy ?? defaultToolcraftBrowserCheckPolicy;
-  const fallbackWhen = policy.fallbackWhen as unknown;
-
-  if (
-    !browserCheckPreferredRunners.has(
-      policy.preferredRunner as ToolcraftBrowserCheckPreferredRunner,
-    )
-  ) {
-    errors.push(
-      'browserCheckPolicy.preferredRunner must be "agent-browser" so AI agents use their controlled browser before fallback automation.',
-    );
-  }
-
-  if (
-    !browserCheckFallbackRunners.has(
-      policy.fallbackRunner as ToolcraftBrowserCheckFallbackRunner,
-    )
-  ) {
-    errors.push(
-      'browserCheckPolicy.fallbackRunner must be "playwright" so generated apps keep a portable CI/non-agent fallback.',
-    );
-  }
-
-  if (!Array.isArray(fallbackWhen)) {
-    errors.push(
-      'browserCheckPolicy.fallbackWhen must include "agent-browser-unavailable" and "ci".',
-    );
-    return errors;
-  }
-
-  for (const condition of fallbackWhen) {
-    if (
-      !browserCheckFallbackConditions.has(
-        condition as ToolcraftBrowserCheckFallbackCondition,
-      )
-    ) {
-      errors.push(
-        `browserCheckPolicy.fallbackWhen contains unsupported condition "${String(
-          condition,
-        )}".`,
-      );
-    }
-  }
-
-  if (!fallbackWhen.includes("agent-browser-unavailable")) {
-    errors.push(
-      'browserCheckPolicy.fallbackWhen must include "agent-browser-unavailable" so Playwright is only used when no agent browser exists.',
-    );
-  }
-
-  if (!fallbackWhen.includes("ci")) {
-    errors.push(
-      'browserCheckPolicy.fallbackWhen must include "ci" so CI/non-agent automation has a portable performance runner.',
-    );
-  }
-
-  return errors;
-}

package/templates/runtime/testing/performance-budget-validation.ts

@@ -1,84 +0,0 @@
-import type {
-  ToolcraftPerformanceBudget,
-  ToolcraftPerformanceScenario,
-} from "./performance-types";
-
-const maxPerformanceBudgetCaps: Required<ToolcraftPerformanceBudget> = {
-  maxExportMs: 8000,
-  maxFrameGapMs: 120,
-  maxInteractionMs: 2000,
-  maxLongTaskMs: 250,
-  maxPreviewMs: 2000,
-  maxRenderMs: 2000,
-};
-
-export function hasAnyBudget(budget: ToolcraftPerformanceBudget): boolean {
-  return Object.values(budget).some((value) => typeof value === "number" && value > 0);
-}
-
-export function hasPositiveBudgetField(
-  budget: ToolcraftPerformanceBudget,
-  field: keyof ToolcraftPerformanceBudget,
-): boolean {
-  const value = budget[field];
-  return typeof value === "number" && value > 0;
-}
-
-export function getMissingInteractionBudgetFields(
-  scenario: ToolcraftPerformanceScenario,
-): string[] {
-  switch (scenario.interaction) {
-    case "animation-frame":
-      return hasPositiveBudgetField(scenario.budget, "maxFrameGapMs")
-        ? hasPositiveBudgetField(scenario.budget, "maxLongTaskMs")
-          ? []
-          : ["maxLongTaskMs"]
-        : hasPositiveBudgetField(scenario.budget, "maxLongTaskMs")
-          ? ["maxFrameGapMs"]
-          : ["maxFrameGapMs", "maxLongTaskMs"];
-    case "animation-viewport-drag":
-    case "mask-drag":
-    case "viewport-zoom-stress":
-      return (["maxInteractionMs", "maxFrameGapMs", "maxLongTaskMs"] as const).filter(
-        (field) => !hasPositiveBudgetField(scenario.budget, field),
-      );
-    case "viewport-stability":
-      return hasPositiveBudgetField(scenario.budget, "maxFrameGapMs")
-        ? []
-        : ["maxFrameGapMs"];
-    case "control-change":
-    case "control-drag":
-    case "media-import":
-      return (["maxInteractionMs", "maxFrameGapMs"] as const).filter(
-        (field) => !hasPositiveBudgetField(scenario.budget, field),
-      );
-    case "export-copy":
-      return hasPositiveBudgetField(scenario.budget, "maxExportMs") ? [] : ["maxExportMs"];
-    case "preview-render":
-      return hasPositiveBudgetField(scenario.budget, "maxPreviewMs") ||
-        hasPositiveBudgetField(scenario.budget, "maxRenderMs")
-        ? []
-        : ["maxPreviewMs or maxRenderMs"];
-    case "timeline-playback":
-      return (["maxFrameGapMs", "maxLongTaskMs"] as const).filter(
-        (field) => !hasPositiveBudgetField(scenario.budget, field),
-      );
-    case "timeline-scrub":
-      return (["maxInteractionMs", "maxFrameGapMs", "maxLongTaskMs"] as const).filter(
-        (field) => !hasPositiveBudgetField(scenario.budget, field),
-      );
-  }
-}
-
-export function getBudgetCapErrors(scenario: ToolcraftPerformanceScenario): string[] {
-  return Object.entries(scenario.budget).flatMap(([field, value]) => {
-    const budgetField = field as keyof ToolcraftPerformanceBudget;
-    const cap = maxPerformanceBudgetCaps[budgetField];
-
-    if (typeof value !== "number" || value <= cap) {
-      return [];
-    }
-
-    return [`${scenario.id} ${budgetField} budget must be <= ${cap}ms, received ${value}ms.`];
-  });
-}

package/templates/runtime/testing/performance-control-classification.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { defineToolcraft } from "../schema/define-toolcraft";
-import {
-  collectToolcraftPerformanceSensitiveControls,
-  collectToolcraftUnclassifiedPerformanceControls,
-  defineToolcraftPerformance,
-  defaultToolcraftBrowserCheckPolicy,
-  type ToolcraftBrowserCheckPolicy,
-  validateToolcraftPerformanceCoverage,
-} from "./performance";
-import {
-  ordinarySliderSchema,
-  testSchema,
-} from "./performance-test-fixtures";
-
-describe("Toolcraft performance control classification contract", () => {
-  it("collects performance-sensitive controls from schema", () => {
-    expect(collectToolcraftPerformanceSensitiveControls(testSchema)).toEqual([
-      expect.objectContaining({
-        controlId: "density",
-        target: "render.density",
-      }),
-    ]);
-  });
-
-  it("does not classify every slider as workload-sensitive", () => {
-    expect(collectToolcraftPerformanceSensitiveControls(ordinarySliderSchema)).toEqual([]);
-  });
-
-  it("collects explicit workload controls even when labels do not match fallback keywords", () => {
-    const explicitWorkloadSchema = defineToolcraft({
-      canvas: {
-        enabled: true,
-        sizing: { mode: "intrinsic-media" },
-      },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                complexity: {
-                  defaultValue: 4,
-                  label: "Complexity",
-                  max: 12,
-                  min: 1,
-                  performanceReason: "Complexity changes the number of render passes.",
-                  performanceRole: "workload",
-                  target: "render.complexity",
-                  type: "slider",
-                },
-              },
-            },
-          ],
-          title: "Runtime Controls",
-        },
-      },
-    });
-
-    expect(collectToolcraftPerformanceSensitiveControls(explicitWorkloadSchema)).toEqual([
-      expect.objectContaining({
-        controlId: "complexity",
-        target: "render.complexity",
-      }),
-    ]);
-  });
-
-  it("collects visible controls without explicit performance classification", () => {
-    const unclassifiedSchema = defineToolcraft({
-      canvas: {
-        enabled: true,
-        renderScale: true,
-        sizing: { mode: "intrinsic-media" },
-      },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                mode: {
-                  defaultValue: "soft",
-                  label: "Mode",
-                  options: [
-                    { label: "Soft", value: "soft" },
-                    { label: "Sharp", value: "sharp" },
-                  ],
-                  target: "render.mode",
-                  type: "select",
-                },
-              },
-            },
-          ],
-          title: "Runtime Controls",
-        },
-        timeline: { mode: "playback" },
-      },
-    });
-
-    expect(collectToolcraftUnclassifiedPerformanceControls(unclassifiedSchema)).toEqual([
-      expect.objectContaining({
-        controlId: "mode",
-        target: "render.mode",
-      }),
-    ]);
-  });
-});