@usefragments/core 1.10.2 → 2.0.0

package/src/registry-install-plan.ts

@@ -7,6 +7,7 @@ import {
   type RegistryDependency,
   type RegistryFile,
   type RegistryInstallReceipt,
+  type RegistryManifest,
 } from "./registry.js";
 
 export interface RegistryWritePlan {
@@ -16,6 +17,40 @@ export interface RegistryWritePlan {
   componentId?: string;
 }
 
+export interface RegistryInstallSelectionInput {
+  manifest: RegistryManifest;
+  requestedComponents: readonly string[];
+  all?: boolean;
+}
+
+export interface RegistryInstallSelection {
+  /** Component ids as resolved from the request (canonical casing), sorted. */
+  requested: string[];
+  /** Components pulled in through `internalDependencies`, sorted; never overlaps `requested`. */
+  implied: string[];
+  /** The full install set: `requested` ∪ `implied`, sorted. */
+  components: string[];
+}
+
+export interface RegistryInstallSourcesInput extends RegistryInstallSelectionInput {
+  includeTests?: boolean;
+}
+
+export interface RegistryInstallSourceFile {
+  file: RegistryFile;
+  componentId?: string;
+}
+
+export interface RegistryInstallSources {
+  selection: RegistryInstallSelection;
+  /** True when the selection covers every component (package entrypoints are installed too). */
+  complete: boolean;
+  /** Source files the install writes, sorted by path and unique. */
+  files: RegistryInstallSourceFile[];
+  /** Registry file paths the install needs bodies for (includes entrypoint-only paths). */
+  paths: string[];
+}
+
 export interface BuildRegistryInstallPlanInput {
   artifact: RegistryArtifact;
   requestedComponents: readonly string[];
@@ -26,6 +61,8 @@ export interface BuildRegistryInstallPlanInput {
 
 export interface RegistryInstallPlan {
   componentNames: string[];
+  requestedComponents: string[];
+  impliedComponents: string[];
   plans: RegistryWritePlan[];
   dependencies: RegistryDependency[];
 }
@@ -48,6 +85,10 @@ function joinRegistryPath(...parts: string[]): string {
   return normalizeRegistryRepoPath(parts.filter(Boolean).join("/"));
 }
 
+function sortStrings(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
 export function sourceToRegistryTargetPath(targetRoot: string, sourcePath: string): string {
   const source = normalizeRegistryRepoPath(sourcePath);
   const withoutSrc = source.startsWith("src/") ? source.slice("src/".length) : source;
@@ -57,54 +98,100 @@ export function sourceToRegistryTargetPath(targetRoot: string, sourcePath: strin
   );
 }
 
-export function selectedRegistryComponentNames(
-  artifact: RegistryArtifact,
-  requested: readonly string[],
-  all: boolean | undefined
-): string[] {
-  if (all || requested.includes("*")) {
-    return Object.keys(artifact.manifest.components).sort((left, right) =>
-      left.localeCompare(right)
+/**
+ * Resolve a requested component id to its canonical id. Exact matches win; otherwise a
+ * unique case-insensitive match is accepted (`button` → `Button`).
+ */
+export function resolveRegistryComponentId(manifest: RegistryManifest, requested: string): string {
+  if (manifest.components[requested]) return requested;
+  const lowered = requested.toLowerCase();
+  const matches = Object.keys(manifest.components).filter((name) => name.toLowerCase() === lowered);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous registry component ${requested}: matches ${matches.sort().join(", ")}`
     );
   }
-  if (requested.length === 0) {
-    throw new Error("Choose at least one registry component to install.");
+  throw new Error(`Unknown registry component ${requested}`);
+}
+
+/** Close a component set over `internalDependencies`, transitively. */
+export function expandRegistryComponentClosure(
+  manifest: RegistryManifest,
+  names: readonly string[]
+): string[] {
+  const closure = new Set<string>();
+  const queue = [...names];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    if (closure.has(name)) continue;
+    const component = manifest.components[name];
+    if (!component) throw new Error(`Unknown registry component ${name}`);
+    closure.add(name);
+    queue.push(...component.internalDependencies);
   }
-  for (const name of requested) {
-    if (!artifact.manifest.components[name]) {
-      throw new Error(`Unknown registry component ${name}`);
-    }
+  return sortStrings(closure);
+}
+
+export function resolveRegistryInstallSelection(
+  input: RegistryInstallSelectionInput
+): RegistryInstallSelection {
+  const { manifest } = input;
+  if (input.all || input.requestedComponents.includes("*")) {
+    const components = sortStrings(Object.keys(manifest.components));
+    return { requested: components, implied: [], components };
   }
-  return [...new Set(requested)].sort();
+  if (input.requestedComponents.length === 0) {
+    throw new Error("Choose at least one registry component to install.");
+  }
+  const requested = sortStrings(
+    input.requestedComponents.map((name) => resolveRegistryComponentId(manifest, name))
+  );
+  const components = expandRegistryComponentClosure(manifest, requested);
+  const requestedSet = new Set(requested);
+  return {
+    requested,
+    implied: components.filter((name) => !requestedSet.has(name)),
+    components,
+  };
 }
 
 function installsCompleteRegistry(
-  artifact: RegistryArtifact,
+  manifest: RegistryManifest,
   componentNames: readonly string[]
 ): boolean {
-  const allComponents = Object.keys(artifact.manifest.components);
+  const allComponents = Object.keys(manifest.components);
   return (
     componentNames.length === allComponents.length &&
     allComponents.every((name) => componentNames.includes(name))
   );
 }
 
+/** Authoring-only roles: shipped in the artifact, written only with `includeTests`. */
+const AUTHORING_ROLES: ReadonlySet<RegistryFile["role"]> = new Set(["test", "story", "example"]);
+
 function shouldInstallFile(file: RegistryFile, includeTests: boolean | undefined): boolean {
   if (includeTests) return true;
-  return file.role !== "test" && file.role !== "story";
+  return !AUTHORING_ROLES.has(file.role);
 }
 
 function dependencyKey(dependency: RegistryDependency): string {
   return `${dependency.type}:${dependency.name}:${dependency.versionRange}:${dependency.optional ? 1 : 0}`;
 }
 
+/**
+ * npm dependencies the install needs: the selected components' own dependencies, plus the
+ * whole package's list when the install is complete (package entrypoints ship too).
+ */
 export function collectRegistryInstallDependencies(
-  artifact: RegistryArtifact,
+  artifact: Pick<RegistryArtifact, "manifest">,
   componentNames: readonly string[]
 ): RegistryDependency[] {
   const dependencies = new Map<string, RegistryDependency>();
-  for (const dependency of artifact.manifest.dependencies) {
-    dependencies.set(dependencyKey(dependency), dependency);
+  if (installsCompleteRegistry(artifact.manifest, componentNames)) {
+    for (const dependency of artifact.manifest.dependencies) {
+      dependencies.set(dependencyKey(dependency), dependency);
+    }
   }
   for (const name of componentNames) {
     const component = artifact.manifest.components[name];
@@ -115,29 +202,53 @@ export function collectRegistryInstallDependencies(
   return [...dependencies.values()].sort((left, right) => left.name.localeCompare(right.name));
 }
 
-function collectComponentWritePlan(args: {
-  artifact: RegistryArtifact;
-  componentNames: readonly string[];
-  targetPath: string;
-  includeTests?: boolean;
-}): RegistryWritePlan[] {
-  const writes = new Map<string, RegistryWritePlan>();
-  for (const componentName of args.componentNames) {
-    const component = args.artifact.manifest.components[componentName];
-    for (const file of component.files) {
-      if (!shouldInstallFile(file, args.includeTests)) continue;
-      const content = args.artifact.files[file.path];
-      if (!content) throw new Error(`Artifact is missing file content for ${file.path}`);
-      const target = sourceToRegistryTargetPath(args.targetPath, file.path);
-      writes.set(target, {
-        path: target,
-        sourcePath: file.path,
-        content: content.content,
-        componentId: component.componentId,
-      });
+function packageFileEntries(manifest: RegistryManifest): Map<string, RegistryFile | null> {
+  const packageFiles = new Map<string, RegistryFile | null>(
+    manifest.packageFiles.map((file) => [file.path, file])
+  );
+  for (const entrypoint of manifest.entrypoints) {
+    if (!packageFiles.has(entrypoint.sourcePath)) packageFiles.set(entrypoint.sourcePath, null);
+  }
+  return packageFiles;
+}
+
+/**
+ * Everything an install needs from the registry, computed from the manifest alone so a
+ * sharded reader can fetch only the bodies the plan will write.
+ */
+export function resolveRegistryInstallSources(
+  input: RegistryInstallSourcesInput
+): RegistryInstallSources {
+  const { manifest } = input;
+  const selection = resolveRegistryInstallSelection(input);
+  const complete = installsCompleteRegistry(manifest, selection.components);
+  const files = new Map<string, RegistryInstallSourceFile>();
+  const paths = new Set<string>();
+  const add = (file: RegistryFile, componentId?: string) => {
+    if (!shouldInstallFile(file, input.includeTests)) return;
+    if (!files.has(file.path)) files.set(file.path, { file, componentId });
+    paths.add(file.path);
+  };
+
+  if (complete) {
+    for (const [path, file] of packageFileEntries(manifest)) {
+      if (file) add(file);
+      else paths.add(path);
     }
+  } else {
+    for (const file of manifest.baseFiles) add(file);
   }
-  return [...writes.values()].sort((left, right) => left.path.localeCompare(right.path));
+  for (const name of selection.components) {
+    const component = manifest.components[name];
+    for (const file of component.files) add(file, component.componentId);
+  }
+
+  return {
+    selection,
+    complete,
+    files: [...files.values()].sort((left, right) => left.file.path.localeCompare(right.file.path)),
+    paths: sortStrings(paths),
+  };
 }
 
 function rewriteInstalledPackagePath(value: string): string {
@@ -191,55 +302,19 @@ function rewriteInstalledPackageJson(content: string): string {
   return `${JSON.stringify(installed, null, 2)}\n`;
 }
 
-function collectPackageWritePlan(args: {
-  artifact: RegistryArtifact;
-  targetPath: string;
-  includeTests?: boolean;
-}): RegistryWritePlan[] {
-  const writes = new Map<string, RegistryWritePlan>();
-  const packageFiles = new Map(
-    args.artifact.manifest.packageFiles.map((file) => [file.path, file])
-  );
-  for (const entrypoint of args.artifact.manifest.entrypoints) {
-    const file = packageFiles.get(entrypoint.sourcePath);
-    if (file) continue;
-    const content = args.artifact.files[entrypoint.sourcePath];
-    if (!content) throw new Error(`Artifact is missing file content for ${entrypoint.sourcePath}`);
-    packageFiles.set(entrypoint.sourcePath, {
-      path: entrypoint.sourcePath,
-      role: "barrel",
-      sha256: content.sha256,
-      size: content.size,
-      contentType: content.contentType,
-      contentRef: `sha256:${content.sha256}`,
-    });
-  }
-
-  for (const file of packageFiles.values()) {
-    if (!shouldInstallFile(file, args.includeTests)) continue;
-    const content = args.artifact.files[file.path];
-    if (!content) throw new Error(`Artifact is missing file content for ${file.path}`);
-    const target = sourceToRegistryTargetPath(args.targetPath, file.path);
-    writes.set(target, {
-      path: target,
-      sourcePath: file.path,
-      content:
-        file.path === "package.json"
-          ? rewriteInstalledPackageJson(content.content)
-          : content.content,
-    });
-  }
-
-  return [...writes.values()].sort((left, right) => left.path.localeCompare(right.path));
+function contentFor(artifact: RegistryArtifact, path: string): string {
+  const content = artifact.files[path];
+  if (!content) throw new Error(`Artifact is missing file content for ${path}`);
+  return content.content;
 }
 
 function generatedIndexPlan(args: {
   componentNames: readonly string[];
   targetPath: string;
-  artifact: RegistryArtifact;
+  manifest: RegistryManifest;
 }): RegistryWritePlan {
   const lines = args.componentNames.map((name) => {
-    const component = args.artifact.manifest.components[name];
+    const component = args.manifest.components[name];
     const exportName = component.exports[0]?.name ?? component.name;
     return `export { ${exportName} } from "./components/${component.componentId}";`;
   });
@@ -268,37 +343,53 @@ function dedupePlans(plans: readonly RegistryWritePlan[]): RegistryWritePlan[] {
 export function buildRegistryInstallPlan(
   input: BuildRegistryInstallPlanInput
 ): RegistryInstallPlan {
+  const { manifest } = input.artifact;
   const targetPath = assertPortableRegistryPath(input.targetPath, "Registry target");
-  const componentNames = selectedRegistryComponentNames(
-    input.artifact,
-    input.requestedComponents,
-    input.all
-  );
+  const sources = resolveRegistryInstallSources({
+    manifest,
+    requestedComponents: input.requestedComponents,
+    all: input.all,
+    includeTests: input.includeTests,
+  });
+  const componentNames = sources.selection.components;
   const dependencies = collectRegistryInstallDependencies(input.artifact, componentNames);
-  const isCompleteInstall = installsCompleteRegistry(input.artifact, componentNames);
-  const hasPackageRoot = input.artifact.manifest.entrypoints.some(
-    (entrypoint) => entrypoint.specifier === "."
-  );
+  const hasPackageRoot = manifest.entrypoints.some((entrypoint) => entrypoint.specifier === ".");
+
+  const writes: RegistryWritePlan[] = sources.files.map(({ file, componentId }) => {
+    const raw = contentFor(input.artifact, file.path);
+    return {
+      path: sourceToRegistryTargetPath(targetPath, file.path),
+      sourcePath: file.path,
+      content:
+        sources.complete && file.path === "package.json" ? rewriteInstalledPackageJson(raw) : raw,
+      ...(componentId && { componentId }),
+    };
+  });
+  if (sources.complete) {
+    for (const entrypoint of manifest.entrypoints) {
+      if (writes.some((plan) => plan.sourcePath === entrypoint.sourcePath)) continue;
+      writes.push({
+        path: sourceToRegistryTargetPath(targetPath, entrypoint.sourcePath),
+        sourcePath: entrypoint.sourcePath,
+        content: contentFor(input.artifact, entrypoint.sourcePath),
+      });
+    }
+  }
+
   const plans = dedupePlans([
-    ...(isCompleteInstall
-      ? collectPackageWritePlan({
-          artifact: input.artifact,
-          targetPath,
-          includeTests: input.includeTests,
-        })
-      : []),
-    ...collectComponentWritePlan({
-      artifact: input.artifact,
-      componentNames,
-      targetPath,
-      includeTests: input.includeTests,
-    }),
-    ...(isCompleteInstall && hasPackageRoot
+    ...writes,
+    ...(sources.complete && hasPackageRoot
       ? []
-      : [generatedIndexPlan({ artifact: input.artifact, componentNames, targetPath })]),
+      : [generatedIndexPlan({ manifest, componentNames, targetPath })]),
   ]);
 
-  return { componentNames, plans, dependencies };
+  return {
+    componentNames,
+    requestedComponents: sources.selection.requested,
+    impliedComponents: sources.selection.implied,
+    plans,
+    dependencies,
+  };
 }
 
 export function buildRegistryInstallReceipt(args: {

package/src/registry-shards.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  REGISTRY_INDEX_SCHEMA_VERSION,
+  REGISTRY_MANIFEST_SCHEMA_VERSION,
+  REGISTRY_POINTER_SCHEMA_VERSION,
+  REGISTRY_SHARD_SCHEMA_VERSION,
+  assembleRegistryArtifact,
+  buildRegistryArtifact,
+  buildRegistryFile,
+  buildRegistryPointer,
+  defaultRegistryShardPath,
+  registryIndexSchema,
+  registryPointerSchema,
+  registryShardSchema,
+  registryShardsForPaths,
+  shardRegistryArtifact,
+  type RegistryArtifact,
+  type RegistryManifestDraft,
+} from "./registry.js";
+import {
+  buildRegistryInstallPlan,
+  resolveRegistryComponentId,
+  resolveRegistryInstallSelection,
+  resolveRegistryInstallSources,
+} from "./registry-install-plan.js";
+
+function file(path: string, content: string, role: "source" | "style" | "token" | "test") {
+  return buildRegistryFile({ path, role, content, contentType: "text/plain" });
+}
+
+function kit(): RegistryArtifact {
+  const index = file("src/index.ts", 'export { Button } from "./components/Button";\n', "source");
+  const globals = file("src/styles/globals.scss", '@use "../tokens/variables";\n', "style");
+  const variables = file("src/tokens/_variables.scss", ":root { --fui-x: 1; }\n", "token");
+  const button = file("src/components/Button/index.tsx", "export const Button = 1;\n", "source");
+  const buttonStyle = file("src/components/Button/Button.module.scss", ".b {}\n", "style");
+  const buttonTest = file("src/components/Button/Button.test.tsx", "test\n", "test");
+  const text = file("src/components/Text/index.tsx", "export const Text = 1;\n", "source");
+  const card = file("src/components/Card/index.tsx", "export const Card = 1;\n", "source");
+  const util = file("src/utils/label.ts", "export const label = 1;\n", "source");
+
+  const component = (
+    componentId: string,
+    files: Array<{ metadata: ReturnType<typeof file>["metadata"] }>,
+    internalDependencies: string[] = []
+  ) => ({
+    componentId,
+    publicRef: `acme-ui:${componentId}`,
+    name: componentId,
+    files: files.map((entry) => entry.metadata),
+    internalDependencies,
+    runtimeDependencies: [
+      { name: `dep-${componentId}`, versionRange: "^1", type: "runtime" as const },
+    ],
+  });
+
+  const manifest: RegistryManifestDraft = {
+    schemaVersion: REGISTRY_MANIFEST_SCHEMA_VERSION,
+    registryId: "acme-ui",
+    name: "Acme UI",
+    channel: "stable",
+    version: "1.0.0",
+    generatedAt: "2026-06-14T12:00:00.000Z",
+    source: { kind: "manual", label: "fixture" },
+    packageFiles: [index.metadata],
+    baseFiles: [globals.metadata, variables.metadata],
+    entrypoints: [{ specifier: ".", sourcePath: "src/index.ts" }],
+    components: {
+      Button: component("Button", [button, buttonStyle, buttonTest, variables, util], ["Text"]),
+      Text: component("Text", [text]),
+      Card: component("Card", [card], ["Text"]),
+    },
+    dependencies: [{ name: "shared-dep", versionRange: "^1", type: "runtime" }],
+  };
+
+  return buildRegistryArtifact({
+    manifest,
+    files: [index, globals, variables, button, buttonStyle, buttonTest, text, card, util].map(
+      (entry) => entry.content
+    ),
+  });
+}
+
+describe("sharded registry artifact", () => {
+  it("lays out shards per component and per shared directory", () => {
+    expect(defaultRegistryShardPath("src/components/Button/index.tsx")).toBe(
+      "components/Button.json"
+    );
+    expect(defaultRegistryShardPath("src/tokens/_variables.scss")).toBe("shared/tokens.json");
+    expect(defaultRegistryShardPath("src/scss.d.ts")).toBe("shared/src.json");
+    expect(defaultRegistryShardPath("package.json")).toBe("shared/package.json");
+    expect(defaultRegistryShardPath("fragments.json")).toBe("shared/package.json");
+  });
+
+  it("splits an artifact into an index and shards that assemble back losslessly", () => {
+    const artifact = kit();
+    const { index, shards } = shardRegistryArtifact(artifact);
+
+    expect(index.schemaVersion).toBe(REGISTRY_INDEX_SCHEMA_VERSION);
+    expect(index.manifest).toEqual(artifact.manifest);
+    expect(Object.keys(index.shards).sort()).toEqual([
+      "components/Button.json",
+      "components/Card.json",
+      "components/Text.json",
+      "shared/src.json",
+      "shared/styles.json",
+      "shared/tokens.json",
+      "shared/utils.json",
+    ]);
+    for (const shard of shards.values()) {
+      expect(shard.schemaVersion).toBe(REGISTRY_SHARD_SCHEMA_VERSION);
+      expect(() => registryShardSchema.parse(shard)).not.toThrow();
+    }
+    expect(() => registryIndexSchema.parse(index)).not.toThrow();
+
+    const paths = Object.keys(artifact.files);
+    const assembled = assembleRegistryArtifact({ index, shards, paths });
+    expect(assembled.files).toEqual(artifact.files);
+    expect(assembled.manifest.registryHash).toBe(artifact.manifest.registryHash);
+  });
+
+  it("names only the shards a path set needs and rejects unknown paths", () => {
+    const { index } = shardRegistryArtifact(kit());
+    expect(
+      registryShardsForPaths(index, ["src/components/Button/index.tsx", "src/utils/label.ts"])
+    ).toEqual(["components/Button.json", "shared/utils.json"]);
+    expect(() => registryShardsForPaths(index, ["src/nope.ts"])).toThrow(/no shard for src\/nope/);
+  });
+
+  it("refuses shard content that does not match the index", () => {
+    const { index, shards } = shardRegistryArtifact(kit());
+    const tampered = new Map(shards);
+    const button = structuredClone(tampered.get("components/Button.json")!);
+    for (const entry of Object.values(button.files)) entry.content = "evil";
+    tampered.set("components/Button.json", button);
+
+    expect(() =>
+      assembleRegistryArtifact({
+        index,
+        shards: tampered,
+        paths: ["src/components/Button/index.tsx"],
+      })
+    ).toThrow(/does not match the index/);
+    expect(() =>
+      assembleRegistryArtifact({
+        index,
+        shards: new Map(),
+        paths: ["src/components/Button/index.tsx"],
+      })
+    ).toThrow(/was not loaded/);
+  });
+
+  it("rejects an index that lists a manifest file in no shard or in two", () => {
+    const { index } = shardRegistryArtifact(kit());
+    const missing = structuredClone(index);
+    delete missing.shards["shared/utils.json"];
+    expect(() => registryIndexSchema.parse(missing)).toThrow(/not carried by any shard/);
+
+    const duplicated = structuredClone(index);
+    duplicated.shards["shared/tokens.json"].push("src/utils/label.ts");
+    expect(() => registryIndexSchema.parse(duplicated)).toThrow(/listed in both/);
+  });
+
+  it("builds a latest.json pointer that names the versioned index by relative path", () => {
+    const { index } = shardRegistryArtifact(kit());
+    const pointer = buildRegistryPointer(index, "1.0.0/index.json");
+    expect(pointer).toEqual({
+      schemaVersion: REGISTRY_POINTER_SCHEMA_VERSION,
+      registryId: "acme-ui",
+      version: "1.0.0",
+      registryHash: index.manifest.registryHash,
+      index: "1.0.0/index.json",
+      generatedAt: "2026-06-14T12:00:00.000Z",
+    });
+    expect(() =>
+      registryPointerSchema.parse({ ...pointer, index: "https://x/index.json" })
+    ).toThrow();
+    expect(() => registryPointerSchema.parse({ ...pointer, index: "../index.json" })).toThrow();
+  });
+});
+
+describe("registry install selection", () => {
+  it("resolves component ids case-insensitively and closes over internal dependencies", () => {
+    const { manifest } = kit();
+    expect(resolveRegistryComponentId(manifest, "button")).toBe("Button");
+    expect(resolveRegistryComponentId(manifest, "Button")).toBe("Button");
+    expect(() => resolveRegistryComponentId(manifest, "nope")).toThrow(
+      /Unknown registry component/
+    );
+
+    const selection = resolveRegistryInstallSelection({
+      manifest,
+      requestedComponents: ["card", "BUTTON"],
+    });
+    expect(selection).toEqual({
+      requested: ["Button", "Card"],
+      implied: ["Text"],
+      components: ["Button", "Card", "Text"],
+    });
+  });
+
+  it("plans base files for partial installs and package files for complete ones", () => {
+    const { manifest } = kit();
+    const partial = resolveRegistryInstallSources({ manifest, requestedComponents: ["Text"] });
+    expect(partial.complete).toBe(false);
+    expect(partial.paths).toEqual([
+      "src/components/Text/index.tsx",
+      "src/styles/globals.scss",
+      "src/tokens/_variables.scss",
+    ]);
+
+    const complete = resolveRegistryInstallSources({
+      manifest,
+      requestedComponents: [],
+      all: true,
+    });
+    expect(complete.complete).toBe(true);
+    expect(complete.paths).toContain("src/index.ts");
+    expect(complete.paths).not.toContain("src/components/Button/Button.test.tsx");
+
+    const withTests = resolveRegistryInstallSources({
+      manifest,
+      requestedComponents: ["Button"],
+      includeTests: true,
+    });
+    expect(withTests.paths).toContain("src/components/Button/Button.test.tsx");
+  });
+
+  it("builds a plan whose dependencies follow the selection", () => {
+    const artifact = kit();
+    const plan = buildRegistryInstallPlan({
+      artifact,
+      requestedComponents: ["button"],
+      targetPath: "src/fragments/ui",
+    });
+    expect(plan.requestedComponents).toEqual(["Button"]);
+    expect(plan.impliedComponents).toEqual(["Text"]);
+    expect(plan.plans.map((entry) => entry.path)).toEqual([
+      "src/fragments/ui/components/Button/Button.module.scss",
+      "src/fragments/ui/components/Button/index.tsx",
+      "src/fragments/ui/components/Text/index.tsx",
+      "src/fragments/ui/index.ts",
+      "src/fragments/ui/styles/globals.scss",
+      "src/fragments/ui/tokens/_variables.scss",
+      "src/fragments/ui/utils/label.ts",
+    ]);
+    // Partial installs carry only the selected components' dependencies …
+    expect(plan.dependencies.map((dependency) => dependency.name)).toEqual([
+      "dep-Button",
+      "dep-Text",
+    ]);
+    // … complete installs add the package-level list.
+    const all = buildRegistryInstallPlan({
+      artifact,
+      requestedComponents: [],
+      all: true,
+      targetPath: "src/fragments/ui",
+    });
+    expect(all.dependencies.map((dependency) => dependency.name)).toContain("shared-dep");
+    expect(all.plans.map((entry) => entry.path)).toContain("src/fragments/ui/index.ts");
+  });
+});