@santi020k/lumen 1.8.0 → 2.1.0

package/README.md

@@ -68,6 +68,9 @@ diagnostics are scoped to the nearest package boundary, generated build trees ar
 application-controlled Astro `Toggle` instances do not require the shared runtime. It also suggests
 matching Lumen primitives for likely hand-built dropdown, theme, dialog-focus, and keyboard-menu
 behavior. These suggestions stay advisory because product-specific composition can be intentional.
+Publishable shared UI libraries are not required to load global styles. Private wrapper packages
+can declare `"lumen": { "styleOwnership": "consumer" }` when their applications own adapter CSS,
+or `"application"` when the package itself owns setup.
 Use `--json` for CI and rollout automation. `lumen init --framework <astro|react|elements>
 [--tailwind]` prints the canonical non-destructive setup.
 

package/dist/cli.js

@@ -91,6 +91,29 @@ const getRegistryItemComponents = (item) => 'components' in item && Array.isArra
 const getRegistryItemDependencies = (item) => 'dependencies' in item && item.dependencies.length > 0 ?
     `dependencies: ${item.dependencies.join(', ')}` :
     undefined;
+const formatContractProp = (prop) => `${prop.name}: ${prop.type}${prop.required ? ' (required)' : ''}${prop.default ? ` = ${prop.default}` : ''}`;
+const formatContractList = (label, values, separator) => values?.length ? `${label}: ${values.join(separator)}` : undefined;
+const getRegistryItemContract = (item) => {
+    if (item.type !== 'component')
+        return [];
+    const contract = item.contract;
+    if (!contract)
+        return [];
+    const optionalLines = [
+        formatContractList('props', contract.props?.map(formatContractProp), '; '),
+        formatContractList('composition', contract.composition, ' '),
+        formatContractList('events', contract.events, ', '),
+        formatContractList('slots', contract.slots, ', '),
+        contract.runtime ? `runtime: ${contract.runtime}` : undefined,
+        formatContractList('styling parts', contract.stylingParts, ', '),
+        formatContractList('tokens', contract.tokens, ', ')
+    ].filter((line) => Boolean(line));
+    return [
+        ...Object.entries(contract.imports).map(([framework, value]) => `import (${framework}): ${value}`),
+        ...Object.entries(contract.usage).map(([framework, value]) => `usage (${framework}): ${value}`),
+        ...optionalLines
+    ];
+};
 const formatItem = (itemName, registry = lumenRegistry) => {
     const item = getLumenRegistryItem(itemName, registry);
     if (!item) {
@@ -102,7 +125,8 @@ const formatItem = (itemName, registry = lumenRegistry) => {
         getRegistryItemDescription(item),
         getRegistryItemCategory(item),
         getRegistryItemComponents(item),
-        getRegistryItemDependencies(item)
+        getRegistryItemDependencies(item),
+        ...getRegistryItemContract(item)
     ];
     const files = getRegistryItemFiles(item);
     if (files) {
@@ -260,8 +284,10 @@ const run = async () => {
             break;
         }
         case 'show': {
-            if (name)
-                output = formatItem(name, registry);
+            if (name) {
+                const item = getLumenRegistryItem(name, registry);
+                output = json && item ? JSON.stringify(item, undefined, 2) : formatItem(name, registry);
+            }
             break;
         }
     }

package/dist/integration-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration-diagnostics.d.ts","sourceRoot":"","sources":["../src/integration-diagnostics.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,uBAAuB,CAAA;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,QAAQ,EAAE,sBAAsB,EAAE,CAAA;IAClC,UAAU,EAAE,CAAC,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC,EAAE,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B;AA8eD,eAAO,MAAM,uBAAuB,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,qBAAqB,CA8C/F,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,QAAQ,qBAAqB,KAAG,MAWtE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,WAAW,OAAO,GAAG,UAAU,GAAG,OAAO,EAAE,kBAAgB,KAAG,MAsC9F,CAAA"}
+{"version":3,"file":"integration-diagnostics.d.ts","sourceRoot":"","sources":["../src/integration-diagnostics.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,uBAAuB,CAAA;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,QAAQ,EAAE,sBAAsB,EAAE,CAAA;IAClC,UAAU,EAAE,CAAC,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC,EAAE,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B;AAowBD,eAAO,MAAM,uBAAuB,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,qBAAqB,CA4D/F,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,QAAQ,qBAAqB,KAAG,MAWtE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,WAAW,OAAO,GAAG,UAAU,GAAG,OAAO,EAAE,kBAAgB,KAAG,MAsC9F,CAAA"}

package/dist/integration-diagnostics.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { extname, join, relative, resolve, sep } from 'node:path';
-import { lumenComponentBehavior, lumenGlobalBehaviors, lumenStylingContracts } from '@santi020k/lumen-core';
+import { lumenComponentBehavior, lumenComponentNames, lumenGlobalBehaviors, lumenStylingContracts } from '@santi020k/lumen-core';
 const sourceExtensions = new Set(['.astro', '.css', '.js', '.jsx', '.mjs', '.ts', '.tsx']);
 const ignoredDirectories = new Set([
     '.astro',
@@ -19,7 +19,15 @@ const ignoredDirectories = new Set([
     'node_modules',
     'out'
 ]);
-const publicRootSlots = new Set(Object.values(lumenStylingContracts).flatMap(contract => [contract.rootSlot, ...contract.parts]));
+const stylingContracts = lumenStylingContracts;
+const publicRootSlots = new Set(Object.values(stylingContracts).flatMap(contract => [contract.rootSlot, ...contract.parts]));
+const componentClassName = (name) => name
+    .replace(/([a-z\d])([A-Z])/gu, '$1-$2')
+    .toLowerCase();
+const componentByClassName = new Map(lumenComponentNames.map((name) => [
+    componentClassName(name),
+    name
+]));
 const discoverProject = async (root) => {
     const packageRoots = [];
     const sourceFiles = [];
@@ -86,7 +94,41 @@ const getFrameworks = (sources) => [
 const getBoundaryRoot = (file, packageRoots, fallback) => packageRoots
     .filter(packageRoot => file === packageRoot || file.startsWith(`${packageRoot}${sep}`))
     .sort((left, right) => right.length - left.length)[0] ?? fallback;
-const createBoundaries = (root, packageRoots, sources) => {
+const readPackageManifest = async (root) => {
+    try {
+        return JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const isPublishablePackageBoundary = (repositoryPath, manifest) => repositoryPath.includes('packages') && manifest?.private !== true;
+const hasApplicationSource = (boundaryRoot, sources) => sources.some(item => /(?:^|\/)(?:app|pages|routes|layouts?)(?:\/|$)/iu.test(relative(boundaryRoot, item.file)));
+const hasApplicationScript = (manifest) => {
+    if (manifest?.private !== true)
+        return false;
+    return Boolean(manifest.scripts?.dev ?? manifest.scripts?.start);
+};
+const isWorkspaceBoundary = (repositoryRoot, boundaryRoot, packageRootCount) => boundaryRoot === repositoryRoot && packageRootCount > 1;
+const getFallbackBoundaryKind = (manifest) => manifest?.private === false ? 'library' : 'application';
+const classifyBoundary = (repositoryRoot, boundaryRoot, manifest, sources, packageRootCount) => {
+    const declaredKind = manifest?.lumen?.integrationBoundary;
+    if (declaredKind)
+        return declaredKind;
+    const repositoryPath = relative(repositoryRoot, boundaryRoot).split(sep);
+    if (repositoryPath.includes('apps'))
+        return 'application';
+    if (isPublishablePackageBoundary(repositoryPath, manifest))
+        return 'library';
+    if (hasApplicationSource(boundaryRoot, sources))
+        return 'application';
+    if (hasApplicationScript(manifest))
+        return 'application';
+    if (isWorkspaceBoundary(repositoryRoot, boundaryRoot, packageRootCount))
+        return 'workspace';
+    return getFallbackBoundaryKind(manifest);
+};
+const createBoundaries = async (root, packageRoots, sources) => {
     const grouped = new Map();
     for (const source of sources) {
         const boundaryRoot = getBoundaryRoot(source.file, packageRoots, root);
@@ -94,11 +136,43 @@ const createBoundaries = (root, packageRoots, sources) => {
         entries.push(source);
         grouped.set(boundaryRoot, entries);
     }
-    return [...grouped].map(([boundaryRoot, boundarySources]) => ({
-        root: boundaryRoot,
-        sources: boundarySources
+    return Promise.all([...grouped].map(async ([boundaryRoot, boundarySources]) => {
+        const manifest = await readPackageManifest(boundaryRoot);
+        const dependencies = [
+            ...Object.keys(manifest?.dependencies ?? {}),
+            ...Object.keys(manifest?.devDependencies ?? {}),
+            ...Object.keys(manifest?.peerDependencies ?? {})
+        ];
+        return {
+            dependencies,
+            kind: classifyBoundary(root, boundaryRoot, manifest, boundarySources, packageRoots.length),
+            ...(manifest?.name ? { packageName: manifest.name } : {}),
+            root: boundaryRoot,
+            sources: boundarySources
+        };
     }));
 };
+const getApplicationSources = (application, boundaries) => {
+    const byName = new Map(boundaries.flatMap(boundary => boundary.packageName ?
+        [[boundary.packageName, boundary]] :
+        []));
+    const sources = [...application.sources];
+    const visited = new Set();
+    const includeDependencies = (boundary) => {
+        for (const dependencyName of boundary.dependencies) {
+            if (visited.has(dependencyName))
+                continue;
+            visited.add(dependencyName);
+            const dependency = byName.get(dependencyName);
+            if (dependency?.kind !== 'library')
+                continue;
+            sources.push(...dependency.sources);
+            includeDependencies(dependency);
+        }
+    };
+    includeDependencies(application);
+    return sources;
+};
 const collectCompatibilityFindings = (root, sources) => sources.flatMap(item => {
     const file = relative(root, item.file);
     const findings = [];
@@ -108,6 +182,9 @@ const collectCompatibilityFindings = (root, sources) => sources.flatMap(item =>
     if (item.source.includes('ui:datatable-selection-change')) {
         findings.push(finding(file, 'deprecated-datatable-event', 'The ui:datatable-selection-change event alias is deprecated.', 'Rename it to ui:data-table-selection-change.', 'advisory'));
     }
+    if (importedNames(item.source, '@santi020k/lumen-astro').includes('UIPrimitives')) {
+        findings.push(finding(file, 'removed-root-export', 'UIPrimitives is no longer exported from the @santi020k/lumen-astro package root.', 'Import the default runtime from @santi020k/lumen-astro/runtime, or run lumen migrate-v2.'));
+    }
     return findings;
 });
 const hasImportedPrimitive = (sources, names) => [
@@ -156,6 +233,47 @@ const duplicatedBehaviorRules = [
         message: 'A raw menu with arrow-key handling may duplicate Lumen menu behavior.',
         remediation: 'Review DropdownMenu, Menubar, or NavigationMenu before maintaining a separate keyboard controller.',
         rule: 'hand-built-menu-keyboard'
+    },
+    {
+        detects: (source, sourceLower) => (source.includes('scrollY') || sourceLower.includes('scrolltop')) && (sourceLower.includes('scrollheight') || sourceLower.includes('scrollprogress')) && (source.includes('addEventListener(\'scroll\'') || source.includes('addEventListener("scroll"') ||
+            sourceLower.includes('onscroll')),
+        imports: ['ScrollProgress'],
+        message: 'Custom document scroll progress may duplicate Lumen ScrollProgress behavior.',
+        remediation: 'Review ScrollProgress before maintaining viewport measurement and progress synchronization.',
+        rule: 'hand-built-scroll-progress'
+    },
+    {
+        detects: (_source, sourceLower) => (sourceLower.includes('href="#main') || sourceLower.includes('href=\'#main')) && sourceLower.includes('skip'),
+        imports: ['SkipLink'],
+        message: 'A custom skip-to-content link may duplicate Lumen SkipLink behavior.',
+        remediation: 'Review SkipLink for its stable slot and fixed-position accessibility contract.',
+        rule: 'hand-built-skip-link'
+    },
+    {
+        detects: (source, sourceLower) => (source.includes('@radix-ui/react-slot') || sourceLower.includes('<slot')) && sourceLower.includes('aschild'),
+        imports: ['Button'],
+        message: 'A Radix Slot or asChild branch may duplicate Lumen Button composition.',
+        remediation: 'Review Button asChild before retaining a separate polymorphic action wrapper.',
+        rule: 'hand-built-polymorphic-button'
+    },
+    {
+        detects: (source, sourceLower) => sourceLower.includes('<input') &&
+            /\bsize\s*=\s*\{(?:size|props\.size)\}/u.test(source) &&
+            !source.includes('visualSize'),
+        imports: ['Input'],
+        message: 'A native input size passthrough may confuse HTML character width with Lumen visual sizing.',
+        remediation: 'Review Input visualSize and keep the native size attribute only when character width is intentional.',
+        rule: 'native-input-size-fallback'
+    },
+    {
+        detects: (source, sourceLower) => sourceLower.includes('card') &&
+            sourceLower.includes('card-header') &&
+            sourceLower.includes('card-content') &&
+            !source.includes('CardHeader'),
+        imports: ['Card'],
+        message: 'A hand-built card section hierarchy may duplicate Lumen Card compound parts.',
+        remediation: 'Review CardHeader, CardContent, and CardFooter while keeping domain-specific card content application-owned.',
+        rule: 'hand-built-card-structure'
     }
 ];
 const collectDuplicatedBehaviorFindings = (root, sources) => sources.flatMap(item => {
@@ -246,25 +364,63 @@ const styleImportByFramework = {
     react: '@santi020k/lumen-react/styles.css'
 };
 const countOccurrences = (source, value) => source.split(value).length - 1;
-const collectCssFindings = (root, sources) => sources
-    .filter(item => item.file.endsWith('.css'))
-    .flatMap(item => {
-    const layerIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["'][^"']*\/layers\.css["']/mu);
-    const tailwindIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["']tailwindcss["']/mu);
-    const styleIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["'][^"']*\/styles\.css["']/mu);
-    const findings = [];
-    if (tailwindIndex >= 0 &&
-        styleIndex >= 0 &&
-        (layerIndex < 0 || !(layerIndex < tailwindIndex && tailwindIndex < styleIndex))) {
-        findings.push(finding(relative(root, item.file), 'tailwind-layer-order', 'Tailwind and Lumen imports do not use the verified cascade order.', 'Import Lumen layers.css, then tailwindcss, then the matching Lumen styles.css.'));
+const getInternalSelectorContract = (selector) => {
+    const [componentClass = ''] = selector.split(/--|__/u, 1);
+    const component = componentByClassName.get(componentClass);
+    if (!component)
+        return {};
+    const contract = stylingContracts[component];
+    if (!contract)
+        return { component };
+    if (selector.includes('__')) {
+        const partName = selector.split('__', 2)[1]?.replaceAll('_', '-') ?? '';
+        const slot = `${contract.rootSlot}-${partName}`;
+        return contract.parts.includes(slot) ? { component, slot } : { component };
     }
-    for (const match of item.source.matchAll(/\.ui-([a-z0-9-]+)/g)) {
-        const selector = match[1] ?? '';
-        if (!publicRootSlots.has(selector)) {
-            findings.push(finding(relative(root, item.file), 'internal-selector', `Selector .ui-${selector} is not a documented stable root hook.`, 'Prefer component props, semantic tokens, documented custom properties, or [data-slot].', 'advisory'));
-        }
+    return { component, slot: contract.rootSlot };
+};
+const consumerClassGuidance = (frameworks) => {
+    const detectedFrameworks = new Set(frameworks);
+    const adapters = [
+        detectedFrameworks.has('astro') && 'the public class prop in Astro',
+        detectedFrameworks.has('react') && 'the public className prop in React',
+        detectedFrameworks.has('elements') && 'a class attribute on the Elements host'
+    ].filter((value) => Boolean(value));
+    if (adapters.length === 0) {
+        return 'Pass a consumer-owned class through the adapter\'s public class API.';
     }
-    return findings;
+    return `Pass a consumer-owned class through ${adapters.join(', ')}.`;
+};
+const internalSelectorFinding = (file, selector, frameworks) => {
+    const contract = getInternalSelectorContract(selector);
+    const componentContext = contract.component ?
+        ` It most likely targets the ${contract.component} component.` :
+        '';
+    const stableSlotGuidance = contract.slot ?
+        ` For a library-owned hook, use [data-slot="${contract.slot}"].` :
+        '';
+    return finding(file, 'internal-selector', `Selector .ui-${selector} is not a documented stable hook.${componentContext}`, `${consumerClassGuidance(frameworks)} Prefer semantic tokens and documented custom properties.${stableSlotGuidance}`, 'advisory');
+};
+const collectCssFindings = (root, boundaries) => boundaries.flatMap(boundary => {
+    const frameworks = getFrameworks(boundary.sources);
+    return boundary.sources.filter(item => item.file.endsWith('.css')).flatMap(item => {
+        const layerIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["'][^"']*\/layers\.css["']/mu);
+        const tailwindIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["']tailwindcss["']/mu);
+        const styleIndex = item.source.search(/^\s*@import\s+(?:url\(\s*)?["'][^"']*\/styles\.css["']/mu);
+        const findings = [];
+        if (tailwindIndex >= 0 &&
+            styleIndex >= 0 &&
+            (layerIndex < 0 || !(layerIndex < tailwindIndex && tailwindIndex < styleIndex))) {
+            findings.push(finding(relative(root, item.file), 'tailwind-layer-order', 'Tailwind and Lumen imports do not use the verified cascade order.', 'Import Lumen layers.css, then tailwindcss, then the matching Lumen styles.css.'));
+        }
+        for (const match of item.source.matchAll(/\.ui-([a-z0-9_-]+)/g)) {
+            const selector = match[1] ?? '';
+            if (!publicRootSlots.has(selector)) {
+                findings.push(internalSelectorFinding(relative(root, item.file), selector, frameworks));
+            }
+        }
+        return findings;
+    });
 });
 const collectFrameworkStyleFindings = (repositoryRoot, boundary, frameworks) => frameworks.flatMap(framework => {
     const styleImport = styleImportByFramework[framework];
@@ -291,6 +447,10 @@ const collectAdapterMismatchFindings = (repositoryRoot, boundary, frameworks) =>
         .filter(adapter => !frameworks.includes(adapter))
         .map(adapter => finding(relative(repositoryRoot, boundary.root) || '.', 'adapter-style-mismatch', `The ${adapter} stylesheet is loaded without matching ${adapter} imports in this application boundary.`, 'Load the stylesheet from the adapter used by this application boundary.'));
 };
+const collectSharedLibraryStyleFindings = (repositoryRoot, boundary) => Object.entries(styleImportByFramework)
+    .flatMap(([framework, styleImport]) => boundary.sources
+    .filter(item => item.source.includes(styleImport))
+    .map(item => finding(relative(repositoryRoot, item.file), 'shared-library-adapter-style', `A shared library loads the ${framework} adapter stylesheet, which can duplicate application-owned setup.`, 'Remove the adapter stylesheet from the shared package and load it once in each consuming application root.', 'advisory')));
 const uniqueFindings = (findings) => [
     ...new Map(findings.map(item => [
         `${item.file}\u0000${item.rule}\u0000${item.message}`,
@@ -306,18 +466,26 @@ export const inspectLumenIntegration = async (repository) => {
         file,
         source: await readFile(file, 'utf8')
     })));
-    const boundaries = createBoundaries(root, discovered.packageRoots, sources);
-    const frameworks = [...new Set(boundaries.flatMap(boundary => getFrameworks(boundary.sources)))];
+    const boundaries = await createBoundaries(root, discovered.packageRoots, sources);
+    const applicationBoundaries = boundaries.filter(boundary => boundary.kind === 'application');
+    const frameworks = [...new Set(applicationBoundaries.flatMap(boundary => getFrameworks(getApplicationSources(boundary, boundaries))))];
     const runtimeComponents = new Set();
     const findings = [
         ...collectCompatibilityFindings(root, sources),
-        ...collectCssFindings(root, sources)
+        ...collectCssFindings(root, boundaries)
     ];
-    for (const boundary of boundaries) {
-        const boundaryFrameworks = getFrameworks(boundary.sources);
-        const runtime = collectRuntimeFindings(root, boundary);
+    for (const boundary of boundaries.filter(item => item.kind === 'library')) {
+        findings.push(...collectSharedLibraryStyleFindings(root, boundary));
+    }
+    for (const boundary of applicationBoundaries) {
+        const effectiveBoundary = {
+            ...boundary,
+            sources: getApplicationSources(boundary, boundaries)
+        };
+        const boundaryFrameworks = getFrameworks(effectiveBoundary.sources);
+        const runtime = collectRuntimeFindings(root, effectiveBoundary);
         runtime.runtimeComponents.forEach(component => runtimeComponents.add(component));
-        findings.push(...collectDuplicatedBehaviorFindings(root, boundary.sources), ...runtime.findings, ...collectFrameworkStyleFindings(root, boundary, boundaryFrameworks), ...collectAdapterMismatchFindings(root, boundary, boundaryFrameworks));
+        findings.push(...collectDuplicatedBehaviorFindings(root, effectiveBoundary.sources), ...runtime.findings, ...collectFrameworkStyleFindings(root, boundary, boundaryFrameworks), ...collectAdapterMismatchFindings(root, boundary, boundaryFrameworks));
     }
     const deduplicatedFindings = uniqueFindings(findings);
     return {

package/dist/registry-data.d.ts

@@ -321,6 +321,42 @@ export declare const lumenRegistry: {
         readonly type: "component";
         readonly description: "Copies arbitrary text or the content of another element with accessible feedback.";
         readonly category: "Actions";
+        readonly contract: {
+            readonly imports: {
+                readonly astro: "import { CopyButton } from '@santi020k/lumen-astro'";
+            };
+            readonly usage: {
+                readonly astro: "<CopyButton value=\"https://example.com\" variant=\"default\">Copy link<span slot=\"copied\">Copied!</span><span slot=\"error\">Try again</span></CopyButton>";
+            };
+            readonly props: readonly [{
+                readonly name: "value";
+                readonly type: "string";
+            }, {
+                readonly name: "target";
+                readonly type: "string";
+            }, {
+                readonly name: "variant";
+                readonly type: "Button variant";
+                readonly default: "outline";
+            }, {
+                readonly name: "size";
+                readonly type: "default | sm | lg | icon";
+                readonly default: "default";
+            }, {
+                readonly name: "resetAfter";
+                readonly type: "number";
+                readonly default: "2000";
+            }, {
+                readonly name: "toast";
+                readonly type: "boolean";
+                readonly default: "false";
+            }];
+            readonly events: readonly ["ui:copy-success", "ui:copy-error"];
+            readonly slots: readonly ["default (idle)", "copied", "error"];
+            readonly runtime: "Mount the default export from @santi020k/lumen-astro/runtime once above the component.";
+            readonly stylingParts: readonly ["copy-button", "copy-idle", "copy-copied", "copy-error"];
+            readonly tokens: readonly ["brand-solid", "line", "surface-muted", "ink"];
+        };
         readonly files: readonly ["packages/astro/components/CopyButton.astro", "packages/astro/styles/lumen.css", "packages/astro/runtime/UIPrimitives.astro"];
         readonly dependencies: readonly ["styles", "runtime"];
     }, {
@@ -935,6 +971,38 @@ export declare const lumenRegistry: {
         readonly type: "component";
         readonly category: "Layout";
         readonly description: "Reveals a group of direct children with tokenized, reduced-motion-aware staggering.";
+        readonly contract: {
+            readonly imports: {
+                readonly astro: "import { RevealGroup } from '@santi020k/lumen-astro'";
+            };
+            readonly usage: {
+                readonly astro: "<RevealGroup as=\"ul\"><li>First</li><li>Second</li></RevealGroup>";
+            };
+            readonly props: readonly [{
+                readonly name: "as";
+                readonly type: "div | ul | ol | section";
+                readonly default: "div";
+            }, {
+                readonly name: "animation";
+                readonly type: "fade | slide-up | scale";
+                readonly default: "slide-up";
+            }, {
+                readonly name: "duration";
+                readonly type: "fast | standard | slow";
+                readonly default: "slow";
+            }, {
+                readonly name: "stagger";
+                readonly type: "number";
+                readonly default: "80";
+            }, {
+                readonly name: "once";
+                readonly type: "boolean";
+                readonly default: "true";
+            }];
+            readonly composition: readonly ["Children remain direct children of the selected semantic root."];
+            readonly runtime: "Mount the Astro runtime once; content remains readable before JavaScript and with reduced motion.";
+            readonly tokens: readonly ["motion-duration-fast", "motion-duration-standard", "motion-duration-slow"];
+        };
         readonly files: readonly ["packages/astro/components/RevealGroup.astro", "packages/astro/runtime/UIPrimitives.astro", "packages/astro/styles/lumen.css", "packages/react/src/components.tsx"];
         readonly dependencies: readonly ["styles", "runtime"];
     }, {
@@ -949,6 +1017,34 @@ export declare const lumenRegistry: {
         readonly type: "component";
         readonly category: "Data display";
         readonly description: "A stat component.";
+        readonly contract: {
+            readonly imports: {
+                readonly astro: "import { Stat, StatLabel, StatValue } from '@santi020k/lumen-astro'";
+                readonly react: "import { Stat, StatLabel, StatValue } from '@santi020k/lumen-react'";
+            };
+            readonly usage: {
+                readonly astro: "<Stat as=\"article\"><StatLabel>Revenue</StatLabel><StatValue>$12,400</StatValue></Stat>";
+                readonly react: "<Stat as=\"article\"><StatLabel>Revenue</StatLabel><StatValue>$12,400</StatValue></Stat>";
+            };
+            readonly props: readonly [{
+                readonly name: "as";
+                readonly type: "article | div | section";
+                readonly default: "div";
+            }, {
+                readonly name: "variant";
+                readonly type: "accent | bare | default | glass";
+                readonly default: "default";
+            }, {
+                readonly name: "label";
+                readonly type: "string";
+            }, {
+                readonly name: "value";
+                readonly type: "string";
+            }];
+            readonly composition: readonly ["Prefer StatLabel, StatValue, StatDescription, StatIcon, and StatTrend for structured content."];
+            readonly stylingParts: readonly ["stat", "stat-label", "stat-value", "stat-description", "stat-icon", "stat-trend"];
+            readonly tokens: readonly ["surface", "line", "ink", "ink-muted", "brand-soft"];
+        };
         readonly files: readonly ["packages/astro/components/Stat.astro", "packages/react/src/components.tsx"];
     }, {
         readonly name: "StatDescription";

package/dist/registry-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-data.d.ts","sourceRoot":"","sources":["../src/registry-data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAm5EQ,CAAA"}
+{"version":3,"file":"registry-data.d.ts","sourceRoot":"","sources":["../src/registry-data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2iFQ,CAAA"}

package/dist/registry-data.js

@@ -730,6 +730,66 @@ export const lumenRegistry = {
             type: 'component',
             description: 'Copies arbitrary text or the content of another element with accessible feedback.',
             category: 'Actions',
+            contract: {
+                imports: {
+                    astro: 'import { CopyButton } from \'@santi020k/lumen-astro\''
+                },
+                usage: {
+                    astro: '<CopyButton value="https://example.com" variant="default">Copy link<span slot="copied">Copied!</span><span slot="error">Try again</span></CopyButton>'
+                },
+                props: [
+                    {
+                        name: 'value',
+                        type: 'string'
+                    },
+                    {
+                        name: 'target',
+                        type: 'string'
+                    },
+                    {
+                        name: 'variant',
+                        type: 'Button variant',
+                        default: 'outline'
+                    },
+                    {
+                        name: 'size',
+                        type: 'default | sm | lg | icon',
+                        default: 'default'
+                    },
+                    {
+                        name: 'resetAfter',
+                        type: 'number',
+                        default: '2000'
+                    },
+                    {
+                        name: 'toast',
+                        type: 'boolean',
+                        default: 'false'
+                    }
+                ],
+                events: [
+                    'ui:copy-success',
+                    'ui:copy-error'
+                ],
+                slots: [
+                    'default (idle)',
+                    'copied',
+                    'error'
+                ],
+                runtime: 'Mount the default export from @santi020k/lumen-astro/runtime once above the component.',
+                stylingParts: [
+                    'copy-button',
+                    'copy-idle',
+                    'copy-copied',
+                    'copy-error'
+                ],
+                tokens: [
+                    'brand-solid',
+                    'line',
+                    'surface-muted',
+                    'ink'
+                ]
+            },
             files: [
                 'packages/astro/components/CopyButton.astro',
                 'packages/astro/styles/lumen.css',
@@ -1988,6 +2048,50 @@ export const lumenRegistry = {
             type: 'component',
             category: 'Layout',
             description: 'Reveals a group of direct children with tokenized, reduced-motion-aware staggering.',
+            contract: {
+                imports: {
+                    astro: 'import { RevealGroup } from \'@santi020k/lumen-astro\''
+                },
+                usage: {
+                    astro: '<RevealGroup as="ul"><li>First</li><li>Second</li></RevealGroup>'
+                },
+                props: [
+                    {
+                        name: 'as',
+                        type: 'div | ul | ol | section',
+                        default: 'div'
+                    },
+                    {
+                        name: 'animation',
+                        type: 'fade | slide-up | scale',
+                        default: 'slide-up'
+                    },
+                    {
+                        name: 'duration',
+                        type: 'fast | standard | slow',
+                        default: 'slow'
+                    },
+                    {
+                        name: 'stagger',
+                        type: 'number',
+                        default: '80'
+                    },
+                    {
+                        name: 'once',
+                        type: 'boolean',
+                        default: 'true'
+                    }
+                ],
+                composition: [
+                    'Children remain direct children of the selected semantic root.'
+                ],
+                runtime: 'Mount the Astro runtime once; content remains readable before JavaScript and with reduced motion.',
+                tokens: [
+                    'motion-duration-fast',
+                    'motion-duration-standard',
+                    'motion-duration-slow'
+                ]
+            },
             files: [
                 'packages/astro/components/RevealGroup.astro',
                 'packages/astro/runtime/UIPrimitives.astro',
@@ -2020,6 +2124,54 @@ export const lumenRegistry = {
             type: 'component',
             category: 'Data display',
             description: 'A stat component.',
+            contract: {
+                imports: {
+                    astro: 'import { Stat, StatLabel, StatValue } from \'@santi020k/lumen-astro\'',
+                    react: 'import { Stat, StatLabel, StatValue } from \'@santi020k/lumen-react\''
+                },
+                usage: {
+                    astro: '<Stat as="article"><StatLabel>Revenue</StatLabel><StatValue>$12,400</StatValue></Stat>',
+                    react: '<Stat as="article"><StatLabel>Revenue</StatLabel><StatValue>$12,400</StatValue></Stat>'
+                },
+                props: [
+                    {
+                        name: 'as',
+                        type: 'article | div | section',
+                        default: 'div'
+                    },
+                    {
+                        name: 'variant',
+                        type: 'accent | bare | default | glass',
+                        default: 'default'
+                    },
+                    {
+                        name: 'label',
+                        type: 'string'
+                    },
+                    {
+                        name: 'value',
+                        type: 'string'
+                    }
+                ],
+                composition: [
+                    'Prefer StatLabel, StatValue, StatDescription, StatIcon, and StatTrend for structured content.'
+                ],
+                stylingParts: [
+                    'stat',
+                    'stat-label',
+                    'stat-value',
+                    'stat-description',
+                    'stat-icon',
+                    'stat-trend'
+                ],
+                tokens: [
+                    'surface',
+                    'line',
+                    'ink',
+                    'ink-muted',
+                    'brand-soft'
+                ]
+            },
             files: [
                 'packages/astro/components/Stat.astro',
                 'packages/react/src/components.tsx'

package/dist/registry-types.d.ts

@@ -2,8 +2,25 @@ export interface LumenRegistryFile {
     path: string;
     source: string;
 }
+export interface LumenRegistryComponentContract {
+    composition?: readonly string[];
+    events?: readonly string[];
+    imports: Readonly<Record<string, string>>;
+    props?: readonly {
+        default?: string;
+        name: string;
+        required?: boolean;
+        type: string;
+    }[];
+    runtime?: string;
+    slots?: readonly string[];
+    stylingParts?: readonly string[];
+    tokens?: readonly string[];
+    usage: Readonly<Record<string, string>>;
+}
 export interface LumenRegistryComponent {
     category: string;
+    contract?: LumenRegistryComponentContract;
     dependencies?: readonly string[];
     description: string;
     files: readonly (LumenRegistryFile | string)[];

package/dist/registry-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-types.d.ts","sourceRoot":"","sources":["../src/registry-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,EAAE,CAAA;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,EAAE,CAAA;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,eAAe,GAAG,eAAe,GAAG,QAAQ,CAAA;CACnD;AAED,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,iBAAiB,CAAA;AAE3E,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"registry-types.d.ts","sourceRoot":"","sources":["../src/registry-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,8BAA8B;IAC7C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,KAAK,CAAC,EAAE,SAAS;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,IAAI,EAAE,MAAM,CAAA;KACb,EAAE,CAAA;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,8BAA8B,CAAA;IACzC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,EAAE,CAAA;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,EAAE,CAAA;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,eAAe,GAAG,eAAe,GAAG,QAAQ,CAAA;CACnD;AAED,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,iBAAiB,CAAA;AAE3E,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/registry.d.ts

@@ -1,7 +1,7 @@
 import { lumenRegistry } from './registry-data.js';
-import type { LumenRegistry, LumenRegistryComponent, LumenRegistryEntry, LumenRegistryFile, LumenRegistryItem, LumenRegistryLoadOptions } from './registry-types.js';
+import type { LumenRegistry, LumenRegistryComponent, LumenRegistryComponentContract, LumenRegistryEntry, LumenRegistryFile, LumenRegistryItem, LumenRegistryLoadOptions } from './registry-types.js';
 export { lumenRegistry };
-export type { LumenRegistry, LumenRegistryComponent, LumenRegistryEntry, LumenRegistryFile, LumenRegistryItem, LumenRegistryLoadOptions };
+export type { LumenRegistry, LumenRegistryComponent, LumenRegistryComponentContract, LumenRegistryEntry, LumenRegistryFile, LumenRegistryItem, LumenRegistryLoadOptions };
 export declare const getLumenRegistryEntries: (registry?: LumenRegistry) => LumenRegistryEntry[];
 export declare const getLumenRegistryItem: (name: string, registry?: LumenRegistry) => LumenRegistryEntry | undefined;
 export declare const loadLumenRegistry: (source: string | URL, options?: LumenRegistryLoadOptions) => Promise<LumenRegistry>;

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACzB,CAAA;AAwBD,eAAO,MAAM,uBAAuB,GAAI,WAAU,aAA6B,KAAG,kBAAkB,EAGnG,CAAA;AAED,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,WAAU,aAA6B,KACtC,kBAAkB,GAAG,SAQvB,CAAA;AA6JD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,GAAG,GAAG,EACpB,UAAS,wBAA6B,KACrC,OAAO,CAAC,aAAa,CAsBvB,CAAA;AAED,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACtB,8BAA8B,EAC9B,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,8BAA8B,EAC9B,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACzB,CAAA;AAwBD,eAAO,MAAM,uBAAuB,GAAI,WAAU,aAA6B,KAAG,kBAAkB,EAGnG,CAAA;AAED,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,WAAU,aAA6B,KACtC,kBAAkB,GAAG,SAQvB,CAAA;AA6JD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,GAAG,GAAG,EACpB,UAAS,wBAA6B,KACrC,OAAO,CAAC,aAAa,CAsBvB,CAAA;AAED,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA"}

package/native-components.json

@@ -70,8 +70,8 @@
     {
       "id": "icon-button",
       "tier": "universal",
-      "contract": "Shared intent and native touch target",
-      "accessibility": "Requires an action label",
+      "contract": "Shared intent and native touch target; SwiftUI supports semantic roles and loading",
+      "accessibility": "Requires an action label; SwiftUI loading preserves the name and disables repeat activation",
       "symbols": {
         "reactNative": "LumenIconButton",
         "swiftUI": "LumenIconButton",
@@ -92,7 +92,7 @@
     {
       "id": "button",
       "tier": "universal",
-      "contract": "Intent, size, loading, and disabled states",
+      "contract": "Intent, size, loading, and disabled states; SwiftUI supports semantic button roles",
       "accessibility": "Exposes native button and state semantics",
       "symbols": {
         "reactNative": "LumenButton",
@@ -126,7 +126,7 @@
       "id": "field-group",
       "tier": "shared",
       "contract": "Label, description, required state, control content, and validation message",
-      "accessibility": "Keeps child control semantics independent while presenting readable field context",
+      "accessibility": "Keeps child control semantics independent, presents readable field context, and announces validation updates",
       "symbols": {
         "reactNative": "LumenFieldGroup",
         "swiftUI": "LumenFieldGroup",
@@ -136,8 +136,8 @@
     {
       "id": "toggle",
       "tier": "shared",
-      "contract": "Native switch behavior with visible label and disabled state",
-      "accessibility": "Exposes native switch state and a readable label",
+      "contract": "Full-row native switch behavior with visible label and disabled state",
+      "accessibility": "Exposes one labeled switch whose full row toggles the controlled state and preserves supporting guidance",
       "symbols": {
         "reactNative": "LumenToggle",
         "swiftUI": "LumenToggle",
@@ -147,7 +147,7 @@
     {
       "id": "settings-row",
       "tier": "shared",
-      "contract": "Title, supporting text, optional graphic, and trailing control",
+      "contract": "Title, supporting text, optional graphic, trailing control, and 56-unit minimum row height",
       "accessibility": "Contains the native control without merging its interaction",
       "symbols": {
         "reactNative": "LumenSettingsRow",
@@ -158,7 +158,7 @@
     {
       "id": "search-field",
       "tier": "shared",
-      "contract": "Native search input with semantic surface and clear action",
+      "contract": "Native search input with semantic surface and a density-aware clear action",
       "accessibility": "Labels the input and clear action while preserving native editing",
       "symbols": {
         "reactNative": "LumenSearchField",
@@ -202,7 +202,7 @@
     {
       "id": "checkbox",
       "tier": "shared",
-      "contract": "Controlled Boolean selection with visible label and optional supporting text",
+      "contract": "Controlled Boolean selection with visible label, optional supporting text, and density-aware row target",
       "accessibility": "Exposes native checkbox state, disabled state, and a readable label",
       "symbols": {
         "reactNative": "LumenCheckbox",
@@ -213,7 +213,7 @@
     {
       "id": "radio-group",
       "tier": "shared",
-      "contract": "Single selection from labeled options with optional supporting text",
+      "contract": "Single selection from labeled options with optional supporting text and density-aware row targets",
       "accessibility": "Exposes a named native radio group and selected or disabled option states",
       "symbols": {
         "reactNative": "LumenRadioGroup",
@@ -246,7 +246,7 @@
     {
       "id": "chip",
       "tier": "shared",
-      "contract": "Compact display, selection, and removal with semantic selected and disabled states",
+      "contract": "Compact display, selection, and removal with semantic states and a 24-unit minimum remove target",
       "accessibility": "Separates selection and removal actions while exposing selected and disabled state",
       "symbols": {
         "reactNative": "LumenChip",
@@ -290,7 +290,7 @@
     {
       "id": "spinner",
       "tier": "universal",
-      "contract": "Brand-colored indeterminate activity",
+      "contract": "Brand-default indeterminate activity with an optional semantic tint",
       "accessibility": "Exposes a loading label",
       "symbols": {
         "reactNative": "LumenSpinner",
@@ -324,7 +324,7 @@
       "id": "toast",
       "tier": "shared",
       "contract": "App-controlled transient feedback with semantic tone, optional action, and dismissal",
-      "accessibility": "Announces concise status while preserving independent action and dismissal controls",
+      "accessibility": "Uses native live feedback semantics while preserving independently labeled, full-target action and dismissal controls",
       "symbols": {
         "reactNative": "LumenToast",
         "swiftUI": "LumenToast",
@@ -544,7 +544,7 @@
       "id": "banner",
       "tier": "shared",
       "contract": "Semantic notice with optional actions and dismissal",
-      "accessibility": "Does not announce automatically and labels dismissal",
+      "accessibility": "Does not announce automatically and exposes a labeled, full-target dismissal control",
       "symbols": {
         "reactNative": "LumenBanner",
         "swiftUI": "LumenBanner",
@@ -576,8 +576,8 @@
     {
       "id": "status-bar",
       "tier": "shared",
-      "contract": "Compact semantic status with optional trailing content",
-      "accessibility": "Status meaning remains present in text, not color alone",
+      "contract": "Compact semantic status that wraps beside fixed optional trailing content",
+      "accessibility": "Status meaning remains present in text before independently operable trailing content",
       "symbols": {
         "reactNative": "LumenStatusBar",
         "swiftUI": "LumenStatusBar",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen",
-  "version": "1.8.0",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -45,17 +45,17 @@
     "lumen": "./bin/lumen.mjs"
   },
   "dependencies": {
-    "semver": "^7.8.0",
-    "@santi020k/lumen-core": "^1.8.0"
+    "semver": "^7.8.5",
+    "@santi020k/lumen-core": "^2.1.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "@types/react": "^19.2.18",
     "@types/semver": "^7.8.0",
     "@vitest/coverage-v8": "^4.1.11",
     "react": "^19.2.8",
-    "typescript": "^6.0.3",
     "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.11"
   },
   "engines": {

package/release-manifest.json

@@ -6,7 +6,7 @@
         "com.santi020k:lumen-compose",
         "com.santi020k:lumen-compose-wear"
       ],
-      "version": "0.7.0"
+      "version": "2.1.0"
     },
     "npm": {
       "packages": {
@@ -14,41 +14,41 @@
           "peerDependencies": {
             "astro": ">=5"
           },
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-core": {
           "peerDependencies": {},
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-elements": {
           "peerDependencies": {},
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-icons-brand": {
           "peerDependencies": {},
-          "version": "1.0.3"
+          "version": "2.0.0"
         },
         "@santi020k/lumen": {
           "peerDependencies": {},
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-mcp": {
           "peerDependencies": {},
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-react": {
           "peerDependencies": {
             "react": ">=19"
           },
-          "version": "1.8.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-react-hook-form": {
           "peerDependencies": {
-            "@santi020k/lumen-react": "^1.7.0",
+            "@santi020k/lumen-react": "^2.0.0",
             "react": ">=19",
             "react-hook-form": ">=7.76.0 <8"
           },
-          "version": "1.0.2"
+          "version": "2.0.0"
         },
         "@santi020k/lumen-react-native": {
           "peerDependencies": {
@@ -57,32 +57,42 @@
             "react-native": ">=0.86.2",
             "react-native-svg": ">=12 <16"
           },
-          "version": "1.1.0"
+          "version": "2.1.0"
         },
         "@santi020k/lumen-tokens": {
           "peerDependencies": {},
-          "version": "0.2.0"
+          "version": "2.0.0"
         }
       }
     },
     "swift": {
       "package": "https://github.com/santi020k/lumen.git",
       "revision": null,
-      "tag": "v1.8.0"
+      "tag": "v2.1.0"
     },
-    "version": "1.8.0"
+    "version": "2.1.0"
   },
   "migration": {
-    "codemod": null,
+    "codemod": "lumen migrate v2 --dry-run",
     "css": {
       "astro": "@santi020k/lumen-astro/styles.css",
       "elements": "@santi020k/lumen-elements/styles.css",
       "react": "@santi020k/lumen-react/styles.css"
     },
     "deprecatedExports": [],
-    "removedExports": [],
+    "removedExports": [
+      "@santi020k/lumen-astro#Sonner",
+      "@santi020k/lumen-astro#UIPrimitives",
+      "@santi020k/lumen-react#Sonner",
+      "@santi020k/lumen-react#SonnerProps",
+      "@santi020k/lumen-react-native#LumenDateField",
+      "@santi020k/lumen-react-native#LumenDateFieldProps",
+      "@santi020k/lumen-react-native#LumenDateRangeField",
+      "@santi020k/lumen-react-native#LumenDateRangeFieldProps",
+      "@santi020k/lumen-react-native#LumenDateRangeValue"
+    ],
     "runtime": {
-      "astro": "Mount UIPrimitives once when an imported component declares the ui-primitives runtime.",
+      "astro": "Import UIPrimitives from @santi020k/lumen-astro/runtime and mount it once when an imported component declares the ui-primitives runtime.",
       "elements": "Call defineLumenElements once before rendering lumen-* elements.",
       "react": "Use the public React behavior hooks for behavior-heavy primitives."
     }

package/styles.css

@@ -1921,6 +1921,17 @@
   color: hsl(var(--danger));
 }
 
+.ui-copy-button [data-slot^="copy-"] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: inherit;
+}
+
+.ui-copy-button [hidden] {
+  display: none;
+}
+
 .ui-skeleton {
   min-height: 1rem;
   border-radius: var(--ui-radius-sm);