@james_sww/metaform-asset-distribution 0.1.2 → 0.1.4

package/codebase/template/src/styles/workspace-shell.css

@@ -0,0 +1,361 @@
+@import './styles.css';
+
+/* 外壳视觉限定在工作空间内，沿用主题语义色。 */
+.workspace-shell {
+  --workspace-blue: var(--link-foreground);
+  --workspace-violet: var(--data-violet);
+  background:
+    radial-gradient(ellipse 48% 28% at 12% 0%, color-mix(in srgb, var(--workspace-blue) 16%, transparent), transparent 100%),
+    radial-gradient(ellipse 35% 24% at 55% 0%, color-mix(in srgb, var(--workspace-violet) 12%, transparent), transparent 100%),
+    radial-gradient(ellipse 30% 40% at 100% 100%, color-mix(in srgb, var(--workspace-violet) 13%, transparent), transparent 100%),
+    color-mix(in srgb, var(--workspace-blue) 5%, var(--card));
+}
+
+.workspace-body {
+  gap: 16px;
+  padding: 12px 16px 16px;
+}
+
+.workspace-sidebar,
+.workspace-content {
+  border: 1px solid color-mix(in oklch, var(--card) 80%, transparent);
+  border-radius: var(--radius);
+  background: color-mix(in srgb, var(--card) 90%, transparent);
+  box-shadow: 0 6px 24px color-mix(in srgb, var(--workspace-blue) 4%, transparent);
+}
+
+.workspace-sidebar {
+  height: auto;
+  background:
+    radial-gradient(ellipse 100% 24% at 0% 100%, color-mix(in srgb, var(--workspace-violet) 6%, transparent), transparent 100%),
+    color-mix(in srgb, var(--card) 88%, transparent);
+}
+
+.workspace-content {
+  background:
+    radial-gradient(ellipse 42% 20% at 100% 0%, color-mix(in srgb, var(--brand-gradient-highlight) 9%, transparent), transparent 100%),
+    radial-gradient(ellipse 35% 30% at 100% 100%, color-mix(in srgb, var(--workspace-violet) 4%, transparent), transparent 100%),
+    color-mix(in srgb, var(--card) 92%, transparent);
+}
+
+.workspace-nav-item[aria-current='page'] {
+  background: linear-gradient(110deg,
+    color-mix(in srgb, var(--workspace-blue) 16%, var(--card)),
+    color-mix(in srgb, var(--brand-gradient-highlight) 13%, var(--card)));
+  color: var(--link-foreground);
+}
+
+.workspace-nav-item[aria-current='page']:hover {
+  background: color-mix(in oklch, var(--workspace-blue) 23%, var(--card));
+}
+
+.workspace-page-header h1,
+.workspace-content > div > h1 {
+  font-size: clamp(1.5rem, 1.9vw, 2rem);
+  line-height: 1.35;
+  letter-spacing: -0.025em;
+}
+
+.workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) {
+  border-style: solid;
+  border-width: 1px;
+  border-color: transparent;
+  border-radius: 16px;
+  min-height: clamp(180px, 14vw, 240px);
+  padding: clamp(24px, 1.9vw, 32px);
+  background:
+    linear-gradient(115deg,
+      var(--card) 45%,
+      color-mix(in srgb, var(--workspace-violet) 3%, var(--card))) padding-box,
+    linear-gradient(115deg,
+      color-mix(in srgb, var(--brand-gradient-highlight) 50%, var(--card)),
+      color-mix(in srgb, var(--workspace-blue) 32%, var(--card)) 40%,
+      color-mix(in srgb, var(--workspace-violet) 45%, var(--card))) border-box;
+  box-shadow: 0 6px 20px color-mix(in srgb, var(--workspace-blue) 4%, transparent);
+}
+
+
+.workspace-sidebar > div:first-child {
+  padding-block: 24px;
+}
+
+.workspace-sidebar nav {
+  padding-inline: 16px;
+}
+
+.workspace-sidebar nav > div.space-y-1 > p {
+  margin-bottom: 10px;
+  font-size: 12px;
+  font-weight: 400;
+  letter-spacing: 0;
+  color: var(--muted-foreground);
+}
+
+.workspace-sidebar nav > div.h-px {
+  margin-block: 20px;
+}
+
+.workspace-sidebar .workspace-nav-item {
+  min-height: 46px;
+  gap: 14px;
+  padding-inline: 14px;
+  font-size: 15px;
+  font-weight: 400;
+}
+
+.workspace-sidebar .workspace-nav-item[aria-current='page'] {
+  font-weight: 600;
+}
+
+.workspace-sidebar .workspace-nav-item svg {
+  width: 19px;
+  height: 19px;
+}
+
+.workspace-sidebar:has(> button[aria-expanded='false']) nav {
+  padding-inline: 10px;
+}
+
+.workspace-sidebar:has(> button[aria-expanded='false']) .workspace-nav-item {
+  padding-inline: 8px;
+}
+
+.workspace-default-page {
+  padding-top: clamp(20px, 2.2vw, 38px);
+}
+
+.workspace-default-page > h1 {
+  position: relative;
+  min-height: 52px;
+  display: flex;
+  align-items: center;
+  padding-left: 70px;
+  margin-block-end: 4px;
+  font-weight: 650;
+}
+
+.workspace-default-page > h1::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  width: 50px;
+  height: 50px;
+  background: linear-gradient(135deg, var(--brand-gradient-highlight), var(--workspace-blue) 45%, var(--workspace-violet));
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2c1 7 3 9 10 10-7 1-9 3-10 10-1-7-3-9-10-10 7-1 9-3 10-10z'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+.workspace-default-page > p {
+  margin-inline-start: 70px;
+  margin-block-end: 36px;
+  line-height: 1.7;
+}
+
+.workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div {
+  position: relative;
+  padding-left: 64px;
+}
+
+.workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 46px;
+  height: 46px;
+  border-radius: 12px;
+  background: color-mix(in srgb, var(--workspace-blue) 16%, var(--card));
+}
+
+.workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div::after {
+  content: '';
+  position: absolute;
+  top: 11px;
+  left: 11px;
+  width: 24px;
+  height: 24px;
+  background: var(--link-foreground);
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.6'%3E%3Crect x='3' y='3' width='7' height='7' rx='2'/%3E%3Crect x='14' y='3' width='7' height='7' rx='2'/%3E%3Crect x='3' y='14' width='7' height='7' rx='2'/%3E%3Crect x='14' y='14' width='7' height='7' rx='2'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+.workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div.mt-4 {
+  margin-left: 64px;
+}
+
+.workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) h2 {
+  font-size: clamp(18px, 1.4vw, 24px);
+  line-height: 1.4;
+}
+
+.workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) [data-slot='badge'] {
+  border: 0;
+  background: color-mix(in srgb, var(--workspace-blue) 12%, var(--card));
+  color: var(--link-foreground);
+  padding: 4px 12px;
+}
+
+.workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) > div.mt-4 {
+  margin-top: 24px;
+  gap: 12px;
+}
+
+.workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) > div.mt-4 > span {
+  border-radius: 999px;
+  padding: 5px 12px;
+  background: var(--surface-muted);
+  color: var(--surface-muted-foreground);
+  font-size: 13px;
+}
+
+@media (max-width: 767px) {
+  .workspace-body {
+    gap: 0;
+    padding: 8px;
+  }
+
+  .workspace-default-page {
+    padding-top: 8px;
+  }
+
+  .workspace-default-page > h1 {
+    min-height: 44px;
+    padding-left: 56px;
+  }
+
+  .workspace-default-page > h1::before {
+    width: 40px;
+    height: 40px;
+  }
+
+  .workspace-default-page > p {
+    margin-inline-start: 0;
+    margin-block-end: 24px;
+  }
+
+  .workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div {
+    padding-left: 0;
+  }
+
+  .workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div::before,
+  .workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div:first-child > div::after {
+    display: none;
+  }
+
+  .workspace-default-page [data-region-implementation='scaffold']:not([data-region-boundary]) > div.mt-4 {
+    margin-left: 0;
+  }
+
+  .workspace-content [data-region-implementation='scaffold']:not([data-region-boundary]) {
+    min-height: 180px;
+    padding: 20px;
+  }
+}
+
+
+.workspace-navigation,
+.workspace-navigation-children {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.workspace-navigation > li + li {
+  margin-top: 4px;
+}
+
+.workspace-navigation-node {
+  border-radius: var(--radius);
+}
+
+.workspace-navigation-button {
+  width: 100%;
+  min-height: 44px;
+  height: auto;
+  justify-content: flex-start;
+  gap: 12px;
+  padding: 10px 12px;
+  border-radius: var(--radius);
+  color: var(--foreground);
+  font-weight: 500;
+  white-space: normal;
+}
+
+.workspace-navigation-button[aria-current='page'],
+.workspace-navigation-ancestor {
+  color: var(--link-foreground);
+}
+
+.workspace-navigation-button[aria-current='page'] {
+  background: var(--selection);
+  font-weight: 600;
+}
+
+.workspace-navigation-children {
+  padding-left: 18px;
+  padding-bottom: 4px;
+}
+
+.workspace-navigation-children[hidden] {
+  display: none;
+}
+
+.workspace-navigation-node[data-depth='1'].workspace-navigation-open {
+  background: var(--surface-muted);
+}
+
+.workspace-navigation-icon {
+  display: inline-flex;
+  width: 22px;
+  height: 22px;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  color: var(--link-foreground);
+}
+
+.workspace-navigation-dot {
+  width: 4px;
+  height: 4px;
+  margin-inline: 8px;
+  flex-shrink: 0;
+  border-radius: 50%;
+  background: var(--muted-foreground);
+}
+
+.workspace-navigation-count {
+  min-width: 24px;
+  border-radius: 6px;
+  padding: 1px 6px;
+  background: var(--surface-muted);
+  color: var(--muted-foreground);
+  font-size: 12px;
+  line-height: 18px;
+  text-align: center;
+}
+
+.workspace-navigation-collapsed {
+  width: 100%;
+  min-height: 44px;
+  justify-content: center;
+  padding-inline: 8px;
+}
+
+.workspace-navigation-menu {
+  max-height: var(--radix-dropdown-menu-content-available-height);
+  overflow-y: auto;
+}
+
+.workspace-breadcrumb-link {
+  cursor: pointer;
+  color: var(--link-foreground);
+  text-decoration: none;
+}
+
+.workspace-breadcrumb-link:hover {
+  color: var(--link-hover-foreground);
+}
+
+.workspace-breadcrumb-link:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 4px;
+  border-radius: var(--radius-sm);
+}

package/codebase/template/src/workspace/default-workspace.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 
-import { SemanticRegionScaffold } from "../components/common/semantic-region/semantic-region-scaffold";
+import { RegionSlot } from "../platform/region/region-slot";
 import { RoleWorkspaceShell } from "../layouts/role-workspace-shell";
 import { workspaceRouteContract } from "./routes";
 
@@ -23,7 +23,7 @@ export function DefaultWorkspace() {
       }}
       slots={{
         content: (
-          <div className="mx-auto w-full max-w-6xl space-y-6">
+          <div className="workspace-default-page mx-auto w-full max-w-6xl space-y-6">
             <h1 className="text-xl font-semibold text-foreground">
               {contract.title}
             </h1>
@@ -31,7 +31,7 @@ export function DefaultWorkspace() {
               尚未配置应用本体。进入 S7
               前完成页面映射、业务资产安装和语义区域初始化。
             </p>
-            <SemanticRegionScaffold contract={contract} />
+            <RegionSlot contract={contract} source={{ component: "src/workspace/default-workspace.tsx", contract: "src/workspace/routes.ts" }} />
           </div>
         ),
       }}

package/codebase/template/tests/workspace-navigation.test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { findNavigationPath, isSelectableNavigationItem, openNavigationBranch } from '../src/layouts/workspace-navigation-model.ts';
+
+const items = [{
+  id: 'tasks', label: '任务', availability: 'implemented', children: [{
+    id: 'prepare', label: '准备', availability: 'implemented', children: [
+      { id: 'arrange', label: '安排', availability: 'implemented' },
+      { id: 'future', label: '待开放', availability: 'planned' },
+    ],
+  }],
+}, {
+  id: 'blocked', label: '待开放分组', availability: 'planned', children: [
+    { id: 'blocked-child', label: '子项', availability: 'implemented' },
+  ],
+}, { id: 'flat', label: '单层入口', availability: 'implemented', children: [] }];
+
+test('定位三级末级时返回完整上级路径，不匹配时返回空路径', () => {
+  assert.deepEqual(findNavigationPath(items, 'arrange').map(item => item.id), ['tasks', 'prepare', 'arrange']);
+  assert.deepEqual(findNavigationPath(items, 'unknown'), []);
+});
+
+test('只允许跳转已实现的末级，兼容空 children 的单层入口', () => {
+  assert.equal(isSelectableNavigationItem(items, 'arrange'), true);
+  assert.equal(isSelectableNavigationItem(items, 'flat'), true);
+  for (const id of ['tasks', 'prepare', 'future', 'blocked-child', 'unknown']) {
+    assert.equal(isSelectableNavigationItem(items, id), false, id);
+  }
+});
+
+const accordionItems = [{
+  id: 'root', label: '根', availability: 'implemented', children: [
+    {id: 'first', label: '一', availability: 'implemented', children: [{id: 'first-child', label: '子分组', availability: 'implemented', children: [{id: 'leaf-a', label: 'A', availability: 'implemented'}]}]},
+    {id: 'second', label: '二', availability: 'implemented', children: [{id: 'leaf-b', label: 'B', availability: 'implemented'}]},
+  ],
+}];
+
+test('默认同级互斥：开启兄弟分组时移除旧分组及其子树，保留祖先', () => {
+  assert.deepEqual(openNavigationBranch(accordionItems, ['root', 'first', 'first-child'], 'second'), ['root', 'second']);
+});
+
+test('显式多开模式保留兄弟分组，叶子和未知节点不参与展开', () => {
+  assert.deepEqual(openNavigationBranch(accordionItems, ['root', 'first'], 'second', true), ['root', 'first', 'second']);
+  for (const id of ['leaf-a', 'unknown']) assert.deepEqual(openNavigationBranch(accordionItems, ['root'], id), ['root']);
+});

package/dist/application-source.js

@@ -37,8 +37,9 @@ export function generateApplicationFiles(design, release, options = {}) {
     const accent = options.accent && /^[a-z][a-z0-9-]*$/.test(options.accent)
         ? ` data-accent="${options.accent}"`
         : "";
-    const scaffold = "src/components/common/semantic-region/semantic-region-scaffold.tsx";
-    const types = "src/components/common/semantic-region/contract.ts";
+    const slot = "src/platform/region/region-slot.tsx";
+    const regionMap = [];
+    const types = "src/asset-internals/semantic-region/contract.ts";
     const targets = [];
     for (const role of design.roles) {
         const pages = design.pages.filter((p) => p.roleKey === role.roleKey);
@@ -56,22 +57,27 @@ export function generateApplicationFiles(design, release, options = {}) {
         for (const r of regions) {
             const componentPath = `${root}/regions/${r.contract.id}.tsx`;
             const contractPath = `${root}/regions/${r.contract.id}.contract.ts`;
+            const source = { component: componentPath, contract: contractPath };
+            regionMap.push({ roleKey: role.roleKey, pageId: r.contract.pageId, regionId: r.contract.id, sourceRefs: r.contract.sourceRefs, source, implementation: r.implementation.kind === "asset" ? { kind: "asset", asset: r.implementation.asset } : { kind: "scaffold" } });
             files[contractPath] =
                 `import type { SemanticRegionContract } from ${modulePath(contractPath, types)};\nexport const contract: SemanticRegionContract = ${literal(r.contract)};\n`;
             const common = `import { contract } from './${r.contract.id}.contract';\nexport { contract };\nexport interface RegionProps { onAction(id: string, context?: unknown): void; context?: unknown }\n`;
             if (r.implementation.kind === "scaffold") {
                 files[componentPath] =
-                    `import { SemanticRegionScaffold } from ${modulePath(componentPath, scaffold)};\n${common}export function Region({ onAction }: RegionProps) { return <SemanticRegionScaffold contract={contract} commands={{ onAction: (action) => onAction(action.id) }} />; }\n`;
+                    `import { RegionSlot } from ${modulePath(componentPath, slot)};\nimport { SemanticRegionScaffold } from ${modulePath(componentPath, "src/asset-internals/semantic-region/semantic-region-scaffold.tsx")};\n${common}export function Region({ onAction }: RegionProps) { return <RegionSlot contract={contract} source={${literal(source)}}><SemanticRegionScaffold contract={contract} commands={{ onAction: (action) => onAction(action.id) }} compact /></RegionSlot>; }\n`;
             }
             else {
                 const impl = r.implementation;
                 const item = release.items.find((a) => a.assetId === impl.asset.id && a.version === impl.asset.version);
-                const source = item.files.find((f) => f.sourcePath === item.contractRef) ??
+                const entrySource = item.files.find((f) => f.sourcePath === item.contractRef) ??
                     item.files[0];
-                if (!source)
+                if (!entrySource)
                     throw new DistributionError("asset_entry_missing", [item.assetId]);
+                const declaration = impl.events.length
+                    ? "export function Region({ onAction }: RegionProps)"
+                    : "export const Region: ComponentType<RegionProps> = () =>";
                 files[componentPath] =
-                    `import { ${impl.exportName} } from ${modulePath(componentPath, source.targetPath)};\n${common}export function Region({ onAction }: RegionProps) { return <section data-region-id={contract.id} data-region-implementation="asset"><${impl.exportName} {...${propsSource(impl.props, new Map(impl.events.map((e) => [e.propPath, e.actionId])))}} /></section>; }\n`;
+                    `${impl.events.length ? "" : "import type { ComponentType } from 'react';\n"}import { RegionSlot } from ${modulePath(componentPath, slot)};\nimport { ${impl.exportName} } from ${modulePath(componentPath, entrySource.targetPath)};\n${common}${declaration} { return <RegionSlot contract={contract} source={${literal(source)}}><${impl.exportName} {...${propsSource(impl.props, new Map(impl.events.map((e) => [e.propPath, e.actionId])))}} /></RegionSlot>; }\n`;
             }
         }
         const appPath = `${root}/workspace.tsx`;
@@ -79,10 +85,10 @@ export function generateApplicationFiles(design, release, options = {}) {
             `import { createRoot } from 'react-dom/client';\nimport { Workspace } from './workspace';\nimport '../../styles/index.css';\ncreateRoot(document.getElementById('root')!).render(<Workspace />);\n`;
         files[appPath] = `import { useState } from 'react';
 import { RoleWorkspaceShell } from '../../layouts/role-workspace-shell';
-import { SemanticRegionScaffold } from '../../components/common/semantic-region/semantic-region-scaffold';
+import { RegionSlot } from '../../platform/region/region-slot';
 import { activeWorkspaceRoute, resolveWorkspacePage, workspaceRouteContract, type WorkspaceRouteMap } from '../../workspace/routes';
 ${regions.map((r, i) => `import { Region as Region${i}, contract as contract${i} } from './regions/${r.contract.id}';`).join("\n")}
-const pages = ${literal(pages)};
+const pages = ${literal(pages.map((page) => ({ ...page, menu: page.menu ?? true })))};
 const workspaceRoutes: WorkspaceRouteMap = ${literal(role.workspaceRoutes ?? {})};
 const mappedPages = new Set(Object.values(workspaceRoutes));
 const regions = { ${regions.map((r, i) => `${literal(r.contract.id)}: { View: Region${i}, contract: contract${i} }`).join(",")} };
@@ -108,9 +114,10 @@ export function Workspace() {
   }
   return <RoleWorkspaceShell model={{productName:${literal(design.name)},workspaceTitle:${literal(role.label)},actorLabel:'未连接登录服务',roleLabel:${literal(role.label)},themes:pages.filter((p) => p.menu !== false && !mappedPages.has(p.id)).map((p) => ({id:p.id,label:p.title,availability:'implemented' as const})),activeThemeId:page ? activeWorkspaceRoute(page.id,workspaceRoutes) : state.pageId}}
     commands={{onSelectTheme:selectPage}}
-    slots={{content:<div className="mx-auto w-full max-w-6xl space-y-6"><header className="space-y-2"><p className="text-sm text-muted-foreground">应用设计底稿 · 真实业务数据尚未接入</p><h1 className="text-2xl font-semibold text-foreground">{page?.title ?? placeholder?.title ?? '待确认页面'}</h1></header>{feedback ? <p role="status" className="text-sm text-muted-foreground">{feedback}</p> : null}{page ? page.regionIds.map((id) => {const View = regions[id as keyof typeof regions].View; return <View key={id} context={state.contexts[page.id]} onAction={(actionId,context) => onAction(id,actionId,context)} />;}) : placeholder ? <SemanticRegionScaffold contract={placeholder} /> : <p>页面映射待确认</p>}</div>}} />;
+    slots={{content:<div className="mx-auto w-full max-w-6xl space-y-6"><header className="space-y-2"><p className="text-sm text-muted-foreground">应用设计底稿 · 真实业务数据尚未接入</p><h1 className="text-2xl font-semibold text-foreground">{page?.title ?? placeholder?.title ?? '待确认页面'}</h1></header>{feedback ? <p role="status" className="text-sm text-muted-foreground">{feedback}</p> : null}{page ? page.regionIds.map((id) => {const View = regions[id as keyof typeof regions].View; return <View key={id} context={state.contexts[page.id]} onAction={(actionId,context) => onAction(id,actionId,context)} />;}) : placeholder ? <RegionSlot contract={placeholder} source={{ component: "${appPath}", contract: "src/workspace/routes.ts" }} /> : <p>页面映射待确认</p>}</div>}} />;
 }\n`;
     }
+    files[".metaform/region-map.json"] = literal({ schemaVersion: 1, regions: regionMap }) + "\n";
     files["role-targets.json"] = literal(targets) + "\n";
     files["docs/application-design.json"] = literal(design) + "\n";
     return files;

package/dist/asset-selection.d.ts

@@ -0,0 +1,3 @@
+import { type CatalogRecord, type RegistryRelease } from './contracts.js';
+export declare function selectRecord(release: RegistryRelease, identity: string, variant?: string): CatalogRecord | undefined;
+export declare function selectInstallItem(release: RegistryRelease, identity: string, variant?: string): import("./contracts.js").SourceItem;

package/dist/asset-selection.js

@@ -0,0 +1,37 @@
+import { DistributionError } from './contracts.js';
+export function selectRecord(release, identity, variant) {
+    const [id, suffix, extra] = identity.split('#');
+    if (extra !== undefined || !id || suffix === '' || (suffix && variant && suffix !== variant))
+        throw new DistributionError('invalid_asset_identity', [identity]);
+    const selectedVariant = suffix ?? variant;
+    const all = [...release.catalog?.components ?? [], ...release.catalog?.assets ?? []];
+    let matches = all.filter(entry => entry.id === id && (!selectedVariant || entry.variant === selectedVariant));
+    if (!matches.length && !id.includes('.')) {
+        matches = all.filter(entry => (entry.name === id || entry.id === `shadcn.${id}`) && (!selectedVariant || entry.variant === selectedVariant));
+        const official = matches.filter(entry => entry.id === `shadcn.${id}`);
+        if (official.length)
+            matches = official;
+    }
+    const ids = new Set(matches.map(entry => entry.id));
+    if (ids.size > 1)
+        throw new DistributionError('ambiguous_asset', [...ids]);
+    if (!selectedVariant)
+        for (const preferred of ['current', 'new-york-v4', 'raw', 'package']) {
+            const entry = matches.find(entry => entry.variant === preferred);
+            if (entry)
+                return entry;
+        }
+    const variants = new Set(matches.map(entry => entry.variant));
+    if (variants.size > 1)
+        throw new DistributionError('ambiguous_variant', [identity]);
+    return matches[0];
+}
+export function selectInstallItem(release, identity, variant) {
+    const entry = selectRecord(release, identity, variant);
+    if (entry?.installation?.supported === false)
+        throw new DistributionError(entry.installation.reason ?? 'asset_not_installable', [identity, ...entry.installation.details ?? []]);
+    const item = release.items.find(item => item.assetId === (entry?.installId ?? identity));
+    if (!item || (variant && !entry))
+        throw new DistributionError('asset_not_installable', [identity]);
+    return item;
+}

package/dist/cli.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyPlan, recoverInstall, retainedInstallBackups } from './apply.js';
+import { selectInstallItem, selectRecord } from './asset-selection.js';
 import { installDependencies } from './commands.js';
 import { DistributionError } from './contracts.js';
 import { runOfficialAdd } from './official.js';
@@ -52,6 +53,7 @@ export async function runCLI(argv, io) {
             'plan',
             'expect-digest',
             'design',
+            'variant',
         ]);
         for (let i = 0; i < argv.length; i++) {
             const arg = argv[i];
@@ -90,6 +92,7 @@ export async function runCLI(argv, io) {
                     '--codebase <template-package-directory> (init)',
                     '--registry <release.json|https URL>',
                     '--json',
+                    '--variant <variant> (also accepts id#variant)',
                     '--no-install (source only; run pnpm install afterwards)',
                 ],
             };
@@ -146,35 +149,41 @@ export async function runCLI(argv, io) {
                 throw new DistributionError('release_digest_mismatch');
             if (cmd === 'search') {
                 const query = words.join(' ').toLocaleLowerCase().trim();
-                const match = (record) => !query || JSON.stringify(record).toLocaleLowerCase().includes(query);
+                const match = (record) => record.maturity !== 'deprecated' &&
+                    (!query || JSON.stringify(record).toLocaleLowerCase().includes(query));
                 const components = release.catalog?.components ??
                     release.items.map((i) => ({
                         id: i.assetId,
                         version: i.version,
                         name: i.exports?.join(',') ?? i.assetId,
                         description: i.description ?? i.assetId,
+                        sourceEntry: i.contractRef,
                         maturity: i.maturity,
                     }));
                 output = {
                     components: components.filter(match).map((c) => ({
                         ...c,
-                        installable: release.items.some((i) => i.assetId === c.id),
+                        installable: c.installation?.supported !== false && release.items.some((i) => i.assetId === (c.installId ?? c.id)),
                         matchedBy: query ? 'catalog-text' : 'all',
                     })),
                     assets: (release.catalog?.assets ?? []).filter(match).map((a) => ({
                         ...a,
-                        installable: release.items.some((i) => i.assetId === a.id),
+                        installable: a.installation?.supported !== false && release.items.some((i) => i.assetId === (a.installId ?? a.id)),
                         matchedBy: query ? 'catalog-text' : 'all',
                     })),
                 };
             }
             else if (cmd === 'inspect') {
-                const id = words[0], item = release.items.find((i) => i.assetId === id);
+                const selected = selectRecord(release, words[0], options.get('variant'));
+                if (!selected && (options.has('variant') || words[0]?.includes('#')))
+                    throw new DistributionError('unknown_asset_variant', [words[0]]);
+                const id = selected?.id ?? words[0], item = release.items.find((i) => i.assetId === (selected?.installId ?? id));
                 const components = release.catalog?.components.filter((c) => c.id === id) ?? [], assets = release.catalog?.assets.filter((a) => a.id === id) ?? [];
                 if (!item && !components.length && !assets.length)
                     throw new DistributionError('unknown_asset', [id]);
                 output = {
                     item,
+                    installation: selected?.installation ?? item?.installation,
                     components,
                     assets,
                     sources: item
@@ -202,8 +211,8 @@ export async function runCLI(argv, io) {
                     throw new DistributionError('assets_required');
                 const assets = words.map((word) => {
                     const [id, version] = word.split('@');
-                    const item = release.items.find((i) => i.assetId === id);
-                    return { id, version: version ?? item?.version ?? '' };
+                    const item = selectInstallItem(release, id, options.get('variant'));
+                    return { id: item.assetId, version: version ?? item.version };
                 });
                 const plan = await planAdd({ projectRoot: root, release, assets });
                 output =

package/dist/contracts.d.ts

@@ -29,6 +29,19 @@ export type SourceItem = {
     exports?: string[];
     events?: string[];
     states?: string[];
+    installation?: InstallationInfo;
+};
+export type InstallationInfo = {
+    supported: boolean;
+    mode?: 'component' | 'reference' | 'package';
+    source?: string;
+    variant?: string;
+    upstreamVersion?: string;
+    adaptation?: string[];
+    reason?: string;
+    details?: string[];
+    entry?: string;
+    declaredDependencies?: Record<string, string>;
 };
 export type RegistryRelease = {
     schemaVersion: 1;
@@ -57,6 +70,10 @@ export type CatalogRecord = {
     exports?: string[];
     events?: string[];
     states?: string[];
+    source?: string;
+    variant?: string;
+    installId?: string;
+    installation?: InstallationInfo;
 };
 export type CatalogSnapshot = {
     components: CatalogRecord[];
@@ -65,6 +82,7 @@ export type CatalogSnapshot = {
 export type InstalledAsset = AssetRef & {
     releaseDigest: string;
     files: Record<string, string>;
+    installation?: InstallationInfo;
 };
 export type AssetLock = {
     schemaVersion: 1;