@nebutra/ui 0.2.0 → 0.2.2

package/README.md

@@ -1,22 +1,11 @@
 # @nebutra/ui
 
-UI layer for the **AI Chat** product feature (`apps/web /chat` route).
-Built on [Lobe UI](https://github.com/lobehub/lobe-ui) + [Lobe Icons](https://github.com/lobehub/lobe-icons) + Lucide Icons.
+Nebutra design-system UI primitives, layouts, patterns, hooks, typography, and
+token-integrated React components.
 
-## Design Intent
-
-| Dependency       | Purpose                                                                       |
-| ---------------- | ----------------------------------------------------------------------------- |
-| `@lobehub/ui`    | Chat bubbles, streaming text, model selector, chat input, markdown renderer   |
-| `@lobehub/icons` | AI provider icons: OpenAI, Anthropic, Claude, Gemini, Mistral, DeepSeek, etc. |
-| `antd`           | Back-office admin tables / forms if needed in enterprise tier                 |
-
-Usage in `apps/web`:
-
-```tsx
-import { ChatList, ChatInputArea } from "@nebutra/ui/components";
-import { Anthropic, Claude } from "@nebutra/ui/icons";
-```
+This package is the shared UI layer for Nebutra products. It combines Nebutra
+runtime tokens with Nebutra primitives, selected compatibility bridges, icons, and
+product-ready SaaS composition patterns.
 
 ## Installation
 
@@ -24,117 +13,123 @@ import { Anthropic, Claude } from "@nebutra/ui/icons";
 pnpm add @nebutra/ui
 ```
 
+For app rendering, load Nebutra runtime tokens once at the application root:
+
+```tsx
+import "@nebutra/tokens/styles.css";
+```
+
 ## Usage
 
-### Theme Provider
+### Theme Bridge
 
-Wrap your app with `NebutraThemeProvider` to apply Nebutra design tokens:
+Use `NebutraThemeProvider` when consuming compatibility surfaces that depend on Lobe UI or Ant Design:
 
 ```tsx
 import { NebutraThemeProvider } from "@nebutra/ui";
+import { Button } from "@nebutra/ui/components";
 
-function App() {
+export function App() {
   return (
     <NebutraThemeProvider appearance="auto">
-      <YourApp />
+      <Button type="primary">Create workspace</Button>
     </NebutraThemeProvider>
   );
 }
 ```
 
-### Components
+### Product Layouts
 
 ```tsx
-import { Button, ChatList, ActionIcon } from "@nebutra/ui/components";
+import { AppShell, EmptyState, PageHeader } from "@nebutra/ui/layout";
 
-<Button type="primary">Submit</Button>
-<ActionIcon icon={<Settings />} />
+export function DashboardEmptyState() {
+  return (
+    <AppShell>
+      <PageHeader title="Projects" description="Manage reusable product surfaces." />
+      <EmptyState title="No projects yet" description="Create one to start shipping." />
+    </AppShell>
+  );
+}
 ```
 
-### AI Provider Icons
+### Components And Patterns
 
 ```tsx
-import { OpenAI, Anthropic, Google, Claude, Gemini } from "@nebutra/ui/icons";
-
-// In a model selector
-<OpenAI size={24} />
-<Anthropic size={24} />
-<Google size={24} />
-```
-
-### All Lobe Icons
+import { AnimateIn, Button } from "@nebutra/ui/components";
+import { DashboardPanel } from "@nebutra/ui/patterns";
 
-```tsx
-import { HuggingFace, Mistral, DeepSeek, Qwen } from "@nebutra/ui/icons";
+export function WorkspaceSurface() {
+  return (
+    <DashboardPanel
+      title="Workspace"
+      description="Reusable command surfaces for product teams."
+    >
+      <AnimateIn preset="fadeUp">
+        <Button type="primary">Open command center</Button>
+      </AnimateIn>
+    </DashboardPanel>
+  );
+}
 ```
 
-### General UI Icons (Lucide)
+### Icons
 
 ```tsx
-import { Settings, Search, Menu, Plus, Check } from "@nebutra/ui/icons";
+import { OpenAI, Search, Settings } from "@nebutra/ui/icons";
 
+<OpenAI size={24} />;
+<Search size={20} />;
 <Settings size={20} />;
 ```
 
-### Design Tokens
+## Exports
+
+| Path | Description |
+| --- | --- |
+| `@nebutra/ui` | Theme bridge plus selected common icon exports |
+| `@nebutra/ui/components` | Nebutra components, chat input/list surfaces, animation helpers, AI prompt box, node graph canvas, and product widgets |
+| `@nebutra/ui/layout` | App shell, page header, status, section, and empty/loading/error states |
+| `@nebutra/ui/layouts` | Section container, themed section, and bento grid layouts |
+| `@nebutra/ui/icons` | Lobe, Lucide, and Nebutra icon exports |
+| `@nebutra/ui/theme` | `NebutraThemeProvider` and compatibility theme bridge types |
+| `@nebutra/ui/primitives` | Low-level UI primitives and visual building blocks |
+| `@nebutra/ui/primitives/canonical` | Canonical primitive token exports |
+| `@nebutra/ui/patterns` | SaaS dashboard, command, card, terminal, QA, sidebar, and workspace patterns |
+| `@nebutra/ui/typography` | Font utilities and typography tokens |
+| `@nebutra/ui/typography/fonts.css` | Font-face CSS for Nebutra typography |
+| `@nebutra/ui/hooks` | Responsive, focus, undo, hotkey, media query, and interaction hooks |
+| `@nebutra/ui/utils` | Shared utilities such as `cn` |
+| `@nebutra/ui/tailwind.preset` | Tailwind preset integration |
+
+## Token Architecture
 
-Runtime design tokens live in `@nebutra/tokens/styles.css` (CSS variables).
-Use Tailwind classes or `var()` in your components:
+Runtime design tokens live in `@nebutra/tokens/styles.css` as CSS variables.
+Use Tailwind classes backed by those variables, or `var()` directly in places
+where Tailwind is not available.
 
 ```tsx
-// Tailwind classes (preferred)
 <div className="bg-primary text-foreground border-border" />
-
-// CSS variables (when Tailwind isn't available)
 <div style={{ color: "var(--color-primary)" }} />
 ```
 
-> **Note:** `@nebutra/ui/theme` also exports JS token objects (`tokens`, `colors`, etc.)
-> but these are an internal Lobe UI bridge and are deprecated for app use.
+Source-of-truth flow:
 
-## Exports
+```text
+@nebutra/brand  -> brand primitives
+@nebutra/tokens -> runtime CSS variables and theme provider primitives
+@nebutra/ui     -> token-consuming components, layouts, hooks, and patterns
+```
 
-| Path                     | Description                                             |
-| ------------------------ | ------------------------------------------------------- |
-| `@nebutra/ui`            | Main exports (theme provider + common components/icons) |
-| `@nebutra/ui/components` | All Lobe UI components + AnimateIn                      |
-| `@nebutra/ui/layout`     | Layout components (PageHeader, EmptyState, etc.)        |
-| `@nebutra/ui/icons`      | All icons (Lobe + Lucide)                               |
-| `@nebutra/ui/theme`      | Lobe UI theme provider (NebutraThemeProvider)           |
-| `@nebutra/ui/primitives` | Design primitive tokens (spacing, typography, etc.)     |
-| `@nebutra/ui/typography` | Typography system (font families, type styles)          |
-| `@nebutra/ui/utils`      | Utilities (cn, etc.)                                    |
-
-## Available AI Icons
-
-- **OpenAI**: `OpenAI`, `ChatGPT`, `Gpt`
-- **Anthropic**: `Anthropic`, `Claude`
-- **Google**: `Google`, `Gemini`, `GoogleColor`
-- **Meta**: `Meta`, `Llama`
-- **Mistral**: `Mistral`
-- **Cohere**: `Cohere`
-- **Hugging Face**: `HuggingFace`
-- **Perplexity**: `Perplexity`
-- **Groq**: `Groq`
-- **DeepSeek**: `DeepSeek`
-- **Qwen/Tongyi**: `Qwen`, `Tongyi`
-- **Baidu/Wenxin**: `Baidu`, `Wenxin`
-- **Zhipu**: `Zhipu`
-- **Moonshot**: `Moonshot`
-- **Yi**: `Yi`
-- And many more from `@lobehub/icons`
+## Repository Model
 
-## Token Architecture
-
-```
-@nebutra/brand    → Brand primitives (color definitions, motion language)
-@nebutra/tokens   → Runtime CSS variables (light/dark, 12-step scales)  ★ SOURCE OF TRUTH
-@nebutra/theme    → Multi-theme presets (6 oklch variants for SaaS)
-@nebutra/ui       → Component library (consumes tokens via CSS variables)
-```
+The canonical source for this package lives in the Nebutra Sailor monorepo at
+`packages/design/ui`. Public subrepo mirrors are generated from that source for
+discovery, standalone cloning, and contribution intake.
 
 ## License
 
-AGPL-3.0 (inherits from Lobe UI)
+MIT
 
-> ⚠️ AI provider icons may be subject to their respective trademark guidelines.
+AI provider and third-party icons may be subject to their respective trademark
+guidelines.

package/dist/agent/index.d.ts

@@ -0,0 +1,119 @@
+type AgentDocsStatus = "stable" | "beta" | "deprecated" | "experimental";
+type AgentDocsMaturity = "experimental" | "beta" | "stable" | "canonical";
+type AgentDocsLayer = "foundation" | "primitive" | "composition" | "pattern" | "registry" | "api" | "guide";
+type AgentDocsSubstrate = "native" | "custom" | "mixed";
+interface AgentComponentSummary {
+    name: string;
+    title: string;
+    description: string;
+    status: AgentDocsStatus;
+    maturity: AgentDocsMaturity;
+    layer: AgentDocsLayer;
+    source: string;
+    href: string;
+    tags: string[];
+}
+interface AgentManifest {
+    $schema: string;
+    name: "nebutra-ui-agent";
+    version: 1;
+    generatedAt: string;
+    homepage: string;
+    registry: string;
+    commands: Array<{
+        name: "search" | "component" | "validate" | "template" | "migrate";
+        status: "available" | "planned";
+        description: string;
+        json: boolean;
+    }>;
+    rules: {
+        sourceOfTruth: string[];
+        importPolicy: string;
+        registryPolicy: string;
+        tokenPolicy: string;
+    };
+    components: AgentComponentSummary[];
+}
+interface AgentComponentContract extends AgentComponentSummary {
+    package: "@nebutra/ui" | "@nebutra/tokens";
+    substrate: AgentDocsSubstrate;
+    imports: {
+        package: string;
+        registry: string;
+    };
+    dependencies: {
+        npm: string[];
+        registry: string[];
+    };
+    files: Array<{
+        path: string;
+        type: string;
+        target?: string;
+    }>;
+    tokens: string[];
+    evidence: {
+        source: true;
+        docs: boolean;
+        storybook: boolean;
+        registry: true;
+        tokens: boolean;
+    };
+    docs: {
+        source?: string;
+        routes: string[];
+        storybook?: string;
+        lastVerified: string;
+    };
+    usage: {
+        recommended: string;
+        antiPatterns: string[];
+    };
+    migration: {
+        requiredForBreakingChanges: true;
+        codemods: string[];
+        hints: string[];
+    };
+}
+interface AgentContractPaths {
+    manifestPath: string;
+    componentDir: string;
+}
+interface LoadAgentContractOptions {
+    root?: string;
+    manifestPath?: string;
+}
+interface SearchAgentComponentsOptions {
+    limit?: number;
+    offset?: number;
+    tag?: string;
+    status?: AgentDocsStatus;
+    maturity?: AgentDocsMaturity;
+}
+interface SearchAgentComponentsResult {
+    query: string;
+    total: number;
+    count: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset?: number;
+    items: AgentComponentSummary[];
+}
+interface AgentValidationResult {
+    name: string;
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    evidence: AgentComponentContract["evidence"];
+    migration: AgentComponentContract["migration"];
+}
+declare function resolveAgentContractPaths(options?: LoadAgentContractOptions): AgentContractPaths;
+declare function normalizeAgentComponentName(name: string): string;
+declare function assertSafeAgentComponentName(name: string): string;
+declare function loadAgentManifest(options?: LoadAgentContractOptions): AgentManifest;
+declare function loadAgentComponentContract(name: string, options?: LoadAgentContractOptions): AgentComponentContract;
+declare function findAgentComponent(manifest: AgentManifest, name: string): AgentComponentSummary | undefined;
+declare function searchAgentComponents(manifest: AgentManifest, query?: string, options?: SearchAgentComponentsOptions): SearchAgentComponentsResult;
+declare function validateAgentComponent(contract: AgentComponentContract): AgentValidationResult;
+
+export { type AgentComponentContract, type AgentComponentSummary, type AgentContractPaths, type AgentDocsLayer, type AgentDocsMaturity, type AgentDocsStatus, type AgentDocsSubstrate, type AgentManifest, type AgentValidationResult, type LoadAgentContractOptions, type SearchAgentComponentsOptions, type SearchAgentComponentsResult, assertSafeAgentComponentName, findAgentComponent, loadAgentComponentContract, loadAgentManifest, normalizeAgentComponentName, resolveAgentContractPaths, searchAgentComponents, validateAgentComponent };

package/dist/agent/index.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve, join } from 'path';
+
+// src/agent/index.ts
+function resolveAgentContractPaths(options = {}) {
+  const manifestPath = options.manifestPath ? resolve(options.manifestPath) : join(
+    resolve(options.root ?? process.cwd()),
+    "apps",
+    "design-docs",
+    "public",
+    "agent-manifest.json"
+  );
+  return {
+    manifestPath,
+    componentDir: join(manifestPath, "..", "agent", "components")
+  };
+}
+function normalizeAgentComponentName(name) {
+  return name.trim().toLowerCase();
+}
+function assertSafeAgentComponentName(name) {
+  const normalized = normalizeAgentComponentName(name);
+  if (!/^[a-z0-9-]+$/.test(normalized)) {
+    throw new Error(
+      `Invalid UI component name "${name}". Use a registry kebab-case id such as "button".`
+    );
+  }
+  return normalized;
+}
+function loadAgentManifest(options = {}) {
+  const { manifestPath } = resolveAgentContractPaths(options);
+  if (!existsSync(manifestPath)) {
+    throw new Error(
+      `Missing Nebutra UI agent manifest at ${manifestPath}. Run pnpm --filter @nebutra/design-docs build:registry.`
+    );
+  }
+  return JSON.parse(readFileSync(manifestPath, "utf8"));
+}
+function loadAgentComponentContract(name, options = {}) {
+  const safeName = assertSafeAgentComponentName(name);
+  const { componentDir } = resolveAgentContractPaths(options);
+  const componentPath = join(componentDir, `${safeName}.json`);
+  if (!existsSync(componentPath)) {
+    throw new Error(`UI component contract not found: ${safeName}`);
+  }
+  return JSON.parse(readFileSync(componentPath, "utf8"));
+}
+function findAgentComponent(manifest, name) {
+  const safeName = normalizeAgentComponentName(name);
+  return manifest.components.find((component) => component.name === safeName);
+}
+function searchAgentComponents(manifest, query = "", options = {}) {
+  const normalizedQuery = query.trim().toLowerCase();
+  const limit = clampInteger(options.limit ?? 20, 1, 100);
+  const offset = clampInteger(options.offset ?? 0, 0, Number.MAX_SAFE_INTEGER);
+  const tag = options.tag?.trim().toLowerCase();
+  const scored = manifest.components.filter((component) => {
+    if (options.status && component.status !== options.status) return false;
+    if (options.maturity && component.maturity !== options.maturity) return false;
+    if (tag && !component.tags.includes(tag)) return false;
+    if (!normalizedQuery) return true;
+    return searchableText(component).includes(normalizedQuery);
+  }).map((component) => ({ component, score: scoreComponent(component, normalizedQuery) })).sort((a, b) => b.score - a.score || a.component.name.localeCompare(b.component.name)).map(({ component }) => component);
+  const items = scored.slice(offset, offset + limit);
+  const nextOffset = offset + items.length;
+  return {
+    query,
+    total: scored.length,
+    count: items.length,
+    offset,
+    limit,
+    hasMore: nextOffset < scored.length,
+    ...nextOffset < scored.length && { nextOffset },
+    items
+  };
+}
+function validateAgentComponent(contract) {
+  const errors = [];
+  const warnings = [];
+  if (!contract.evidence.source) errors.push("Missing source evidence.");
+  if (!contract.evidence.docs) errors.push("Missing docs evidence.");
+  if (!contract.evidence.registry) errors.push("Missing registry evidence.");
+  if ((contract.status === "stable" || contract.maturity === "canonical") && !contract.evidence.storybook) {
+    errors.push("Stable/canonical components must have Storybook evidence.");
+  }
+  if (!contract.evidence.tokens && contract.package === "@nebutra/ui") {
+    warnings.push(
+      "No token evidence was detected; confirm this primitive intentionally has no CSS variables."
+    );
+  }
+  if (contract.migration.requiredForBreakingChanges && contract.migration.hints.length === 0) {
+    warnings.push(
+      "Breaking-change migration policy is enabled but no migration hints are present."
+    );
+  }
+  return {
+    name: contract.name,
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    evidence: contract.evidence,
+    migration: contract.migration
+  };
+}
+function searchableText(component) {
+  return [
+    component.name,
+    component.title,
+    component.description,
+    component.status,
+    component.maturity,
+    component.layer,
+    component.source,
+    ...component.tags
+  ].join(" ").toLowerCase();
+}
+function scoreComponent(component, query) {
+  if (!query) return component.maturity === "canonical" ? 20 : 10;
+  if (component.name === query) return 100;
+  if (component.name.startsWith(query)) return 80;
+  if (component.title.toLowerCase().startsWith(query)) return 70;
+  if (component.tags.includes(query)) return 60;
+  if (component.name.includes(query)) return 50;
+  if (component.title.toLowerCase().includes(query)) return 40;
+  if (component.description.toLowerCase().includes(query)) return 20;
+  return 1;
+}
+function clampInteger(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+export { assertSafeAgentComponentName, findAgentComponent, loadAgentComponentContract, loadAgentManifest, normalizeAgentComponentName, resolveAgentContractPaths, searchAgentComponents, validateAgentComponent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/agent/index.ts"],"names":[],"mappings":";;;;AAgIO,SAAS,yBAAA,CACd,OAAA,GAAoC,EAAC,EACjB;AACpB,EAAA,MAAM,eAAe,OAAA,CAAQ,YAAA,GACzB,OAAA,CAAQ,OAAA,CAAQ,YAAY,CAAA,GAC5B,IAAA;AAAA,IACE,OAAA,CAAQ,OAAA,CAAQ,IAAA,IAAQ,OAAA,CAAQ,KAAK,CAAA;AAAA,IACrC,MAAA;AAAA,IACA,aAAA;AAAA,IACA,QAAA;AAAA,IACA;AAAA,GACF;AAEJ,EAAA,OAAO;AAAA,IACL,YAAA;AAAA,IACA,YAAA,EAAc,IAAA,CAAK,YAAA,EAAc,IAAA,EAAM,SAAS,YAAY;AAAA,GAC9D;AACF;AAEO,SAAS,4BAA4B,IAAA,EAAsB;AAChE,EAAA,OAAO,IAAA,CAAK,IAAA,EAAK,CAAE,WAAA,EAAY;AACjC;AAEO,SAAS,6BAA6B,IAAA,EAAsB;AACjE,EAAA,MAAM,UAAA,GAAa,4BAA4B,IAAI,CAAA;AACnD,EAAA,IAAI,CAAC,cAAA,CAAe,IAAA,CAAK,UAAU,CAAA,EAAG;AACpC,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,8BAA8B,IAAI,CAAA,iDAAA;AAAA,KACpC;AAAA,EACF;AACA,EAAA,OAAO,UAAA;AACT;AAEO,SAAS,iBAAA,CAAkB,OAAA,GAAoC,EAAC,EAAkB;AACvF,EAAA,MAAM,EAAE,YAAA,EAAa,GAAI,yBAAA,CAA0B,OAAO,CAAA;AAC1D,EAAA,IAAI,CAAC,UAAA,CAAW,YAAY,CAAA,EAAG;AAC7B,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,wCAAwC,YAAY,CAAA,wDAAA;AAAA,KACtD;AAAA,EACF;AACA,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,YAAA,CAAa,YAAA,EAAc,MAAM,CAAC,CAAA;AACtD;AAEO,SAAS,0BAAA,CACd,IAAA,EACA,OAAA,GAAoC,EAAC,EACb;AACxB,EAAA,MAAM,QAAA,GAAW,6BAA6B,IAAI,CAAA;AAClD,EAAA,MAAM,EAAE,YAAA,EAAa,GAAI,yBAAA,CAA0B,OAAO,CAAA;AAC1D,EAAA,MAAM,aAAA,GAAgB,IAAA,CAAK,YAAA,EAAc,CAAA,EAAG,QAAQ,CAAA,KAAA,CAAO,CAAA;AAC3D,EAAA,IAAI,CAAC,UAAA,CAAW,aAAa,CAAA,EAAG;AAC9B,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,iCAAA,EAAoC,QAAQ,CAAA,CAAE,CAAA;AAAA,EAChE;AACA,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,YAAA,CAAa,aAAA,EAAe,MAAM,CAAC,CAAA;AACvD;AAEO,SAAS,kBAAA,CACd,UACA,IAAA,EACmC;AACnC,EAAA,MAAM,QAAA,GAAW,4BAA4B,IAAI,CAAA;AACjD,EAAA,OAAO,SAAS,UAAA,CAAW,IAAA,CAAK,CAAC,SAAA,KAAc,SAAA,CAAU,SAAS,QAAQ,CAAA;AAC5E;AAEO,SAAS,sBACd,QAAA,EACA,KAAA,GAAQ,EAAA,EACR,OAAA,GAAwC,EAAC,EACZ;AAC7B,EAAA,MAAM,eAAA,GAAkB,KAAA,CAAM,IAAA,EAAK,CAAE,WAAA,EAAY;AACjD,EAAA,MAAM,QAAQ,YAAA,CAAa,OAAA,CAAQ,KAAA,IAAS,EAAA,EAAI,GAAG,GAAG,CAAA;AACtD,EAAA,MAAM,SAAS,YAAA,CAAa,OAAA,CAAQ,UAAU,CAAA,EAAG,CAAA,EAAG,OAAO,gBAAgB,CAAA;AAC3E,EAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,GAAA,EAAK,IAAA,GAAO,WAAA,EAAY;AAE5C,EAAA,MAAM,MAAA,GAAS,QAAA,CAAS,UAAA,CACrB,MAAA,CAAO,CAAC,SAAA,KAAc;AACrB,IAAA,IAAI,QAAQ,MAAA,IAAU,SAAA,CAAU,MAAA,KAAW,OAAA,CAAQ,QAAQ,OAAO,KAAA;AAClE,IAAA,IAAI,QAAQ,QAAA,IAAY,SAAA,CAAU,QAAA,KAAa,OAAA,CAAQ,UAAU,OAAO,KAAA;AACxE,IAAA,IAAI,OAAO,CAAC,SAAA,CAAU,KAAK,QAAA,CAAS,GAAG,GAAG,OAAO,KAAA;AACjD,IAAA,IAAI,CAAC,iBAAiB,OAAO,IAAA;AAE7B,IAAA,OAAO,cAAA,CAAe,SAAS,CAAA,CAAE,QAAA,CAAS,eAAe,CAAA;AAAA,EAC3D,CAAC,CAAA,CACA,GAAA,CAAI,CAAC,SAAA,MAAe,EAAE,SAAA,EAAW,KAAA,EAAO,cAAA,CAAe,SAAA,EAAW,eAAe,CAAA,EAAE,CAAE,CAAA,CACrF,IAAA,CAAK,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,CAAE,KAAA,GAAQ,EAAE,KAAA,IAAS,CAAA,CAAE,SAAA,CAAU,IAAA,CAAK,cAAc,CAAA,CAAE,SAAA,CAAU,IAAI,CAAC,EACpF,GAAA,CAAI,CAAC,EAAE,SAAA,OAAgB,SAAS,CAAA;AAEnC,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,MAAA,EAAQ,SAAS,KAAK,CAAA;AACjD,EAAA,MAAM,UAAA,GAAa,SAAS,KAAA,CAAM,MAAA;AAElC,EAAA,OAAO;AAAA,IACL,KAAA;AAAA,IACA,OAAO,MAAA,CAAO,MAAA;AAAA,IACd,OAAO,KAAA,CAAM,MAAA;AAAA,IACb,MAAA;AAAA,IACA,KAAA;AAAA,IACA,OAAA,EAAS,aAAa,MAAA,CAAO,MAAA;AAAA,IAC7B,GAAI,UAAA,GAAa,MAAA,CAAO,MAAA,IAAU,EAAE,UAAA,EAAW;AAAA,IAC/C;AAAA,GACF;AACF;AAEO,SAAS,uBAAuB,QAAA,EAAyD;AAC9F,EAAA,MAAM,SAAmB,EAAC;AAC1B,EAAA,MAAM,WAAqB,EAAC;AAE5B,EAAA,IAAI,CAAC,QAAA,CAAS,QAAA,CAAS,MAAA,EAAQ,MAAA,CAAO,KAAK,0BAA0B,CAAA;AACrE,EAAA,IAAI,CAAC,QAAA,CAAS,QAAA,CAAS,IAAA,EAAM,MAAA,CAAO,KAAK,wBAAwB,CAAA;AACjE,EAAA,IAAI,CAAC,QAAA,CAAS,QAAA,CAAS,QAAA,EAAU,MAAA,CAAO,KAAK,4BAA4B,CAAA;AAEzE,EAAA,IAAA,CACG,QAAA,CAAS,WAAW,QAAA,IAAY,QAAA,CAAS,aAAa,WAAA,KACvD,CAAC,QAAA,CAAS,QAAA,CAAS,SAAA,EACnB;AACA,IAAA,MAAA,CAAO,KAAK,2DAA2D,CAAA;AAAA,EACzE;AAEA,EAAA,IAAI,CAAC,QAAA,CAAS,QAAA,CAAS,MAAA,IAAU,QAAA,CAAS,YAAY,aAAA,EAAe;AACnE,IAAA,QAAA,CAAS,IAAA;AAAA,MACP;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,SAAS,SAAA,CAAU,0BAAA,IAA8B,SAAS,SAAA,CAAU,KAAA,CAAM,WAAW,CAAA,EAAG;AAC1F,IAAA,QAAA,CAAS,IAAA;AAAA,MACP;AAAA,KACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,MAAM,QAAA,CAAS,IAAA;AAAA,IACf,KAAA,EAAO,OAAO,MAAA,KAAW,CAAA;AAAA,IACzB,MAAA;AAAA,IACA,QAAA;AAAA,IACA,UAAU,QAAA,CAAS,QAAA;AAAA,IACnB,WAAW,QAAA,CAAS;AAAA,GACtB;AACF;AAEA,SAAS,eAAe,SAAA,EAA0C;AAChE,EAAA,OAAO;AAAA,IACL,SAAA,CAAU,IAAA;AAAA,IACV,SAAA,CAAU,KAAA;AAAA,IACV,SAAA,CAAU,WAAA;AAAA,IACV,SAAA,CAAU,MAAA;AAAA,IACV,SAAA,CAAU,QAAA;AAAA,IACV,SAAA,CAAU,KAAA;AAAA,IACV,SAAA,CAAU,MAAA;AAAA,IACV,GAAG,SAAA,CAAU;AAAA,GACf,CACG,IAAA,CAAK,GAAG,CAAA,CACR,WAAA,EAAY;AACjB;AAEA,SAAS,cAAA,CAAe,WAAkC,KAAA,EAAuB;AAC/E,EAAA,IAAI,CAAC,KAAA,EAAO,OAAO,SAAA,CAAU,QAAA,KAAa,cAAc,EAAA,GAAK,EAAA;AAC7D,EAAA,IAAI,SAAA,CAAU,IAAA,KAAS,KAAA,EAAO,OAAO,GAAA;AACrC,EAAA,IAAI,SAAA,CAAU,IAAA,CAAK,UAAA,CAAW,KAAK,GAAG,OAAO,EAAA;AAC7C,EAAA,IAAI,UAAU,KAAA,CAAM,WAAA,GAAc,UAAA,CAAW,KAAK,GAAG,OAAO,EAAA;AAC5D,EAAA,IAAI,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,KAAK,GAAG,OAAO,EAAA;AAC3C,EAAA,IAAI,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,KAAK,GAAG,OAAO,EAAA;AAC3C,EAAA,IAAI,UAAU,KAAA,CAAM,WAAA,GAAc,QAAA,CAAS,KAAK,GAAG,OAAO,EAAA;AAC1D,EAAA,IAAI,UAAU,WAAA,CAAY,WAAA,GAAc,QAAA,CAAS,KAAK,GAAG,OAAO,EAAA;AAChE,EAAA,OAAO,CAAA;AACT;AAEA,SAAS,YAAA,CAAa,KAAA,EAAe,GAAA,EAAa,GAAA,EAAqB;AACrE,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,GAAG,OAAO,GAAA;AACpC,EAAA,OAAO,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,MAAM,KAAK,CAAA,EAAG,GAAG,CAAA,EAAG,GAAG,CAAA;AACvD","file":"index.js","sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\n\nexport type AgentDocsStatus = \"stable\" | \"beta\" | \"deprecated\" | \"experimental\";\nexport type AgentDocsMaturity = \"experimental\" | \"beta\" | \"stable\" | \"canonical\";\nexport type AgentDocsLayer =\n  | \"foundation\"\n  | \"primitive\"\n  | \"composition\"\n  | \"pattern\"\n  | \"registry\"\n  | \"api\"\n  | \"guide\";\nexport type AgentDocsSubstrate = \"native\" | \"custom\" | \"mixed\";\n\nexport interface AgentComponentSummary {\n  name: string;\n  title: string;\n  description: string;\n  status: AgentDocsStatus;\n  maturity: AgentDocsMaturity;\n  layer: AgentDocsLayer;\n  source: string;\n  href: string;\n  tags: string[];\n}\n\nexport interface AgentManifest {\n  $schema: string;\n  name: \"nebutra-ui-agent\";\n  version: 1;\n  generatedAt: string;\n  homepage: string;\n  registry: string;\n  commands: Array<{\n    name: \"search\" | \"component\" | \"validate\" | \"template\" | \"migrate\";\n    status: \"available\" | \"planned\";\n    description: string;\n    json: boolean;\n  }>;\n  rules: {\n    sourceOfTruth: string[];\n    importPolicy: string;\n    registryPolicy: string;\n    tokenPolicy: string;\n  };\n  components: AgentComponentSummary[];\n}\n\nexport interface AgentComponentContract extends AgentComponentSummary {\n  package: \"@nebutra/ui\" | \"@nebutra/tokens\";\n  substrate: AgentDocsSubstrate;\n  imports: {\n    package: string;\n    registry: string;\n  };\n  dependencies: {\n    npm: string[];\n    registry: string[];\n  };\n  files: Array<{\n    path: string;\n    type: string;\n    target?: string;\n  }>;\n  tokens: string[];\n  evidence: {\n    source: true;\n    docs: boolean;\n    storybook: boolean;\n    registry: true;\n    tokens: boolean;\n  };\n  docs: {\n    source?: string;\n    routes: string[];\n    storybook?: string;\n    lastVerified: string;\n  };\n  usage: {\n    recommended: string;\n    antiPatterns: string[];\n  };\n  migration: {\n    requiredForBreakingChanges: true;\n    codemods: string[];\n    hints: string[];\n  };\n}\n\nexport interface AgentContractPaths {\n  manifestPath: string;\n  componentDir: string;\n}\n\nexport interface LoadAgentContractOptions {\n  root?: string;\n  manifestPath?: string;\n}\n\nexport interface SearchAgentComponentsOptions {\n  limit?: number;\n  offset?: number;\n  tag?: string;\n  status?: AgentDocsStatus;\n  maturity?: AgentDocsMaturity;\n}\n\nexport interface SearchAgentComponentsResult {\n  query: string;\n  total: number;\n  count: number;\n  offset: number;\n  limit: number;\n  hasMore: boolean;\n  nextOffset?: number;\n  items: AgentComponentSummary[];\n}\n\nexport interface AgentValidationResult {\n  name: string;\n  valid: boolean;\n  errors: string[];\n  warnings: string[];\n  evidence: AgentComponentContract[\"evidence\"];\n  migration: AgentComponentContract[\"migration\"];\n}\n\nexport function resolveAgentContractPaths(\n  options: LoadAgentContractOptions = {},\n): AgentContractPaths {\n  const manifestPath = options.manifestPath\n    ? resolve(options.manifestPath)\n    : join(\n        resolve(options.root ?? process.cwd()),\n        \"apps\",\n        \"design-docs\",\n        \"public\",\n        \"agent-manifest.json\",\n      );\n\n  return {\n    manifestPath,\n    componentDir: join(manifestPath, \"..\", \"agent\", \"components\"),\n  };\n}\n\nexport function normalizeAgentComponentName(name: string): string {\n  return name.trim().toLowerCase();\n}\n\nexport function assertSafeAgentComponentName(name: string): string {\n  const normalized = normalizeAgentComponentName(name);\n  if (!/^[a-z0-9-]+$/.test(normalized)) {\n    throw new Error(\n      `Invalid UI component name \"${name}\". Use a registry kebab-case id such as \"button\".`,\n    );\n  }\n  return normalized;\n}\n\nexport function loadAgentManifest(options: LoadAgentContractOptions = {}): AgentManifest {\n  const { manifestPath } = resolveAgentContractPaths(options);\n  if (!existsSync(manifestPath)) {\n    throw new Error(\n      `Missing Nebutra UI agent manifest at ${manifestPath}. Run pnpm --filter @nebutra/design-docs build:registry.`,\n    );\n  }\n  return JSON.parse(readFileSync(manifestPath, \"utf8\")) as AgentManifest;\n}\n\nexport function loadAgentComponentContract(\n  name: string,\n  options: LoadAgentContractOptions = {},\n): AgentComponentContract {\n  const safeName = assertSafeAgentComponentName(name);\n  const { componentDir } = resolveAgentContractPaths(options);\n  const componentPath = join(componentDir, `${safeName}.json`);\n  if (!existsSync(componentPath)) {\n    throw new Error(`UI component contract not found: ${safeName}`);\n  }\n  return JSON.parse(readFileSync(componentPath, \"utf8\")) as AgentComponentContract;\n}\n\nexport function findAgentComponent(\n  manifest: AgentManifest,\n  name: string,\n): AgentComponentSummary | undefined {\n  const safeName = normalizeAgentComponentName(name);\n  return manifest.components.find((component) => component.name === safeName);\n}\n\nexport function searchAgentComponents(\n  manifest: AgentManifest,\n  query = \"\",\n  options: SearchAgentComponentsOptions = {},\n): SearchAgentComponentsResult {\n  const normalizedQuery = query.trim().toLowerCase();\n  const limit = clampInteger(options.limit ?? 20, 1, 100);\n  const offset = clampInteger(options.offset ?? 0, 0, Number.MAX_SAFE_INTEGER);\n  const tag = options.tag?.trim().toLowerCase();\n\n  const scored = manifest.components\n    .filter((component) => {\n      if (options.status && component.status !== options.status) return false;\n      if (options.maturity && component.maturity !== options.maturity) return false;\n      if (tag && !component.tags.includes(tag)) return false;\n      if (!normalizedQuery) return true;\n\n      return searchableText(component).includes(normalizedQuery);\n    })\n    .map((component) => ({ component, score: scoreComponent(component, normalizedQuery) }))\n    .sort((a, b) => b.score - a.score || a.component.name.localeCompare(b.component.name))\n    .map(({ component }) => component);\n\n  const items = scored.slice(offset, offset + limit);\n  const nextOffset = offset + items.length;\n\n  return {\n    query,\n    total: scored.length,\n    count: items.length,\n    offset,\n    limit,\n    hasMore: nextOffset < scored.length,\n    ...(nextOffset < scored.length && { nextOffset }),\n    items,\n  };\n}\n\nexport function validateAgentComponent(contract: AgentComponentContract): AgentValidationResult {\n  const errors: string[] = [];\n  const warnings: string[] = [];\n\n  if (!contract.evidence.source) errors.push(\"Missing source evidence.\");\n  if (!contract.evidence.docs) errors.push(\"Missing docs evidence.\");\n  if (!contract.evidence.registry) errors.push(\"Missing registry evidence.\");\n\n  if (\n    (contract.status === \"stable\" || contract.maturity === \"canonical\") &&\n    !contract.evidence.storybook\n  ) {\n    errors.push(\"Stable/canonical components must have Storybook evidence.\");\n  }\n\n  if (!contract.evidence.tokens && contract.package === \"@nebutra/ui\") {\n    warnings.push(\n      \"No token evidence was detected; confirm this primitive intentionally has no CSS variables.\",\n    );\n  }\n\n  if (contract.migration.requiredForBreakingChanges && contract.migration.hints.length === 0) {\n    warnings.push(\n      \"Breaking-change migration policy is enabled but no migration hints are present.\",\n    );\n  }\n\n  return {\n    name: contract.name,\n    valid: errors.length === 0,\n    errors,\n    warnings,\n    evidence: contract.evidence,\n    migration: contract.migration,\n  };\n}\n\nfunction searchableText(component: AgentComponentSummary): string {\n  return [\n    component.name,\n    component.title,\n    component.description,\n    component.status,\n    component.maturity,\n    component.layer,\n    component.source,\n    ...component.tags,\n  ]\n    .join(\" \")\n    .toLowerCase();\n}\n\nfunction scoreComponent(component: AgentComponentSummary, query: string): number {\n  if (!query) return component.maturity === \"canonical\" ? 20 : 10;\n  if (component.name === query) return 100;\n  if (component.name.startsWith(query)) return 80;\n  if (component.title.toLowerCase().startsWith(query)) return 70;\n  if (component.tags.includes(query)) return 60;\n  if (component.name.includes(query)) return 50;\n  if (component.title.toLowerCase().includes(query)) return 40;\n  if (component.description.toLowerCase().includes(query)) return 20;\n  return 1;\n}\n\nfunction clampInteger(value: number, min: number, max: number): number {\n  if (!Number.isFinite(value)) return min;\n  return Math.min(Math.max(Math.trunc(value), min), max);\n}\n"]}