@usefragments/core 1.0.0

package/src/local-canonical.ts

@@ -0,0 +1,102 @@
+import type { ContractCanonicalMappingInput } from "./contract/index.js";
+import type { GovernanceConfig } from "./governance.js";
+
+export interface LocalCanonicalResolveRule {
+  tag: string;
+  role?: string;
+  inputType?: string;
+}
+
+export interface LocalCanonicalDeclaration {
+  importPath: string;
+  resolves: readonly LocalCanonicalResolveRule[];
+}
+
+export interface InspectConfig {
+  localCanonical?: Readonly<Record<string, LocalCanonicalDeclaration>>;
+}
+
+interface PreferLibraryRuleConfig {
+  enabled?: boolean;
+  severity?: "error" | "warn" | "info";
+  options?: {
+    canonicalMappings?: unknown[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export function localCanonicalContractMappings(
+  inspect: InspectConfig | null | undefined
+): ContractCanonicalMappingInput[] {
+  return localCanonicalRuleMappings(inspect).map((mapping) => ({
+    component: mapping.htmlEquivalent,
+    canonical: mapping.name,
+    status: "confirmed",
+    importPath: mapping.importPath,
+    resolves: [
+      {
+        tag: mapping.htmlEquivalent,
+        ...(mapping.ariaRole ? { role: mapping.ariaRole } : {}),
+        ...(mapping.htmlType ? { inputType: mapping.htmlType } : {}),
+      },
+    ],
+  }));
+}
+
+export function governanceConfigWithLocalCanonical(
+  config: GovernanceConfig | undefined,
+  inspect: InspectConfig | null | undefined
+): GovernanceConfig | undefined {
+  const localMappings = localCanonicalRuleMappings(inspect);
+  if (localMappings.length === 0) return config;
+
+  const existingRule = readPreferLibraryRule(config);
+  const existingOptions = existingRule.options ?? {};
+  return {
+    ...(config ?? {}),
+    rules: {
+      ...(config?.rules ?? {}),
+      "components/prefer-library": {
+        ...existingRule,
+        enabled: existingRule.enabled ?? true,
+        severity: existingRule.severity ?? "error",
+        options: {
+          ...existingOptions,
+          canonicalMappings: [
+            ...(Array.isArray(existingOptions.canonicalMappings)
+              ? existingOptions.canonicalMappings
+              : []),
+            ...localMappings,
+          ],
+        },
+      },
+    },
+  };
+}
+
+function localCanonicalRuleMappings(inspect: InspectConfig | null | undefined) {
+  return Object.entries(inspect?.localCanonical ?? {}).flatMap(([name, declaration]) =>
+    declaration.resolves.map((rule) => ({
+      name,
+      canonical: name,
+      htmlEquivalent: rule.tag,
+      ...(rule.role ? { ariaRole: rule.role } : {}),
+      ...(rule.inputType ? { htmlType: rule.inputType } : {}),
+      importPath: declaration.importPath,
+      confidence: 1,
+      // Provenance: the user explicitly declared this tag → component mapping
+      // (not an inferred htmlEquivalent), so prefer-library may enforce a
+      // specific interactive tag against this exact (possibly non-Fragments)
+      // component name. See isEnforceableHtmlEquivalent(explicit).
+      declaredHtmlEquivalent: true,
+    }))
+  );
+}
+
+function readPreferLibraryRule(config: GovernanceConfig | undefined): PreferLibraryRuleConfig {
+  const raw = config?.rules?.["components/prefer-library"];
+  return raw && typeof raw === "object" && !Array.isArray(raw)
+    ? (raw as PreferLibraryRuleConfig)
+    : {};
+}

package/src/mcp-snapshot.ts

@@ -0,0 +1,222 @@
+import { z } from 'zod';
+
+export const mcpSnapshotSchemaVersionSchema = z.literal(1);
+
+export const mcpSourceTypeSchema = z.enum([
+  'fragments-json',
+  'cloud',
+  'auto-extract',
+  'custom-json',
+  'bundle',
+]);
+
+export const mcpCapabilitySchema = z.enum([
+  'components',
+  'tokens',
+  'blocks',
+  'graph',
+  'performance',
+]);
+
+export const mcpPerformanceImportSchema = z.object({
+  path: z.string().min(1),
+  bytes: z.number().nonnegative(),
+  percent: z.number().nonnegative(),
+});
+
+export const mcpPerformanceDataSchema = z.object({
+  bundleSize: z.number().nonnegative(),
+  rawSize: z.number().nonnegative(),
+  complexity: z.enum(['lightweight', 'moderate', 'heavy']),
+  budgetPercent: z.number().nonnegative(),
+  overBudget: z.boolean(),
+  measuredAt: z.string().datetime(),
+  imports: z.array(mcpPerformanceImportSchema).optional(),
+});
+
+export const mcpPerformanceSummarySchema = z.object({
+  preset: z.string().min(1),
+  budget: z.number().nonnegative(),
+  total: z.number().int().nonnegative(),
+  overBudget: z.number().int().nonnegative(),
+  tiers: z.record(
+    z.enum(['lightweight', 'moderate', 'heavy']),
+    z.number().int().nonnegative(),
+  ),
+});
+
+export const mcpComponentPropSchema = z.object({
+  type: z.string().min(1),
+  description: z.string().default(''),
+  required: z.boolean().default(false),
+  default: z.unknown().optional(),
+  values: z.array(z.string()).optional(),
+  constraints: z.array(z.string()).optional(),
+});
+
+export const mcpComponentExampleSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  code: z.string().optional(),
+  kind: z.string().optional(),
+});
+
+export const mcpComponentRelationSchema = z.object({
+  componentName: z.string().min(1),
+  componentId: z.string().optional(),
+  relationship: z.string().min(1),
+  note: z.string().optional(),
+  description: z.string().optional(),
+});
+
+export const mcpCompoundChildSchema = z.object({
+  name: z.string().min(1),
+  componentId: z.string().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  accepts: z.array(z.string()).optional(),
+  visibility: z.enum(['public', 'internal']).optional(),
+});
+
+export const mcpGuidancePatternSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+});
+
+export const mcpComponentGuidanceSchema = z.object({
+  when: z.array(z.string()).default([]),
+  whenNot: z.array(z.string()).default([]),
+  guidelines: z.array(z.string()).default([]),
+  accessibility: z.array(z.string()).default([]),
+  usageGuidance: z.string().optional(),
+  dos: z.array(z.string()).default([]),
+  donts: z.array(z.string()).default([]),
+  patterns: z.array(mcpGuidancePatternSchema).default([]),
+});
+
+export const mcpComponentMetadataSchema = z.object({
+  a11yRules: z.array(z.string()).default([]),
+  scenarioTags: z.array(z.string()).default([]),
+});
+
+export const mcpComponentSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().default(''),
+  category: z.string().default('uncategorized'),
+  status: z.string().default('stable'),
+  tags: z.array(z.string()).default([]),
+  props: z.record(z.string(), mcpComponentPropSchema).default({}),
+  propsSummary: z.array(z.string()).default([]),
+  examples: z.array(mcpComponentExampleSchema).default([]),
+  relations: z.array(mcpComponentRelationSchema).default([]),
+  compoundChildren: z.array(mcpCompoundChildSchema).default([]),
+  guidance: mcpComponentGuidanceSchema.default({
+    when: [],
+    whenNot: [],
+    guidelines: [],
+    accessibility: [],
+    dos: [],
+    donts: [],
+    patterns: [],
+  }),
+  sourceType: mcpSourceTypeSchema,
+  sourcePath: z.string().optional(),
+  sourceRepoFullName: z.string().optional(),
+  packageName: z.string().optional(),
+  importPath: z.string().optional(),
+  publicRef: z.string().optional(),
+  publicSlug: z.string().nullable().optional(),
+  isCanonical: z.boolean().optional(),
+  tier: z.string().optional(),
+  parentComponentId: z.string().optional(),
+  parentComponentName: z.string().optional(),
+  performance: mcpPerformanceDataSchema.optional(),
+  metadata: mcpComponentMetadataSchema.default({
+    a11yRules: [],
+    scenarioTags: [],
+  }),
+});
+
+export const mcpBlockSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().default(''),
+  category: z.string().default('uncategorized'),
+  components: z.array(z.string()).default([]),
+  tags: z.array(z.string()).default([]),
+  code: z.string().default(''),
+});
+
+export const mcpTokenSchema = z.object({
+  name: z.string().min(1),
+  category: z.string().min(1),
+  value: z.string().optional(),
+  description: z.string().optional(),
+  path: z.array(z.string()).optional(),
+  type: z.string().optional(),
+});
+
+export const mcpTokenDataSchema = z.object({
+  prefix: z.string(),
+  total: z.number().int().nonnegative(),
+  categories: z.record(z.string(), z.array(mcpTokenSchema)),
+  flat: z.array(mcpTokenSchema).default([]),
+});
+
+export const mcpSnapshotMetadataSchema = z.object({
+  designSystemName: z.string().optional(),
+  packageName: z.string().optional(),
+  importPath: z.string().optional(),
+  revision: z.string().optional(),
+  updatedAt: z.string().optional(),
+});
+
+export const mcpSnapshotSchema = z.object({
+  schemaVersion: mcpSnapshotSchemaVersionSchema,
+  sourceType: mcpSourceTypeSchema,
+  sourceLabel: z.string().min(1),
+  capabilities: z.array(mcpCapabilitySchema),
+  metadata: mcpSnapshotMetadataSchema.default({}),
+  components: z.record(z.string(), mcpComponentSchema),
+  blocks: z.record(z.string(), mcpBlockSchema).optional(),
+  tokens: mcpTokenDataSchema.optional(),
+  graph: z.unknown().optional(),
+  performanceSummary: mcpPerformanceSummarySchema.optional(),
+  packageMap: z.record(z.string(), z.string()).default({}),
+  defaultPackageName: z.string().optional(),
+});
+
+export type McpSnapshotSchemaVersion = z.infer<
+  typeof mcpSnapshotSchemaVersionSchema
+>;
+export type McpSourceType = z.infer<typeof mcpSourceTypeSchema>;
+export type McpCapability = z.infer<typeof mcpCapabilitySchema>;
+export type McpPerformanceImport = z.infer<
+  typeof mcpPerformanceImportSchema
+>;
+export type McpPerformanceData = z.infer<typeof mcpPerformanceDataSchema>;
+export type McpPerformanceSummary = z.infer<
+  typeof mcpPerformanceSummarySchema
+>;
+export type McpComponentProp = z.infer<typeof mcpComponentPropSchema>;
+export type McpComponentExample = z.infer<typeof mcpComponentExampleSchema>;
+export type McpComponentRelation = z.infer<
+  typeof mcpComponentRelationSchema
+>;
+export type McpCompoundChild = z.infer<typeof mcpCompoundChildSchema>;
+export type McpGuidancePattern = z.infer<typeof mcpGuidancePatternSchema>;
+export type McpComponentGuidance = z.infer<
+  typeof mcpComponentGuidanceSchema
+>;
+export type McpComponentMetadata = z.infer<
+  typeof mcpComponentMetadataSchema
+>;
+export type McpComponent = z.infer<typeof mcpComponentSchema>;
+export type McpBlock = z.infer<typeof mcpBlockSchema>;
+export type McpToken = z.infer<typeof mcpTokenSchema>;
+export type McpTokenData = z.infer<typeof mcpTokenDataSchema>;
+export type McpSnapshotMetadata = z.infer<
+  typeof mcpSnapshotMetadataSchema
+>;
+export type McpSnapshot = z.infer<typeof mcpSnapshotSchema>;

package/src/package-identity-match.ts

@@ -0,0 +1,33 @@
+import {
+  canonicalizeOwnedComponentId,
+  canonicalizeOwnedImport,
+  ownedImportEquivalents,
+} from "./package-identity.js";
+
+/** Equality for typed npm import fields; arbitrary strings remain exact. */
+export function ownedImportsEqual(left: string, right: string): boolean {
+  if (left === right) return true;
+  if (ownedImportEquivalents(left).includes(right)) return true;
+  return canonicalizeOwnedImport(left) === canonicalizeOwnedImport(right);
+}
+
+/**
+ * Match an import against a configured package root/subpath while accepting
+ * every signed legacy/current spelling of that root.
+ */
+export function ownedImportMatchesRoot(imported: string, configuredRoot: string): boolean {
+  for (const equivalent of ownedImportEquivalents(configuredRoot)) {
+    if (imported === equivalent || imported.startsWith(`${equivalent}/`)) {
+      return true;
+    }
+  }
+
+  const canonicalImported = canonicalizeOwnedImport(imported);
+  const canonicalRoot = canonicalizeOwnedImport(configuredRoot);
+  return canonicalImported === canonicalRoot || canonicalImported.startsWith(`${canonicalRoot}/`);
+}
+
+/** Equality for the package-name half of typed `package#Component` ids. */
+export function ownedComponentIdsEqual(left: string, right: string): boolean {
+  return canonicalizeOwnedComponentId(left) === canonicalizeOwnedComponentId(right);
+}

package/src/package-identity.generated.ts

@@ -0,0 +1,233 @@
+// This file is generated by scripts/generate-owned-package-identity-module.mjs.
+// Edit owned-package-identities.json, then regenerate. Do not edit by hand.
+
+export const OWNED_PACKAGE_AUTHORING_EPOCH = "current" as const;
+export const OWNED_PACKAGE_IDENTITY_SOURCE_SHA256 =
+  "e1777bd86647150762a454d021343627fc8d4ef73067c9bf5e61095866635baf" as const;
+
+export const OWNED_PACKAGE_ROOT_POLICIES = [
+  {
+    id: "core",
+    status: "retained",
+    legacyRoot: "@fragments-sdk/core",
+    currentRoot: "@usefragments/core",
+    targetSpecifier: "@usefragments/core",
+    authoring: {
+      legacy: "@fragments-sdk/core",
+      current: "@usefragments/core",
+    },
+    v1Projection: "@fragments-sdk/core",
+    readEquivalents: ["@fragments-sdk/core", "@usefragments/core"],
+  },
+  {
+    id: "ui",
+    status: "retained",
+    legacyRoot: "@fragments-sdk/ui",
+    currentRoot: "@usefragments/ui",
+    targetSpecifier: "@usefragments/ui",
+    authoring: {
+      legacy: "@fragments-sdk/ui",
+      current: "@usefragments/ui",
+    },
+    v1Projection: "@fragments-sdk/ui",
+    readEquivalents: ["@fragments-sdk/ui", "@usefragments/ui"],
+  },
+  {
+    id: "cli",
+    status: "retained",
+    legacyRoot: "@fragments-sdk/cli",
+    currentRoot: "@usefragments/cli",
+    targetSpecifier: "@usefragments/cli",
+    authoring: {
+      legacy: "@fragments-sdk/cli",
+      current: "@usefragments/cli",
+    },
+    v1Projection: "@fragments-sdk/cli",
+    readEquivalents: ["@fragments-sdk/cli", "@usefragments/cli"],
+  },
+  {
+    id: "preview",
+    status: "moved",
+    legacyRoot: "@fragments-sdk/preview",
+    currentRoot: null,
+    targetSpecifier: "@usefragments/core/preview",
+    authoring: {
+      legacy: "@fragments-sdk/preview",
+      current: "@usefragments/core/preview",
+    },
+    v1Projection: "@fragments-sdk/preview",
+    readEquivalents: ["@fragments-sdk/preview", "@usefragments/core/preview"],
+  },
+  {
+    id: "extract",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/extract",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/extract",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/extract",
+    readEquivalents: ["@fragments-sdk/extract"],
+  },
+  {
+    id: "context",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/context",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/context",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/context",
+    readEquivalents: ["@fragments-sdk/context"],
+  },
+  {
+    id: "compiler",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/compiler",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/compiler",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/compiler",
+    readEquivalents: ["@fragments-sdk/compiler"],
+  },
+  {
+    id: "classifier",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/classifier",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/classifier",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/classifier",
+    readEquivalents: ["@fragments-sdk/classifier"],
+  },
+  {
+    id: "viewer",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/viewer",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/viewer",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/viewer",
+    readEquivalents: ["@fragments-sdk/viewer"],
+  },
+  {
+    id: "mcp",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/mcp",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/mcp",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/mcp",
+    readEquivalents: ["@fragments-sdk/mcp"],
+  },
+  {
+    id: "lsp",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/lsp",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/lsp",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/lsp",
+    readEquivalents: ["@fragments-sdk/lsp"],
+  },
+  {
+    id: "bench",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/bench",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/bench",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/bench",
+    readEquivalents: ["@fragments-sdk/bench"],
+  },
+  {
+    id: "govern",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/govern",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/govern",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/govern",
+    readEquivalents: ["@fragments-sdk/govern"],
+  },
+  {
+    id: "webmcp",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/webmcp",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/webmcp",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/webmcp",
+    readEquivalents: ["@fragments-sdk/webmcp"],
+  },
+  {
+    id: "skills",
+    status: "retired",
+    legacyRoot: "@fragments-sdk/skills",
+    currentRoot: null,
+    targetSpecifier: null,
+    authoring: {
+      legacy: "@fragments-sdk/skills",
+      current: null,
+    },
+    v1Projection: "@fragments-sdk/skills",
+    readEquivalents: ["@fragments-sdk/skills"],
+  },
+] as const;
+
+export const OWNED_PACKAGE_EXPLICIT_POLICIES = [
+  {
+    id: "cli/core",
+    status: "moved",
+    legacySpecifier: "@fragments-sdk/cli/core",
+    currentSpecifier: "@usefragments/core",
+    authoring: {
+      legacy: "@fragments-sdk/core",
+      current: "@usefragments/core",
+    },
+    v1Projection: "@fragments-sdk/cli/core",
+    readEquivalents: ["@fragments-sdk/cli/core", "@fragments-sdk/core", "@usefragments/core"],
+    matchCurrentForV1: false,
+  },
+  {
+    id: "preview",
+    status: "moved",
+    legacySpecifier: "@fragments-sdk/preview",
+    currentSpecifier: "@usefragments/core/preview",
+    authoring: {
+      legacy: "@fragments-sdk/preview",
+      current: "@usefragments/core/preview",
+    },
+    v1Projection: "@fragments-sdk/preview",
+    readEquivalents: ["@fragments-sdk/preview", "@usefragments/core/preview"],
+    matchCurrentForV1: true,
+  },
+] as const;

package/src/package-identity.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  OWNED_PACKAGE_IDENTITY_EPOCH,
+  authorOwnedImport,
+  canonicalizeOwnedComponentId,
+  canonicalizeOwnedImport,
+  ownedImportEquivalents,
+  projectV1OwnedComponentId,
+  projectV1OwnedImportIdentity,
+  resolveOwnedPackageImport,
+} from "./package-identity.js";
+
+describe("owned package import identity", () => {
+  it("canonicalizes retained roots and their subpaths to the current scope", () => {
+    expect(canonicalizeOwnedImport("@fragments-sdk/ui")).toBe("@usefragments/ui");
+    expect(canonicalizeOwnedImport("@fragments-sdk/ui/styles")).toBe("@usefragments/ui/styles");
+    expect(canonicalizeOwnedImport("@usefragments/ui/data-table")).toBe(
+      "@usefragments/ui/data-table"
+    );
+  });
+
+  it("resolves approved moves without exposing private implementation packages", () => {
+    expect(canonicalizeOwnedImport("@fragments-sdk/preview")).toBe("@usefragments/core/preview");
+    expect(canonicalizeOwnedImport("@fragments-sdk/cli/core")).toBe("@usefragments/core");
+
+    const retired = resolveOwnedPackageImport("@fragments-sdk/extract");
+    expect(retired).toMatchObject({ owned: true, status: "retired" });
+    expect(retired.canonicalSpecifier).toBeUndefined();
+    expect(canonicalizeOwnedImport("@fragments-sdk/extract")).toBe("@fragments-sdk/extract");
+  });
+
+  it("enumerates supported equivalents without collapsing historical CLI/core", () => {
+    expect(ownedImportEquivalents("@fragments-sdk/ui/styles")).toEqual([
+      "@fragments-sdk/ui/styles",
+      "@usefragments/ui/styles",
+    ]);
+    expect(ownedImportEquivalents("@fragments-sdk/cli/core")).toEqual([
+      "@fragments-sdk/cli/core",
+      "@fragments-sdk/core",
+      "@usefragments/core",
+    ]);
+    expect(ownedImportEquivalents("@usefragments/core")).toEqual([
+      "@fragments-sdk/core",
+      "@usefragments/core",
+    ]);
+  });
+
+  it("never treats arbitrary or third-party strings as owned imports", () => {
+    for (const value of [
+      "@acme/ui",
+      "@fragments-sdkish/ui",
+      "prefix:@fragments-sdk/ui",
+      "https://github.com/fragments-sdk/fragments",
+    ]) {
+      expect(resolveOwnedPackageImport(value)).toEqual({
+        input: value,
+        owned: false,
+        v1Specifier: value,
+      });
+      expect(canonicalizeOwnedImport(value)).toBe(value);
+    }
+  });
+
+  it("authors only current public identities after the coordinated cutover", () => {
+    expect(OWNED_PACKAGE_IDENTITY_EPOCH).toBe("current");
+    expect(authorOwnedImport("@fragments-sdk/ui/styles")).toBe("@usefragments/ui/styles");
+    expect(authorOwnedImport("@fragments-sdk/preview")).toBe("@usefragments/core/preview");
+  });
+});
+
+describe("fcid-preimage:v1 owned identity projection", () => {
+  it("projects retained and moved old/new spellings to their historical bytes", () => {
+    expect(projectV1OwnedImportIdentity("@usefragments/ui/styles")).toBe(
+      "@fragments-sdk/ui/styles"
+    );
+    expect(projectV1OwnedImportIdentity("@usefragments/core/preview")).toBe(
+      "@fragments-sdk/preview"
+    );
+    expect(projectV1OwnedImportIdentity("@fragments-sdk/preview")).toBe("@fragments-sdk/preview");
+  });
+
+  it("keeps historical CLI/core distinct from the Core root", () => {
+    expect(projectV1OwnedImportIdentity("@fragments-sdk/cli/core")).toBe("@fragments-sdk/cli/core");
+    expect(projectV1OwnedImportIdentity("@usefragments/core")).toBe("@fragments-sdk/core");
+  });
+
+  it("projects component package identities but preserves their component names", () => {
+    expect(canonicalizeOwnedComponentId("@fragments-sdk/ui#Card.Header")).toBe(
+      "@usefragments/ui#Card.Header"
+    );
+    expect(projectV1OwnedComponentId("@usefragments/ui#Card.Header")).toBe(
+      "@fragments-sdk/ui#Card.Header"
+    );
+    expect(projectV1OwnedComponentId("local-design-system#Button")).toBe(
+      "local-design-system#Button"
+    );
+  });
+});