@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/src/app/starter-performance.lifecycle.test.ts

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+import {
+  TOOLCRAFT_DELIVERY_VERIFICATION_COMMAND,
+  TOOLCRAFT_FULL_PERFORMANCE_VERIFICATION_COMMAND,
+} from "../../scripts/toolcraft-performance-authority-policy.mjs";
+import { requiredPackageScriptNames } from "../../scripts/toolcraft-integrity-policy.mjs";
+
+import { projectDir } from "./starter-performance-test-utils";
+
+const expectedRequiredPackageScriptNames = [
+  "ai:check", "build", "dev", "dev:restart", "docs:check", "preview",
+  "preview:restart", "test", "test:browser", "typecheck", "verify:delivery",
+  "verify:kernel", "verify:perf", "verify:receipt",
+] as const;
+
+describe("Toolcraft starter performance lifecycle", () => {
+  it("publishes separate functional acceptance and performance gates", () => {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
+      scripts?: Record<string, string>;
+    };
+    const generatedAppTestScript =
+      packageJson.scripts?.["test:generated"] ?? packageJson.scripts?.test;
+
+    expect(requiredPackageScriptNames).toEqual(expectedRequiredPackageScriptNames);
+    for (const scriptName of requiredPackageScriptNames) {
+      expect(packageJson.scripts?.[scriptName]).toBeDefined();
+    }
+    for (const removed of [
+      "test:delivery", "verify:final", "verify:perf:record-iteration",
+      "verify:quick", "verify:ui",
+    ]) {
+      expect(packageJson.scripts?.[removed]).toBeUndefined();
+    }
+    expect(packageJson.scripts?.["ai:check"]).toBe(
+      "node scripts/check-toolcraft-code-health.mjs",
+    );
+    const sourceTestScript =
+      "node scripts/check-toolcraft-docs.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs";
+    const generatedTestScript =
+      "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs";
+    if (packageJson.scripts?.["test:generated"]) {
+      expect(packageJson.scripts.test).toBe(sourceTestScript);
+      expect(packageJson.scripts["test:generated"]).toBe(generatedTestScript);
+    } else {
+      expect(packageJson.scripts?.test).toBe(generatedTestScript);
+    }
+
+    expect(
+      generatedAppTestScript,
+      "Generated app tests must invoke the Toolcraft integrity checker.",
+    ).toContain("node scripts/check-toolcraft-integrity.mjs");
+    expect(
+      packageJson.scripts?.["test:browser"],
+      "Generated apps must keep measured performance and kernel benchmark scenarios out of the default browser acceptance gate.",
+    ).toBe(
+      'playwright install chromium && playwright test --grep-invert "browser perf:|toolcraft kernel:"',
+    );
+    expect(packageJson.scripts?.["test:browser:perf"]).toBeUndefined();
+    const performanceRunner = readFileSync(
+      join(projectDir, "scripts/run-browser-performance.mjs"),
+      "utf8",
+    );
+    const receiptModule = readFileSync(
+      join(projectDir, "scripts/toolcraft-verification-receipt.mjs"),
+      "utf8",
+    );
+    const deliveryRunner = readFileSync(
+      join(projectDir, "scripts/run-delivery-verification.mjs"),
+      "utf8",
+    );
+    const deliveryLifecycle = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-lifecycle.mjs"),
+      "utf8",
+    );
+    const proofProcess = readFileSync(
+      join(projectDir, "scripts/toolcraft-proof-process.mjs"),
+      "utf8",
+    );
+    const deliveryReceiptModule = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-receipt.mjs"),
+      "utf8",
+    );
+    expect(performanceRunner).toContain("runToolcraftFullPerformanceCertification");
+    expect(performanceRunner).not.toContain("runToolcraftDeliveryVerification");
+    expect(performanceRunner).not.toContain("--reason=");
+    expect(performanceRunner).toContain("withToolcraftVerificationLock");
+    expect(performanceRunner).toContain("measureToolcraftPerformanceCheckpoint");
+    expect(performanceRunner).not.toContain("writeCheckpointFile");
+    expect(receiptModule).not.toContain(
+      "export async function writeToolcraftPerformanceReceipt",
+    );
+    expect(deliveryReceiptModule).not.toContain(
+      "export async function writeToolcraftDeliveryReceipt",
+    );
+    expect(packageJson.scripts?.["verify:delivery"]).toBe(
+      "node scripts/run-delivery-verification.mjs",
+    );
+    expect(deliveryRunner).toContain("executeToolcraftDeliveryLifecycle");
+    expect(deliveryRunner).toContain("withToolcraftVerificationLock");
+    expect(deliveryLifecycle).toContain("executeToolcraftDeliveryLifecycleCore");
+    expect(deliveryLifecycle).toContain("executeToolcraftDeliveryPlan");
+    expect(deliveryLifecycle).not.toContain("runToolcraftFullPerformanceCertification");
+    expect(deliveryLifecycle).not.toContain("measureToolcraftPerformanceCheckpoint");
+    expect(proofProcess).toContain('from "cross-spawn"');
+    expect(proofProcess).toContain("ensureToolcraftChromium");
+    const deliverySources = `${deliveryRunner}\n${deliveryLifecycle}`;
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:quick")');
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:final")');
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:perf")');
+    expect(packageJson.scripts?.["verify:perf"]).toBe(
+      "node scripts/run-browser-performance.mjs",
+    );
+    expect(packageJson.scripts?.["verify:perf:playwright"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:refresh"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:record-agent-browser"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:record-iteration"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:kernel"]).toBe(
+      "node scripts/run-kernel-benchmarks.mjs",
+    );
+    const deliveryExecutor = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-executor.mjs"),
+      "utf8",
+    );
+    const targetedPerformanceExecution = readFileSync(
+      join(projectDir, "scripts/toolcraft-targeted-performance-execution.mjs"),
+      "utf8",
+    );
+    expect(
+      deliveryExecutor.match(
+        /TOOLCRAFT_PERFORMANCE_FIXTURE_SELECTOR: "development"/g,
+      ),
+    ).toBeNull();
+    expect(
+      targetedPerformanceExecution.match(
+        /TOOLCRAFT_PERFORMANCE_FIXTURE_SELECTOR: "development"/g,
+      ),
+    ).toHaveLength(1);
+    expect(packageJson.scripts?.["verify:perf:record-exemption"]).toBeUndefined();
+    expect(receiptModule).not.toContain('command === "record-iteration"');
+    expect(packageJson.scripts?.["verify:receipt"]).toContain("validate");
+  });
+
+  it("documents adaptive delivery routing without command-shaped authority", () => {
+    const routedDocs = [
+      "AGENTS.md",
+      "docs/toolcraft/README.md",
+      "docs/toolcraft/acceptance-testing.md",
+      "docs/toolcraft/agent-worklog.md",
+      "docs/toolcraft/assembly-workflow.md",
+      "docs/toolcraft/core/performance.md",
+      "docs/toolcraft/performance.md",
+      "docs/toolcraft/workflow.md",
+    ];
+    const docSources = routedDocs.map((relativePath) => ({
+      relativePath,
+      source: readFileSync(join(projectDir, relativePath), "utf8"),
+    }));
+
+    for (const { relativePath, source } of docSources) {
+      expect(source, relativePath).toMatch(/first (?:product )?delivery/i);
+      expect(source, relativePath).toMatch(/later[^\n]{0,40}delivery/i);
+      expect(source, relativePath).toMatch(
+        /(?:performance complaint|localized complaint)/i,
+      );
+      expect(source, relativePath).toMatch(
+        /(?:full audit|complete (?:performance )?(?:audit|review))/i,
+      );
+      expect(source, relativePath).toContain(
+        TOOLCRAFT_DELIVERY_VERIFICATION_COMMAND,
+      );
+      expect(source, relativePath).toContain(
+        TOOLCRAFT_FULL_PERFORMANCE_VERIFICATION_COMMAND,
+      );
+    }
+
+    const allRoutedDocs = docSources.map(({ source }) => source).join("\n");
+    const nonAgentsDocs = docSources
+      .filter(({ relativePath }) => relativePath !== "AGENTS.md")
+      .map(({ source }) => source)
+      .join("\n");
+    expect(nonAgentsDocs).not.toMatch(/\bTier (?:N|[0-4])\b/);
+    expect(allRoutedDocs).not.toMatch(
+      /verify:quick|verify:ui|verify:final|verify:perf:record-iteration|test:delivery/,
+    );
+    expect(allRoutedDocs).not.toMatch(
+      /verify:delivery\s+--|--tier|--unit-test|--browser-test|--performance-test/,
+    );
+    expect(allRoutedDocs).not.toMatch(
+      /performance modules require protected evidence|(?:add|run)[^\n]*affected path performance checks[^\n]*when an edit changes|during development[^\n]*affected performance scenarios|targeted performance scenarios only for touched/i,
+    );
+    expect(allRoutedDocs).toMatch(
+      /only exact request authority[^\n]*measured targeted performance/i,
+    );
+    expect(allRoutedDocs).not.toMatch(/matching (?:executed )?`?Run\b`?/i);
+    expect(allRoutedDocs).not.toContain("app-performance-impact.json");
+  });
+
+  it("keeps workload guidance structural instead of prescribing domain constants", () => {
+    const monorepoRoot = join(projectDir, "..");
+    const documentation = [
+      join(projectDir, "AGENTS.md"),
+      join(projectDir, "docs/toolcraft/core/performance.md"),
+      join(projectDir, "docs/toolcraft/performance.md"),
+      join(projectDir, "docs/toolcraft/renderer-technique.md"),
+      join(projectDir, "docs/toolcraft/assembly-workflow.md"),
+      join(projectDir, "docs/toolcraft/workflow.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-core-performance.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-performance.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-renderer-technique.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-assembly-workflow.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-workflow.md"),
+    ]
+      .filter((filePath) => existsSync(filePath))
+      .map((filePath) => readFileSync(filePath, "utf8"))
+      .join("\n");
+
+    expect(documentation).toMatch(/reachable controls and inputs/i);
+    expect(documentation).toMatch(/workload dimensions and enforced boundaries/i);
+    expect(documentation).toMatch(
+      /render-plan assessment(?: and| with).*protected kernel benchmark/i,
+    );
+    expect(documentation).toMatch(/derived paths and combined fixtures/i);
+    expect(documentation).not.toMatch(/50_000|1_000\s+lines|1920x1080-equivalent/i);
+    expect(documentation).not.toMatch(/classif(?:y|ication)[^\n]*(?:key name|key-name|keyword)/i);
+    expect(documentation).not.toMatch(
+      /bitmap-media|halftone|per-pixel|max text length|max media size/i,
+    );
+    expect(documentation).toMatch(/exact normalized development pressure `0\.8`/i);
+    expect(documentation).toMatch(/exhaustive-discrete/i);
+    expect(documentation).toMatch(/match(?:es)? every option one-to-one/i);
+    expect(documentation).toMatch(/toolcraftDiscreteCombinationBudget/);
+    expect(documentation).toMatch(/toolcraftDiscreteDimensionBudget/);
+    expect(documentation).toMatch(/bypasses search budgets because no (?:combination )?search runs/i);
+    expect(documentation).toMatch(/planning error/i);
+    expect(documentation).toMatch(/TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE/);
+    expect(documentation).toMatch(/exactly one scenario (?:for|per) (?:every )?(?:canonical |derived )?path/i);
+    expect(documentation).toMatch(/targeted failure[^\n]*(?:not|rather than)[^\n]*full[- ]suite/i);
+    expect(documentation).toMatch(
+      /first product delivery[^\n]*full functional acceptance[^\n]*no measured performance/i,
+    );
+    expect(documentation).toMatch(/later delivery[^\n]*functional-targeted/i);
+    expect(documentation).toMatch(
+      /complaint[^\n]*one-authority-targeted-performance-iteration/i,
+    );
+    expect(documentation).toMatch(/full-performance/i);
+    expect(documentation).toMatch(/needs-agent-judgment/i);
+    expect(documentation).toMatch(
+      /later[^\n]{0,40}delivery[^\n]*(?:same )?bare command[^\n]*exact ownership/i,
+    );
+    expect(documentation).not.toMatch(
+      /first stable[^\n]*(?:full performance|full checkpoint|baseline)/i,
+    );
+    expect(documentation).not.toMatch(/compatibility mode|legacy preferred|legacy-only/i);
+    expect(documentation).not.toMatch(/loadProfile|smoothTargetRatio/i);
+    expect(documentation).not.toMatch(/without exceeding development pressure/i);
+    expect(documentation).not.toMatch(/\breachableValues\b/);
+  });
+});

package/templates/starter/src/app/test-evidence/browser-runtime-contract.ts

@@ -20,13 +20,14 @@ export const TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_TYPES = [
   "canvas-render-scale-backing",
   "command-side-effect",
   "compound-control-part",
-  "conditional-control-hidden",
-  "conditional-control-visible",
+  "control-applicability-hidden",
+  "control-applicability-visible",
   "discrete-slider-layout",
   "exported-artifact",
   "infinity-mode-restoration",
   "infinity-scene-bounds-image-export",
   "infinity-scene-bounds-video-export",
+  "image-export-artifact",
   "layer-grouping",
   "layer-media-lifecycle",
   "layer-reorder",
@@ -78,6 +79,7 @@ export const TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_TYPES = [
   "timeline-pause-resume",
   "timeline-rendered-frame",
   "timeline-scrub",
+  "video-export-artifact",
   "viewport-side-effect",
 ] as const;
 

package/templates/starter/src/routes/index.tsx

@@ -8,6 +8,8 @@ export function StarterHome(): React.JSX.Element {
       canvasContent={starterComposition.canvasContent}
       className="h-dvh min-h-dvh"
       controlRenderers={starterComposition.controlRenderers}
+      exportRenderer={starterComposition.exportRenderer}
+      infiniteCanvasContent={starterComposition.infiniteCanvasContent}
       modelPresentation={starterComposition.modelPresentation}
       onPanelAction={starterComposition.onPanelAction}
       renderDefaultCanvasMedia={starterComposition.renderDefaultCanvasMedia}

package/templates/ui/components/composites/tabs.tsx

@@ -26,7 +26,7 @@ const tabsListVariants = cva(
       },
       variant: {
         control:
-          "w-full rounded-md border border-[color:color-mix(in_oklab,var(--border)_12%,transparent)] bg-[color:color-mix(in_oklab,var(--input)_5%,transparent)] p-0 text-[color:color-mix(in_oklab,var(--foreground)_72%,transparent)] [&>[data-slot=tabs-trigger]]:relative [&>[data-slot=tabs-trigger]:has(+[data-slot=tabs-trigger])]:border-r-0 [&>[data-slot=tabs-trigger][data-active]+[data-slot=tabs-trigger]]:border-l-[color:color-mix(in_oklab,var(--border)_10%,transparent)]",
+          "w-full rounded-md p-0 text-[color:color-mix(in_oklab,var(--foreground)_72%,transparent)] [&>[data-slot=tabs-trigger]]:relative [&>[data-slot=tabs-trigger]:has(+[data-slot=tabs-trigger])]:border-r-0 [&>[data-slot=tabs-trigger][data-active]+[data-slot=tabs-trigger]]:border-l-[color:color-mix(in_oklab,var(--border)_10%,transparent)]",
         default: "bg-transparent",
         line: "gap-1 bg-transparent pl-0",
       },
@@ -69,7 +69,7 @@ function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {
       className={cn(
         "relative inline-flex h-[var(--tabs-trigger-height,calc(100%-1px))] flex-1 cursor-pointer items-center justify-center gap-1.5 rounded-md border border-transparent px-1.5 py-0.5 text-xs font-medium whitespace-nowrap text-[color:color-mix(in_oklab,var(--foreground)_60%,transparent)] transition-none group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start group-data-vertical/tabs:py-[calc(--spacing(1.25))] hover:text-[color:var(--foreground)] focus-visible:border-[color:var(--ring)] focus-visible:ring-[3px] focus-visible:ring-[color:color-mix(in_oklab,var(--ring)_50%,transparent)] focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 dark:text-[color:var(--muted-foreground)] dark:hover:text-[color:var(--foreground)] [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
         "group-data-[size=header-lg]/tabs-list:px-2.5 group-data-[size=header-lg]/tabs-list:text-xs-plus",
-        "group-data-[variant=control]/tabs-list:min-w-0 group-data-[variant=control]/tabs-list:rounded-none group-data-[variant=control]/tabs-list:border-[color:color-mix(in_oklab,var(--border)_12%,transparent)] group-data-[variant=control]/tabs-list:bg-transparent group-data-[variant=control]/tabs-list:px-2 group-data-[variant=control]/tabs-list:transition-all group-data-[variant=control]/tabs-list:first:rounded-l-md group-data-[variant=control]/tabs-list:last:rounded-r-md group-data-[variant=control]/tabs-list:hover:bg-[color:color-mix(in_oklab,var(--foreground)_10%,transparent)] group-data-[variant=control]/tabs-list:hover:text-[color:var(--foreground)] group-data-[variant=control]/tabs-list:data-active:hover:bg-[color:color-mix(in_oklab,var(--link)_12%,transparent)] group-data-[variant=control]/tabs-list:data-active:hover:text-[color:var(--foreground)]",
+        "group-data-[variant=control]/tabs-list:h-full group-data-[variant=control]/tabs-list:min-w-0 group-data-[variant=control]/tabs-list:rounded-none group-data-[variant=control]/tabs-list:border-[color:color-mix(in_oklab,var(--border)_12%,transparent)] group-data-[variant=control]/tabs-list:bg-[color:color-mix(in_oklab,var(--input)_5%,transparent)] group-data-[variant=control]/tabs-list:px-2 group-data-[variant=control]/tabs-list:transition-all group-data-[variant=control]/tabs-list:first:rounded-l-md group-data-[variant=control]/tabs-list:last:rounded-r-md group-data-[variant=control]/tabs-list:hover:bg-[color:color-mix(in_oklab,var(--foreground)_10%,transparent)] group-data-[variant=control]/tabs-list:hover:text-[color:var(--foreground)] group-data-[variant=control]/tabs-list:data-active:border-[color:color-mix(in_oklab,var(--border)_10%,transparent)] group-data-[variant=control]/tabs-list:data-active:bg-[color:color-mix(in_oklab,var(--link)_12%,transparent)] group-data-[variant=control]/tabs-list:data-active:text-[color:var(--foreground)] group-data-[variant=control]/tabs-list:data-active:hover:bg-[color:color-mix(in_oklab,var(--link)_12%,transparent)] group-data-[variant=control]/tabs-list:data-active:hover:text-[color:var(--foreground)]",
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:border-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent",
         `${activeSelectedItemClassName} dark:data-active:text-[color:var(--foreground)]`,
         "after:absolute after:bg-[color:var(--foreground)] after:opacity-0 after:transition-none group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[var(--tabs-indicator-bottom,-5px)] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",

package/templates/ui/components/controls/collection-actions/collection-item-groups.test.tsx

@@ -0,0 +1,38 @@
+// @vitest-environment jsdom
+
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { CollectionItemGroups } from "./collection-item-groups";
+
+describe("CollectionItemGroups", () => {
+  it("renders a line only before adjacent logical groups", () => {
+    const { container } = render(
+      <CollectionItemGroups>
+        <div>Strength A</div>
+        <div>Strength B</div>
+      </CollectionItemGroups>,
+    );
+    const groups = container.querySelectorAll(
+      '[data-slot="collection-item-group"]',
+    );
+
+    expect(groups).toHaveLength(2);
+    expect(groups[0]?.className).not.toContain("border-t");
+    expect(groups[1]?.className).toContain("border-t");
+    expect(container.textContent).not.toMatch(/Item 1|Item 2/u);
+  });
+
+  it("renders no line for one logical group", () => {
+    const { container } = render(
+      <CollectionItemGroups>
+        <div>Only group</div>
+      </CollectionItemGroups>,
+    );
+
+    expect(
+      container.querySelector('[data-slot="collection-item-group"]')
+        ?.className,
+    ).not.toContain("border-t");
+  });
+});

package/templates/ui/components/controls/collection-actions/collection-item-groups.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import * as React from "react";
+
+export type CollectionItemGroupsProps = {
+  children: React.ReactNode;
+};
+
+export function CollectionItemGroups({
+  children,
+}: CollectionItemGroupsProps): React.JSX.Element {
+  const groups = React.Children.toArray(children);
+
+  return (
+    <div className="min-w-0" data-slot="collection-item-groups">
+      {groups.map((group, index) => {
+        const key =
+          React.isValidElement(group) && group.key !== null ? group.key : index;
+
+        return (
+          <div
+            className={
+              index === 0
+                ? "min-w-0"
+                : "mt-[18px] min-w-0 border-t border-[color:color-mix(in_oklab,var(--border)_5%,transparent)] pt-[18px]"
+            }
+            data-slot="collection-item-group"
+            key={key}
+          >
+            {group}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/ui/components/controls/collection-actions/index.ts

@@ -2,3 +2,5 @@
 
 export { CollectionActionsControl } from "./collection-actions-control";
 export type { CollectionActionsControlProps } from "./collection-actions-control";
+export { CollectionItemGroups } from "./collection-item-groups";
+export type { CollectionItemGroupsProps } from "./collection-item-groups";

package/templates/ui/components/controls/file-drop/file-drop-collection-control.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import * as React from "react";
+
+import { cn } from "../../../lib/utils";
+import {
+  CollectionActionsControl,
+  CollectionItemGroups,
+} from "../collection-actions";
+import { Field } from "../../primitives";
+import { FileDropPresentationMessages } from "./file-drop-presentation-messages";
+import type {
+  FileDropCollectionActions,
+  FileDropPresentation,
+  FileDropPresentationEntry,
+  FileDropPresentationItem,
+} from "./file-drop-types";
+
+type FileDropCollectionSlotControl = (
+  props: Readonly<{
+    collectionSlot: true;
+    onFilesSelect: (files: File[]) => void;
+    presentation: FileDropPresentation<string, unknown, unknown>;
+  }>,
+) => React.JSX.Element;
+
+type FileDropCollectionControlProps = {
+  actions: FileDropCollectionActions;
+  canRemoveAttachedItem: boolean;
+  entries: readonly FileDropPresentationEntry[];
+  onFilesSelect?: (files: File[]) => void;
+  onRemoveAttachedItem: (item: FileDropPresentationItem, index: number) => void;
+  presentation: FileDropPresentation<string, unknown, unknown>;
+  SlotControl: FileDropCollectionSlotControl;
+};
+
+export function FileDropCollectionControl({
+  actions,
+  canRemoveAttachedItem,
+  entries,
+  onFilesSelect,
+  onRemoveAttachedItem,
+  presentation,
+  SlotControl,
+}: FileDropCollectionControlProps): React.JSX.Element {
+  const pendingBaseCountRef = React.useRef(entries.length);
+  const [hasPendingSlot, setHasPendingSlot] = React.useState(
+    () => entries.length === 0,
+  );
+  const itemLabel = actions.itemLabel ?? "file";
+
+  React.useEffect(() => {
+    if (entries.length === 0 && !hasPendingSlot) {
+      pendingBaseCountRef.current = 0;
+      setHasPendingSlot(true);
+    } else if (hasPendingSlot && entries.length > pendingBaseCountRef.current) {
+      setHasPendingSlot(false);
+    }
+  }, [entries.length, hasPendingSlot]);
+
+  const canAddSlot = actions.canAdd !== false && !hasPendingSlot;
+  const canRemoveSlot = hasPendingSlot
+    ? entries.length > 0
+    : entries.length > 0 && canRemoveAttachedItem;
+
+  function renderSlot(
+    item: FileDropPresentationItem | null,
+    index: number,
+    key: React.Key,
+  ): React.JSX.Element {
+    const itemContent = item ? actions.renderItemContent?.(item, index) : null;
+
+    return (
+      <div
+        className={cn("min-w-0", itemContent && "space-y-4")}
+        data-slot="file-drop-collection-slot"
+        key={key}
+      >
+        <SlotControl
+          collectionSlot
+          onFilesSelect={(files) => onFilesSelect?.(files.slice(0, 1))}
+          presentation={{
+            ...presentation,
+            allowsFileBatch: false,
+            allowsFolderSelection: false,
+            emptyTitle: `Upload ${itemLabel} ${index + 1}`,
+            feedback: undefined,
+            items: item ? [item] : [],
+            secondaryActions: [],
+            status: undefined,
+          }}
+        />
+        {itemContent}
+      </div>
+    );
+  }
+
+  return (
+    <Field className="min-w-0" style={{ gap: "6px" }}>
+      <CollectionActionsControl
+        addLabel={actions.addLabel}
+        canAdd={canAddSlot}
+        canRemove={canRemoveSlot}
+        name={actions.name}
+        onAdd={() => {
+          pendingBaseCountRef.current = entries.length;
+          setHasPendingSlot(true);
+        }}
+        onRemove={() => {
+          if (hasPendingSlot) {
+            setHasPendingSlot(false);
+            return;
+          }
+
+          const entry = entries[entries.length - 1];
+
+          if (entry) {
+            onRemoveAttachedItem(entry.item, entry.sourceIndex);
+          }
+        }}
+        removeLabel={actions.removeLabel}
+      />
+      <CollectionItemGroups>
+        {entries.map((entry, index) =>
+          renderSlot(entry.item, index, entry.key),
+        )}
+        {hasPendingSlot
+          ? renderSlot(null, entries.length, `pending-${entries.length}`)
+          : null}
+      </CollectionItemGroups>
+      <FileDropPresentationMessages
+        feedback={presentation.feedback}
+        status={presentation.status}
+      />
+    </Field>
+  );
+}