@forumone/throughline-design-contract 0.0.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @forumone/throughline-design-contract
+
+## 0.3.0
+
+### Minor Changes
+
+- 24bd325: Add an optional `group` to the component contract, so an authoring UI can shelve components separately from what they are.
+
+  `category` was answering two questions at once — what a component _is_, and where an editor looks for it — and it is a bad answer to the second at any real size. A design system of sixty blocks files roughly half of them under `section`, so a picker grouped on `category` hands back the flat list the grouping was meant to avoid while `card` and `navigation` hold one entry each. Evening the shelves out within `category` would file components under the wrong kind for every consumer that reasons about kind, including `list_components`.
+
+  So `category` keeps its meaning and its enum, and `group` takes the second question with a vocabulary of shelf labels: `hero`, `narrative`, `proof`, `listing`, `media`, `form`, `cta`, `navigation`, `utility`. No `section`, which is the problem being solved; no `card` or `data`, which name a kind rather than a place to look.
+
+  New API: `groupOf(component)` resolves `group ?? category`, and `LoadedManifest` gains `listByGroup()` and `listGroups()` which match on the resolved value. Grouping consumers should call `groupOf` rather than reading either field.
+
+  Non-breaking. `group` is optional, and the fallback means a design system that sets none groups exactly as it did before.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#9](https://github.com/forumone/throughline/pull/9) [`337f2ca`](https://github.com/forumone/throughline/commit/337f2ca779a30d2f135845259bbae8e961a625ed) Thanks [@briangraves](https://github.com/briangraves)! - Initial release. Defines `ComponentContractSchema`, `ManifestSchema`, `loadManifest`, `loadManifestFromUrl`, and `lintManifest`. Every design system that satisfies this contract is a valid input to the framework's Component Server.

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,179 @@
 # @forumone/throughline-design-contract
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+The contract every AI-ready design system satisfies to be consumable by Throughline.
 
-**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.
+- **`ComponentContractSchema`** — the Zod schema for per-component metadata (intent, composition rules, content fields, tokens, accessibility, examples).
+- **`ManifestSchema`** — the aggregated JSON format a design system publishes, versioned via `contractVersion`.
+- **`loadManifest` / `loadManifestFromUrl`** — runtime loaders with strict validation and a readable error format.
+- **`lintManifest`** (via the `/lint` subpath) — CI-runnable consistency checks for design system repos.
 
-## Purpose
+Zero runtime dependencies beyond Zod. Safe to import into client apps, design systems, and server packages alike.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@forumone/throughline-design-contract`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Installation
 
-## What is OIDC Trusted Publishing?
+```bash
+pnpm add @forumone/throughline-design-contract
+```
 
-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.
+## Authoring contracts in a design system
 
-## Setup Instructions
+Each component has a co-located contract file:
 
-To properly configure OIDC trusted publishing for this package:
+```
+src/components/Hero/
+├── Hero.tsx
+├── Hero.stories.tsx
+├── Hero.contract.ts
+└── index.ts
+```
 
-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
+`Hero.contract.ts` exports a single object that satisfies `ComponentContract`:
 
-## DO NOT USE THIS PACKAGE
+```typescript
+import type { ComponentContract } from '@forumone/throughline-design-contract'
 
-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 const contract: ComponentContract = {
+  name: 'Hero',
+  category: 'hero',
+  description: 'A page opener with a headline and optional call-to-action.',
+  intent:
+    'Used to establish what a page is about within the first viewport. Appropriate for top-level pages that need editorial framing.',
+  composition: {
+    placement: ['page'],
+    maxPerPage: 1,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Hero'],
+  },
+  content: {
+    fields: [{ name: 'headline', type: 'text', required: true, maxLength: 80 }],
+  },
+  tokens: { consumes: ['color.brand.primary'] },
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior: 'Headline is announced as h1 by default.',
+    contentWarnings: [],
+  },
+  examples: [{ label: 'Default', intent: 'Standard page opener', storyId: 'hero--default' }],
+  antiExamples: [
+    { label: 'Stacked heroes', why: 'Breaks the visual rhythm.', useInstead: 'Section' },
+  ],
+}
+```
 
-## More Information
+Your design system's build tooling aggregates these into a `Manifest`. See the reference design system for a canonical example.
 
-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)
+## `category` and `group`
 
----
+Two fields, two questions.
 
-**Maintained for OIDC setup purposes only**
+`category` is what the component **is** — `hero`, `section`, `card`, `media`, `cta`, `navigation`, `data`, `form`, `utility`. It is required, and consumers reason about it as a kind: `list_components` in the components MCP server filters on it.
+
+`group` is where an **editor looks for it** — `hero`, `narrative`, `proof`, `listing`, `media`, `form`, `cta`, `navigation`, `utility`. It is optional, and exists because `category` is a bad answer to that second question at any real size. A design system of sixty blocks files roughly half of them under `section`, so an authoring UI grouped on `category` hands back the flat list the grouping was meant to avoid, while `card` and `navigation` hold one entry each. Evening the shelves out by moving components between categories would file them under the wrong *kind* for every other consumer, so the fix is a second field rather than a looser first one.
+
+There is deliberately no `section` in the group vocabulary — a shelf holding half the library is the problem this field exists to solve — and no `card` or `data`, both of which name a kind rather than a place to look.
+
+Read the resolved value with `groupOf`, never either field directly:
+
+```typescript
+import { groupOf } from '@forumone/throughline-design-contract'
+
+groupOf({ category: 'section', group: 'proof' }) // 'proof'
+groupOf({ category: 'hero' })                    // 'hero' — falls back
+```
+
+The fallback is what makes this a non-breaking addition: a design system that sets no `group` anywhere groups exactly as it did before the field existed, and one part-way through adopting it stays consistent instead of grouping half one way and half the other.
+
+## Loading a manifest at runtime
+
+```typescript
+import { loadManifest } from '@forumone/throughline-design-contract'
+import manifest from '@my-company/design-system/manifest.json'
+
+const loaded = loadManifest(manifest)
+
+const hero = loaded.requireComponent('Hero')
+console.log(hero.intent)
+
+for (const name of loaded.listByCategory('card')) {
+  console.log(name)
+}
+
+// Grouped for an authoring UI. Matches on the resolved group, so components
+// with no `group` are found by their category.
+for (const shelf of loaded.listGroups()) {
+  console.log(shelf, loaded.listByGroup(shelf).length)
+}
+```
+
+Invalid manifests throw immediately with a path-qualified error message. The loader never partially loads invalid data.
+
+### Loading over HTTP
+
+```typescript
+import { loadManifestFromUrl } from '@forumone/throughline-design-contract'
+
+const loaded = await loadManifestFromUrl('https://ds.example.com/manifest.json')
+```
+
+## Linting in CI
+
+Every design system should lint its own manifest before publishing. Import the lint helpers from the `/lint` subpath:
+
+```typescript
+import { lintManifest, formatLintIssues } from '@forumone/throughline-design-contract/lint'
+import manifest from './dist/manifest.json'
+
+const issues = lintManifest(manifest, {
+  availableStoryIds: new Set(/* collected from storybook-static */),
+})
+
+if (issues.some((i) => i.severity === 'error')) {
+  console.error(formatLintIssues(issues))
+  process.exit(1)
+}
+```
+
+`lintManifest` checks:
+
+- Every `requiredSiblings` and `forbiddenAdjacent` entry references a real component in the manifest.
+- Every token in `tokens.consumes` exists in the manifest's token table (or in `availableTokens` if you pass one).
+- Every example's `storyId` exists in `availableStoryIds` (skipped when the option is omitted).
+- Warnings: components with no anti-examples; intent statements shorter than 50 characters.
+
+`assertManifestClean(manifest, options)` is the CI-friendly form: throws on any error, silent on warnings-only.
+
+## Versioning
+
+The current contract version is `1.0.0`, exported as `CONTRACT_VERSION`. Manifests declare it via the `contractVersion` field; the loader rejects mismatches so Claude never recommends a component from a schema it does not understand.
+
+When the contract evolves, this package ships a new major version with migration guidance in the changelog.
+
+## Relationship to Storybook AI manifests
+
+Storybook ships its own [AI manifest format](https://storybook.js.org/docs/ai/manifests) (`/manifests/components.json`). It is a static-analysis artifact that describes what *exists* in a Storybook — component ids, paths, props with types and JSDoc, story ids, import statements. Storybook marks it as preview / unstable.
+
+This package's contract describes what's *appropriate* — intent, composition rules, accessibility expectations, anti-examples, token consumption. Hand-authored, stable, versioned.
+
+They complement rather than overlap. Typical integration: during a design system's CI, parse Storybook's `components.json`, collect every `stories[].id`, and pass the set to `lintManifest` as `availableStoryIds`. That gives you the "does this `storyId` resolve to a real story?" check for free:
+
+```typescript
+import storybookManifest from './storybook-static/manifests/components.json'
+import contractManifest from './dist/manifest.json'
+import { lintManifest } from '@forumone/throughline-design-contract/lint'
+
+const availableStoryIds = new Set(
+  Object.values(storybookManifest.components).flatMap((c: { stories: Array<{ id: string }> }) =>
+    c.stories.map((s) => s.id),
+  ),
+)
+
+const issues = lintManifest(contractManifest, { availableStoryIds })
+```
+
+## Related packages
+
+- `@forumone/throughline-reference-ds` — a reference design system that satisfies this contract (C3).
+- `@forumone/throughline-components` — the Component Server MCP that consumes manifests (C5).
+- `@forumone/throughline-plugin-contract` — the plugin contract for packages that extend Payload.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './schema.js';
+export * from './manifest.js';
+export * from './loader.js';
+export type { LintIssue, LintOptions } from './lint.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,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './schema.js';
+export * from './manifest.js';
+export * from './loader.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,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/dist/lint.d.ts

@@ -0,0 +1,38 @@
+import type { Manifest } from './manifest.js';
+export interface LintIssue {
+    severity: 'error' | 'warning';
+    component: string;
+    rule: string;
+    message: string;
+}
+export interface LintOptions {
+    /**
+     * Source of truth for Storybook story IDs. If provided, lint verifies
+     * every example's `storyId` exists in this set. Omit to skip the check
+     * (e.g. in environments that do not have Storybook output available).
+     */
+    availableStoryIds?: Set<string>;
+    /**
+     * Source of truth for token names. If provided, lint verifies every
+     * token referenced by a component's `tokens.consumes` exists in this set.
+     * Defaults to the manifest's own token table when omitted.
+     */
+    availableTokens?: Set<string>;
+}
+/**
+ * Lints a manifest against the contract's internal consistency rules.
+ * Returns an array of issues; an empty array means the manifest is clean.
+ *
+ * Errors describe unambiguous contract violations (unknown component
+ * references, unknown tokens). Warnings surface weaker signals that may
+ * still be worth addressing.
+ */
+export declare function lintManifest(manifest: Manifest, options?: LintOptions): LintIssue[];
+/** Formats lint issues as a multi-line string suitable for CI output. */
+export declare function formatLintIssues(issues: LintIssue[]): string;
+/**
+ * Throws when the manifest has any lint errors. Warnings do not throw.
+ * Use in CI to fail the build on contract violations.
+ */
+export declare function assertManifestClean(manifest: Manifest, options?: LintOptions): void;
+//# sourceMappingURL=lint.d.ts.map

package/dist/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,WAAgB,GAAG,SAAS,EAAE,CAyEvF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAwB5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAMnF"}

package/dist/lint.js

@@ -0,0 +1,110 @@
+/**
+ * Lints a manifest against the contract's internal consistency rules.
+ * Returns an array of issues; an empty array means the manifest is clean.
+ *
+ * Errors describe unambiguous contract violations (unknown component
+ * references, unknown tokens). Warnings surface weaker signals that may
+ * still be worth addressing.
+ */
+export function lintManifest(manifest, options = {}) {
+    const issues = [];
+    const componentNames = new Set(Object.keys(manifest.components));
+    const tokenNames = options.availableTokens ?? new Set(manifest.tokens.map((t) => t.name));
+    const storyIds = options.availableStoryIds;
+    for (const [name, component] of Object.entries(manifest.components)) {
+        for (const sibling of component.composition.requiredSiblings) {
+            if (!componentNames.has(sibling)) {
+                issues.push({
+                    severity: 'error',
+                    component: name,
+                    rule: 'composition.requiredSiblings',
+                    message: `References unknown component "${sibling}"`,
+                });
+            }
+        }
+        for (const adjacent of component.composition.forbiddenAdjacent) {
+            if (!componentNames.has(adjacent)) {
+                issues.push({
+                    severity: 'error',
+                    component: name,
+                    rule: 'composition.forbiddenAdjacent',
+                    message: `References unknown component "${adjacent}"`,
+                });
+            }
+        }
+        for (const token of component.tokens.consumes) {
+            if (!tokenNames.has(token)) {
+                issues.push({
+                    severity: 'error',
+                    component: name,
+                    rule: 'tokens.consumes',
+                    message: `References unknown token "${token}"`,
+                });
+            }
+        }
+        if (storyIds) {
+            for (const example of component.examples) {
+                if (!storyIds.has(example.storyId)) {
+                    issues.push({
+                        severity: 'error',
+                        component: name,
+                        rule: 'examples.storyId',
+                        message: `Example "${example.label}" references unknown story "${example.storyId}"`,
+                    });
+                }
+            }
+        }
+        if (component.antiExamples.length === 0) {
+            issues.push({
+                severity: 'warning',
+                component: name,
+                rule: 'antiExamples.empty',
+                message: 'Component has no anti-examples; consider adding at least one',
+            });
+        }
+        if (component.intent.length < 50) {
+            issues.push({
+                severity: 'warning',
+                component: name,
+                rule: 'intent.brevity',
+                message: 'Intent statement is quite short; consider a more specific description',
+            });
+        }
+    }
+    return issues;
+}
+/** Formats lint issues as a multi-line string suitable for CI output. */
+export function formatLintIssues(issues) {
+    if (issues.length === 0)
+        return 'No issues found.';
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    const lines = [];
+    if (errors.length > 0) {
+        lines.push(`Errors (${errors.length}):`);
+        for (const issue of errors) {
+            lines.push(`  [${issue.component}] ${issue.rule}: ${issue.message}`);
+        }
+    }
+    if (warnings.length > 0) {
+        if (lines.length > 0)
+            lines.push('');
+        lines.push(`Warnings (${warnings.length}):`);
+        for (const issue of warnings) {
+            lines.push(`  [${issue.component}] ${issue.rule}: ${issue.message}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Throws when the manifest has any lint errors. Warnings do not throw.
+ * Use in CI to fail the build on contract violations.
+ */
+export function assertManifestClean(manifest, options) {
+    const issues = lintManifest(manifest, options);
+    const errors = issues.filter((i) => i.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`Manifest has errors:\n${formatLintIssues(errors)}`);
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

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

package/dist/loader.d.ts

@@ -0,0 +1,49 @@
+import { type Manifest } from './manifest.js';
+import type { ComponentContract, ComponentCategory, ComponentGroup } from './schema.js';
+/**
+ * A validated, queryable manifest. Returned by {@link loadManifest} and
+ * {@link loadManifestFromUrl}. Consumers use the helper methods rather than
+ * poking at {@link raw} directly, which lets the implementation evolve.
+ */
+export declare class LoadedManifest {
+    readonly raw: Manifest;
+    constructor(raw: Manifest);
+    /** The design system's metadata. */
+    get designSystem(): Manifest['designSystem'];
+    /** The contract version this manifest satisfies. */
+    get contractVersion(): Manifest['contractVersion'];
+    /** Full contract for a component by name, or `undefined` if absent. */
+    getComponent(name: string): ComponentContract | undefined;
+    /** Like {@link getComponent} but throws when the component is missing. */
+    requireComponent(name: string): ComponentContract;
+    /** Every component name in declaration order. */
+    listComponents(): string[];
+    /** Every component whose category matches. */
+    listByCategory(category: ComponentCategory | string): ComponentContract[];
+    /** Every distinct category present, sorted alphabetically. */
+    listCategories(): string[];
+    /**
+     * Every component filed under a shelf. Matches on the resolved group, so a
+     * component with no `group` is found by its category.
+     */
+    listByGroup(group: ComponentGroup | string): ComponentContract[];
+    /** Every distinct resolved group present, sorted alphabetically. */
+    listGroups(): string[];
+    /** Token definition by name, or `undefined` if absent. */
+    getToken(name: string): {
+        value: string;
+        name: string;
+        category: string;
+    } | undefined;
+}
+/**
+ * Loads a manifest from a plain object. Validates against {@link ManifestSchema}
+ * and throws on any validation error with a readable, line-by-line message.
+ */
+export declare function loadManifest(input: unknown): LoadedManifest;
+/**
+ * Fetches a manifest from a URL and loads it. Useful when a design system
+ * serves its manifest via HTTP rather than bundling into the consumer.
+ */
+export declare function loadManifestFromUrl(url: string, init?: RequestInit): Promise<LoadedManifest>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,eAAe,CAAA;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEvF;;;;GAIG;AACH,qBAAa,cAAc;aACG,GAAG,EAAE,QAAQ;gBAAb,GAAG,EAAE,QAAQ;IAEzC,oCAAoC;IACpC,IAAI,YAAY,IAAI,QAAQ,CAAC,cAAc,CAAC,CAE3C;IAED,oDAAoD;IACpD,IAAI,eAAe,IAAI,QAAQ,CAAC,iBAAiB,CAAC,CAEjD;IAED,uEAAuE;IACvE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIzD,0EAA0E;IAC1E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;IAQjD,iDAAiD;IACjD,cAAc,IAAI,MAAM,EAAE;IAI1B,8CAA8C;IAC9C,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,iBAAiB,EAAE;IAIzE,8DAA8D;IAC9D,cAAc,IAAI,MAAM,EAAE;IAQ1B;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,iBAAiB,EAAE;IAIhE,oEAAoE;IACpE,UAAU,IAAI,MAAM,EAAE;IAQtB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM;;;;;CAGtB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAS3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,cAAc,CAAC,CAOzB"}

package/dist/loader.js

@@ -0,0 +1,95 @@
+import { ManifestSchema } from './manifest.js';
+import { groupOf } from './schema.js';
+/**
+ * A validated, queryable manifest. Returned by {@link loadManifest} and
+ * {@link loadManifestFromUrl}. Consumers use the helper methods rather than
+ * poking at {@link raw} directly, which lets the implementation evolve.
+ */
+export class LoadedManifest {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** The design system's metadata. */
+    get designSystem() {
+        return this.raw.designSystem;
+    }
+    /** The contract version this manifest satisfies. */
+    get contractVersion() {
+        return this.raw.contractVersion;
+    }
+    /** Full contract for a component by name, or `undefined` if absent. */
+    getComponent(name) {
+        return this.raw.components[name];
+    }
+    /** Like {@link getComponent} but throws when the component is missing. */
+    requireComponent(name) {
+        const component = this.getComponent(name);
+        if (!component) {
+            throw new Error(`Component "${name}" not found in manifest`);
+        }
+        return component;
+    }
+    /** Every component name in declaration order. */
+    listComponents() {
+        return Object.keys(this.raw.components);
+    }
+    /** Every component whose category matches. */
+    listByCategory(category) {
+        return Object.values(this.raw.components).filter((c) => c.category === category);
+    }
+    /** Every distinct category present, sorted alphabetically. */
+    listCategories() {
+        const categories = new Set();
+        for (const component of Object.values(this.raw.components)) {
+            categories.add(component.category);
+        }
+        return Array.from(categories).sort();
+    }
+    /**
+     * Every component filed under a shelf. Matches on the resolved group, so a
+     * component with no `group` is found by its category.
+     */
+    listByGroup(group) {
+        return Object.values(this.raw.components).filter((c) => groupOf(c) === group);
+    }
+    /** Every distinct resolved group present, sorted alphabetically. */
+    listGroups() {
+        const groups = new Set();
+        for (const component of Object.values(this.raw.components)) {
+            groups.add(groupOf(component));
+        }
+        return Array.from(groups).sort();
+    }
+    /** Token definition by name, or `undefined` if absent. */
+    getToken(name) {
+        return this.raw.tokens.find((t) => t.name === name);
+    }
+}
+/**
+ * Loads a manifest from a plain object. Validates against {@link ManifestSchema}
+ * and throws on any validation error with a readable, line-by-line message.
+ */
+export function loadManifest(input) {
+    const result = ManifestSchema.safeParse(input);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid manifest:\n${issues}`);
+    }
+    return new LoadedManifest(result.data);
+}
+/**
+ * Fetches a manifest from a URL and loads it. Useful when a design system
+ * serves its manifest via HTTP rather than bundling into the consumer.
+ */
+export async function loadManifestFromUrl(url, init) {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch manifest from ${url}: HTTP ${response.status}`);
+    }
+    const json = (await response.json());
+    return loadManifest(json);
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

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