@forumone/throughline-components 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @forumone/throughline-components
+
+## 0.2.0
+
+### Minor Changes
+
+- [#16](https://github.com/forumone/throughline/pull/16) [`4db5168`](https://github.com/forumone/throughline/commit/4db5168cfe83922ad371b7927029c21b009b1e53) Thanks [@briangraves](https://github.com/briangraves)! - Initial release. MCP server that exposes a design system manifest as seven conversational tools: `list_components`, `get_contract`, `get_variants`, `get_tokens`, `suggest_for_intent`, `validate_composition`, `find_anti_pattern`. Ships TF-IDF intent matching (no external deps); embeddings strategy reserved for a follow-up release. Accepts manifests as imported objects, remote URLs (with `refreshInterval`), or Payload collections.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forum One Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,134 @@
 # @forumone/throughline-components
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+MCP server that exposes a design system manifest as conversational primitives. Drop it into a Payload + Throughline app and Claude can list components, read contracts, suggest components for an intent, validate compositions, and surface anti-patterns — against any design system that satisfies the Throughline contract.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## What this package provides
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Seven MCP tools served at `${routePrefix}/mcp` (default `/api/components/mcp`):
 
-## Purpose
+| Tool | Purpose |
+|---|---|
+| `list_components` | Discover what components exist (optionally filtered by category) |
+| `get_contract` | Full `ComponentContract` for a named component |
+| `get_variants` | Available variants and when to use each |
+| `get_tokens` | Tokens a component consumes + configurable token-backed props |
+| `suggest_for_intent` | Ranked component recommendations for a natural-language intent |
+| `validate_composition` | Errors + warnings for a proposed block list against the design system's rules |
+| `find_anti_pattern` | Surfaces structural anti-patterns (multiple Heroes, Hero at the bottom, etc.) |
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@forumone/throughline-components`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+Every consequential call writes to the audit log via `@forumone/throughline-core`'s audit writer.
 
-## What is OIDC Trusted Publishing?
+## Installation
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```bash
+pnpm add @forumone/throughline-components
+```
 
-## Setup Instructions
+Peer: `payload@^3.0.0`. Required runtime: `@forumone/throughline-core` (the components plugin asserts the `audit-log` capability at init).
 
-To properly configure OIDC trusted publishing for this package:
+## Usage
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```ts
+import { buildConfig } from 'payload'
+import { auditPlugin, createInngestClient } from '@forumone/throughline-core'
+import { componentsPlugin } from '@forumone/throughline-components'
+import manifest from '@my-company/design-system/manifest' with { type: 'json' }
 
-## DO NOT USE THIS PACKAGE
+const inngest = createInngestClient({ id: 'my-site' })
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+export default buildConfig({
+  // collections, db, secret...
+  plugins: [
+    auditPlugin({ inngest }),       // must come first (componentsPlugin requires audit-log)
+    componentsPlugin({
+      manifest: { type: 'object', manifest },
+      matching: { strategy: 'tfidf' },
+    }),
+  ],
+})
+```
 
-## More Information
+## Manifest sources
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+Three ways to supply the manifest:
 
----
+**Imported object** — simplest; bundle the manifest with the app.
 
-**Maintained for OIDC setup purposes only**
+```ts
+componentsPlugin({ manifest: { type: 'object', manifest: importedManifest } })
+```
+
+**Remote URL** — for design systems deployed independently.
+
+```ts
+componentsPlugin({
+  manifest: {
+    type: 'url',
+    url: 'https://design-system.example.com/manifest.json',
+    refreshInterval: 3600, // seconds; manifest is re-fetched after the TTL expires
+  },
+})
+```
+
+**Payload collection** — when the manifest is admin-editable.
+
+```ts
+componentsPlugin({
+  manifest: { type: 'payload-collection', slug: 'design-system-manifest' },
+})
+```
+
+The loader reads the most recent document by `updatedAt`, optionally filtered by `documentId`, and looks for a `data` field on it before falling back to the document itself.
+
+## Intent matching
+
+The current shipping strategy is **TF-IDF**: zero external dependencies, weights `intent` more than `description`, fast enough that the first response after deploy is sub-100ms.
+
+```ts
+componentsPlugin({
+  manifest: { /* ... */ },
+  matching: { strategy: 'tfidf', maxRecommendations: 5 },
+})
+```
+
+An embeddings-based matcher is on the roadmap. The matcher interface is strategy-agnostic, so swapping it in won't change the tool surface. Until then, real recommendation quality depends on contract authoring — specifically, on how vividly each `intent` field describes the component's editorial purpose.
+
+## Composition rules enforced
+
+`validate_composition` checks:
+
+- **`forbiddenAdjacent`** — neither the previous nor next block can be the forbidden type
+- **`maxPerPage`** — total occurrences in the block list don't exceed the contract's `maxPerPage`
+- **`requiredSiblings`** — warns (not errors) when a sibling that the contract expects isn't present
+- **Unknown components** — flagged as an error
+- **Unknown variants** — flagged as an error per block
+
+`find_anti_pattern` surfaces:
+
+- "Multiple X" labels when X appears more than once in the block list
+- "End of page" / "bottom" labels when an X with `placement: ['page']` lands as the last block
+
+The two tools are complementary. Use `validate_composition` to gate publishing and `find_anti_pattern` to surface design quality issues that aren't strictly invalid.
+
+## The `_meta` parameter
+
+`suggest_for_intent`, `validate_composition`, and `find_anti_pattern` all accept the framework's `_meta` payload (via `withMeta` from `@forumone/throughline-core`):
+
+```jsonc
+{
+  "intent": "introduce a new climate fellowship",
+  "_meta": {
+    "userPrompt": "I want a hero for the new climate program",
+    "reasoning": "The marketer asked for a page opener, not a section header",
+    "changesSummary": "Recommended Hero (split variant) for the program landing"
+  }
+}
+```
+
+The audit writer reads these fields and stores them on every record so "why did Claude recommend Hero for the contact page?" is answerable later.
+
+## Related packages
+
+- `@forumone/throughline-design-contract` — the manifest schema this plugin reads
+- `@forumone/throughline-reference-ds` — reference DS used as a test fixture and a starting point for clients
+- `@forumone/throughline-core` — required peer; provides the audit log, MCP handler, and `withMeta` helper this plugin builds on

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { componentsPlugin } from './plugin.js';
+export type { ComponentsPluginOptions, ManifestSource, MatchingConfig } from './options.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { componentsPlugin } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}

package/dist/manifest-source.d.ts

@@ -0,0 +1,17 @@
+import type { Payload } from 'payload';
+import { type LoadedManifest } from '@forumone/throughline-design-contract';
+import type { ManifestSource } from './options.js';
+export interface ManifestLoader {
+    /** Returns the cached manifest, refreshing if the URL TTL has expired. */
+    get(): Promise<LoadedManifest>;
+    /** Forces a re-fetch from the source. */
+    refresh(): Promise<LoadedManifest>;
+}
+/**
+ * Builds a manifest loader from a source descriptor. The loader caches the
+ * parsed manifest indefinitely for `object` and `payload-collection` sources;
+ * for `url` sources it honors `refreshInterval` (seconds) and re-fetches when
+ * the cached copy is older than that.
+ */
+export declare function createManifestLoader(source: ManifestSource, payload: Payload): ManifestLoader;
+//# sourceMappingURL=manifest-source.d.ts.map

package/dist/manifest-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-source.d.ts","sourceRoot":"","sources":["../src/manifest-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAC9B,yCAAyC;IACzC,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAuD7F"}

package/dist/manifest-source.js

@@ -0,0 +1,60 @@
+import { loadManifest, loadManifestFromUrl, } from '@forumone/throughline-design-contract';
+/**
+ * Builds a manifest loader from a source descriptor. The loader caches the
+ * parsed manifest indefinitely for `object` and `payload-collection` sources;
+ * for `url` sources it honors `refreshInterval` (seconds) and re-fetches when
+ * the cached copy is older than that.
+ */
+export function createManifestLoader(source, payload) {
+    let cached = null;
+    let lastLoadedAt = 0;
+    async function load() {
+        switch (source.type) {
+            case 'object':
+                return loadManifest(source.manifest);
+            case 'url':
+                return loadManifestFromUrl(source.url);
+            case 'payload-collection': {
+                const where = source.documentId
+                    ? { id: { equals: source.documentId } }
+                    : undefined;
+                const result = await payload.find({
+                    collection: source.slug,
+                    ...(where ? { where } : {}),
+                    limit: 1,
+                    sort: '-updatedAt',
+                });
+                const doc = result.docs[0];
+                if (!doc) {
+                    const idClause = source.documentId ? ` with id "${source.documentId}"` : '';
+                    throw new Error(`No manifest document found in collection "${source.slug}"${idClause}`);
+                }
+                const candidate = (doc['data'] ?? doc);
+                return loadManifest(candidate);
+            }
+        }
+    }
+    return {
+        async get() {
+            if (cached) {
+                if (source.type === 'url' && source.refreshInterval !== undefined) {
+                    const ageMs = Date.now() - lastLoadedAt;
+                    if (ageMs > source.refreshInterval * 1000) {
+                        cached = await load();
+                        lastLoadedAt = Date.now();
+                    }
+                }
+                return cached;
+            }
+            cached = await load();
+            lastLoadedAt = Date.now();
+            return cached;
+        },
+        async refresh() {
+            cached = await load();
+            lastLoadedAt = Date.now();
+            return cached;
+        },
+    };
+}
+//# sourceMappingURL=manifest-source.js.map

package/dist/manifest-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-source.js","sourceRoot":"","sources":["../src/manifest-source.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,YAAY,EACZ,mBAAmB,GACpB,MAAM,uCAAuC,CAAA;AAU9C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,OAAgB;IAC3E,IAAI,MAAM,GAA0B,IAAI,CAAA;IACxC,IAAI,YAAY,GAAG,CAAC,CAAA;IAEpB,KAAK,UAAU,IAAI;QACjB,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,QAAQ;gBACX,OAAO,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YACtC,KAAK,KAAK;gBACR,OAAO,mBAAmB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxC,KAAK,oBAAoB,CAAC,CAAC,CAAC;gBAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU;oBAC7B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE;oBACvC,CAAC,CAAC,SAAS,CAAA;gBACb,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;oBAChC,UAAU,EAAE,MAAM,CAAC,IAAI;oBACvB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC3B,KAAK,EAAE,CAAC;oBACR,IAAI,EAAE,YAAY;iBACnB,CAAC,CAAA;gBACF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAwC,CAAA;gBACjE,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;oBAC3E,MAAM,IAAI,KAAK,CACb,6CAA6C,MAAM,CAAC,IAAI,IAAI,QAAQ,EAAE,CACvE,CAAA;gBACH,CAAC;gBACD,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAY,CAAA;gBACjD,OAAO,YAAY,CAAC,SAAS,CAAC,CAAA;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,CAAC,GAAG;YACP,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;oBAClE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAA;oBACvC,IAAI,KAAK,GAAG,MAAM,CAAC,eAAe,GAAG,IAAI,EAAE,CAAC;wBAC1C,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;wBACrB,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;oBAC3B,CAAC;gBACH,CAAC;gBACD,OAAO,MAAM,CAAA;YACf,CAAC;YACD,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;YACrB,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACzB,OAAO,MAAM,CAAA;QACf,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;YACrB,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACzB,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/matching/index.d.ts

@@ -0,0 +1,3 @@
+export { createTfidfMatcher } from './tfidf.js';
+export type { Matcher, RankedComponent, RankedSuggestion } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/matching/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/matching/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}

package/dist/matching/index.js

@@ -0,0 +1,2 @@
+export { createTfidfMatcher } from './tfidf.js';
+//# sourceMappingURL=index.js.map

package/dist/matching/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/matching/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/dist/matching/tfidf.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract';
+import type { Matcher } from './types.js';
+/**
+ * Simple TF-IDF matcher over component search documents. Indexed once at
+ * factory time; subsequent `rank()` calls scan the precomputed index.
+ *
+ * The search document weights `intent` more than `description`, and includes
+ * variant `whenToUse` text + example intents. Editorial language often shows
+ * up in those fields, so weighting them helps real intents like "introduce
+ * a new program" find the Hero's `intent` rather than its name.
+ */
+export declare function createTfidfMatcher(components: ComponentContract[]): Matcher;
+//# sourceMappingURL=tfidf.d.ts.map

package/dist/matching/tfidf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.d.ts","sourceRoot":"","sources":["../../src/matching/tfidf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,YAAY,CAAA;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,OAAO,CA8C3E"}

package/dist/matching/tfidf.js

@@ -0,0 +1,118 @@
+/**
+ * Simple TF-IDF matcher over component search documents. Indexed once at
+ * factory time; subsequent `rank()` calls scan the precomputed index.
+ *
+ * The search document weights `intent` more than `description`, and includes
+ * variant `whenToUse` text + example intents. Editorial language often shows
+ * up in those fields, so weighting them helps real intents like "introduce
+ * a new program" find the Hero's `intent` rather than its name.
+ */
+export function createTfidfMatcher(components) {
+    const index = components.map((component) => {
+        const document = makeSearchDocument(component);
+        const tokens = tokenize(document);
+        const termFreq = new Map();
+        for (const token of tokens) {
+            termFreq.set(token, (termFreq.get(token) ?? 0) + 1);
+        }
+        return { component, terms: termFreq, length: Math.max(tokens.length, 1) };
+    });
+    const docCount = index.length;
+    const docFreq = new Map();
+    for (const entry of index) {
+        for (const term of entry.terms.keys()) {
+            docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+        }
+    }
+    const idf = new Map();
+    for (const [term, df] of docFreq) {
+        idf.set(term, Math.log((docCount + 1) / (df + 1)) + 1);
+    }
+    return {
+        rank(query) {
+            const queryCounts = new Map();
+            for (const token of tokenize(query)) {
+                queryCounts.set(token, (queryCounts.get(token) ?? 0) + 1);
+            }
+            const scored = index.map((entry) => {
+                let score = 0;
+                for (const [term, queryCount] of queryCounts) {
+                    const docCountForTerm = entry.terms.get(term) ?? 0;
+                    if (docCountForTerm === 0)
+                        continue;
+                    const tf = docCountForTerm / entry.length;
+                    const termIdf = idf.get(term) ?? 0;
+                    score += tf * termIdf * queryCount;
+                }
+                return { component: entry.component, score };
+            });
+            scored.sort((a, b) => b.score - a.score);
+            return scored;
+        },
+    };
+}
+function makeSearchDocument(component) {
+    const parts = [
+        // Intent and description are the most-weighted fields. Repeat the intent
+        // twice so it dominates rankings when its terms match.
+        component.intent,
+        component.intent,
+        component.description,
+        component.name,
+        ...(component.content.variants ?? []).flatMap((v) => [v.name, v.whenToUse]),
+        ...component.examples.map((e) => e.intent),
+    ];
+    return parts.join(' ');
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+}
+const STOP_WORDS = new Set([
+    'the',
+    'and',
+    'for',
+    'with',
+    'that',
+    'this',
+    'have',
+    'has',
+    'had',
+    'are',
+    'was',
+    'were',
+    'been',
+    'being',
+    'will',
+    'would',
+    'should',
+    'could',
+    'may',
+    'might',
+    'must',
+    'shall',
+    'can',
+    'these',
+    'those',
+    'its',
+    'use',
+    'used',
+    'using',
+    'when',
+    'where',
+    'how',
+    'what',
+    'which',
+    'into',
+    'onto',
+    'than',
+    'then',
+    'them',
+    'they',
+    'their',
+    'there',
+]);
+//# sourceMappingURL=tfidf.js.map

package/dist/matching/tfidf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.js","sourceRoot":"","sources":["../../src/matching/tfidf.ts"],"names":[],"mappings":"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"}

package/dist/matching/types.d.ts

@@ -0,0 +1,22 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract';
+export interface RankedComponent {
+    component: ComponentContract;
+    score: number;
+}
+export interface Matcher {
+    /** Returns the indexed components ranked best-first against the query. */
+    rank(query: string): RankedComponent[];
+}
+/**
+ * Surface returned by {@link suggest_for_intent}. Same shape regardless of the
+ * underlying matcher.
+ */
+export interface RankedSuggestion {
+    component: string;
+    score: number;
+    reasoning: string;
+    matchedIntent: string;
+    variant?: string;
+    warnings?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/matching/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/matching/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAE9E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,iBAAiB,CAAA;IAC5B,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,OAAO;IACtB,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAAA;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB"}

package/dist/matching/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/matching/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/matching/types.ts"],"names":[],"mappings":""}

package/dist/options.d.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import type { BaseCorePluginOptions } from '@forumone/throughline-plugin-contract';
+import type { Manifest } from '@forumone/throughline-design-contract';
+export type ManifestSource = {
+    type: 'object';
+    manifest: Manifest;
+} | {
+    type: 'url';
+    url: string;
+    refreshInterval?: number;
+} | {
+    type: 'payload-collection';
+    slug: string;
+    documentId?: string;
+};
+export interface MatchingConfig {
+    /**
+     * Strategy for ranking components against a natural-language intent.
+     * `tfidf` ships now and requires no external dependencies; `embeddings`
+     * is reserved for a follow-up.
+     */
+    strategy: 'tfidf';
+    /** Maximum number of recommendations from `suggest_for_intent`. Default: 5. */
+    maxRecommendations?: number;
+}
+export interface ComponentsPluginOptions extends BaseCorePluginOptions {
+    /** Required: where the design system manifest comes from. */
+    manifest: ManifestSource;
+    /** Optional: how the plugin matches intents to components. Defaults to TF-IDF. */
+    matching?: MatchingConfig;
+}
+export declare const ComponentsPluginOptionsSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    routePrefix: z.ZodOptional<z.ZodString>;
+    manifest: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+        manifest: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        type: "object";
+        manifest?: unknown;
+    }, {
+        type: "object";
+        manifest?: unknown;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"url">;
+        url: z.ZodString;
+        refreshInterval: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        type: "url";
+        refreshInterval?: number | undefined;
+    }, {
+        url: string;
+        type: "url";
+        refreshInterval?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"payload-collection">;
+        slug: z.ZodString;
+        documentId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "payload-collection";
+        slug: string;
+        documentId?: string | undefined;
+    }, {
+        type: "payload-collection";
+        slug: string;
+        documentId?: string | undefined;
+    }>]>;
+    matching: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodEnum<["tfidf"]>;
+        maxRecommendations: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "tfidf";
+        maxRecommendations?: number | undefined;
+    }, {
+        strategy: "tfidf";
+        maxRecommendations?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    manifest: {
+        type: "object";
+        manifest?: unknown;
+    } | {
+        url: string;
+        type: "url";
+        refreshInterval?: number | undefined;
+    } | {
+        type: "payload-collection";
+        slug: string;
+        documentId?: string | undefined;
+    };
+    matching?: {
+        strategy: "tfidf";
+        maxRecommendations?: number | undefined;
+    } | undefined;
+    enabled?: boolean | undefined;
+    routePrefix?: string | undefined;
+}, {
+    manifest: {
+        type: "object";
+        manifest?: unknown;
+    } | {
+        url: string;
+        type: "url";
+        refreshInterval?: number | undefined;
+    } | {
+        type: "payload-collection";
+        slug: string;
+        documentId?: string | undefined;
+    };
+    matching?: {
+        strategy: "tfidf";
+        maxRecommendations?: number | undefined;
+    } | undefined;
+    enabled?: boolean | undefined;
+    routePrefix?: string | undefined;
+}>;
+/**
+ * Validates plugin options at load time. Throws with a multi-line message
+ * on schema failure or with a targeted message on cross-field violations.
+ * Plugins that depend on this server must initialize after `componentsPlugin`
+ * because the registry capability check happens during onInit.
+ */
+export declare function validateOptions(options: ComponentsPluginOptions): ComponentsPluginOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAA;AAErE,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,6DAA6D;IAC7D,QAAQ,EAAE,cAAc,CAAA;IACxB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAgBD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUxC,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CASzF"}