@santi020k/lumen 3.0.1 → 4.0.0

package/README.md

@@ -1,7 +1,59 @@
-# @santi020k/lumen
+<p align="center">
+  <a href="https://lumen.santi020k.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/santi020k/lumen/main/docs/assets/readme/package-dark.svg">
+      <img src="https://raw.githubusercontent.com/santi020k/lumen/main/docs/assets/readme/package-light.svg" alt="Lumen UI — Web. Native. Thoughtfully connected." width="1200" height="184">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">Lumen UI · CLI &amp; Registry</h1>
+
+<p align="center">Component discovery · Recipes · Integration diagnostics</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@santi020k/lumen"><img src="https://img.shields.io/npm/v/@santi020k/lumen?style=flat-square&color=0369a0" alt="npm version"></a>
+  <a href="https://github.com/santi020k/lumen/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-13967e?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://lumen.santi020k.com/docs">Documentation</a>
+  ·
+  <a href="https://www.npmjs.com/package/@santi020k/lumen">npm</a>
+  ·
+  <a href="https://github.com/santi020k/lumen/tree/main/packages/lumen">Source</a>
+  ·
+  <a href="https://github.com/santi020k/lumen/issues">Issues</a>
+</p>
+
+**Package:** `@santi020k/lumen`
+
+**On this page:** [Install](#install) · [Commands](#commands) · [Appearance presets](#appearance-presets) · [Resources](#resources)
+
+<details>
+<summary>Browse all sections</summary>
+
+- [Install](#install)
+- [Typography](#typography)
+- [Commands](#commands)
+- [Version migration previews](#version-migration-previews)
+- [Coordinated consumer rollout](#coordinated-consumer-rollout)
+- [Consumer upgrade and theme audits](#consumer-upgrade-and-theme-audits)
+- [Content flow](#content-flow)
+- [Appearance presets](#appearance-presets)
+- [Preview a v4 migration](#preview-a-v4-migration)
+- [Dashboard header recipes](#dashboard-header-recipes)
+- [Visual interactions and product blocks](#visual-interactions-and-product-blocks)
+- [Presence motion](#presence-motion)
+- [Studio media workspace](#studio-media-workspace)
+- [Resources](#resources)
+
+</details>
 
 Shared foundation and umbrella package for Lumen UI.
 
+## Install
+
 Install the framework package directly:
 
 - `@santi020k/lumen-astro`
@@ -28,6 +80,8 @@ The package declares the family but does not bundle or load font files. Applicat
 Montserrat once through their preferred delivery path, or override `--ui-font` when using another
 typeface.
 
+## Commands
+
 The umbrella package also exposes typed registry metadata and the `lumen` CLI:
 
 ```bash
@@ -47,11 +101,14 @@ lumen doctor --json
 lumen doctor-native --json
 lumen init --framework astro --tailwind
 lumen migrate v2 --dry-run
+lumen migrate v3 --dry-run
+lumen migrate v4 --dry-run
 ```
 
 Use `lumen add <component>` for a local Astro wrapper, `--target react` for a React wrapper, or
 `--target elements` for a custom-elements starter. Bundled recipes support the same Astro, React,
-and Elements targets.
+and Elements targets. With `--conflict error`, existing target files are checked before any recipe
+files are written; runtime write failures can still require cleanup.
 
 Complete product recipes are also bundled for `analytics-dashboard`, `saas-admin`,
 `commerce-dashboard`, `project-workspace`, `auth-onboarding`, `docs-shell`, `marketing-shell`,
@@ -61,6 +118,9 @@ External registry manifests are treated as untrusted input. Inline recipe files
 relative forward-slash paths and cannot traverse outside the selected `--cwd` or write through a
 symbolic-link path segment. `loadLumenRegistry` bounds local and remote manifests to 5 MiB by
 default; programmatic consumers can set `maxBytes` and `timeoutMs` for tighter deployment limits.
+Component wrapper names must be ASCII identifiers containing letters, digits, or underscores,
+starting with a letter or underscore, and cannot be reserved module keywords. Invalid names are
+rejected before generating or writing any wrapper; recipe names retain their existing format.
 
 Run `lumen doctor` to check adapter/style agreement, duplicate stylesheet entrypoints, Tailwind
 layer order, Astro runtime mounts, and fragile internal selector dependencies. In a workspace,
@@ -68,6 +128,8 @@ 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.
+Astro runtime mount detection follows default-import aliases, including `default as` imports.
+Type-only imports, front matter example strings, and HTML comments do not establish a runtime mount.
 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.
@@ -93,7 +155,32 @@ Run `lumen audit-tokens [path]` before incremental adoption when an existing sty
 declare names such as `--surface`, `--ink`, or `--line`. The audit reports complete CSS colors that
 are incompatible with Lumen's HSL-channel token format and exits non-zero when it finds conflicts.
 
-## Lumen v2 migration preview
+## Version migration previews
+
+Run `lumen migrate v3` for the v2-to-v3 review: no web source rewrites are needed. It reports
+native rebuild and exhaustive Swift icon-switch boundaries. Run `lumen migrate v4` for the
+v3-to-v4 source preview. Literal Stack/Grid gaps preserve v3 spacing (`md` → `group`, `lg` → `xl`,
+`xl` → `2xl`); dynamic values, spreads, product CSS, charts, dialogs and native contracts need review.
+Aliases are resolved from actual Lumen imports; unrelated components and source examples stay intact.
+
+Both commands preview by default and accept `--cwd`, `--json`, and `--apply`. Add `--dependencies`
+to include the existing coordinated pnpm rollout: v3 targets `3.0.1`, v4 targets `4.0.0`. Dependency
+apply retains rollout's exact package-manager and dirty-worktree guards; `--allow-dirty` is explicit.
+Installs run before source rewrites; a failed dependency command stops source apply. Run the
+consumer's completion gate after both phases. Source-only migration works without a package manifest
+or package-manager requirement. Native Swift/Maven pins remain application-owned.
+
+V4 apply records output fingerprints in `.lumen/migrations-v4.json`. Commit that ledger with the
+source changes: repeated applies skip migrated files, and later edits to them require manual review.
+The pure `migrateLumenVersionSource` API assumes v3 input and does not maintain that filesystem ledger.
+Markup migrations preserve literal slash-star text; script comments and regex literals remain
+excluded from rewrites. The umbrella package includes TypeScript as a runtime dependency so
+the migration scanner can distinguish regex literals from division using compiler grammar.
+Files that exceed the parser nesting limit remain unchanged and receive a manual-review finding.
+Dependency inventory recognizes root and nested manifests using platform-native paths.
+Review the actual application at mobile and desktop widths after applying a migration.
+
+### Lumen v2 migration
 
 Run `lumen migrate v2 [--cwd <path>]` to preview the candidate v2 source migrations. Previewing is
 the safe default; `--dry-run` makes that intent explicit, and `--json` emits a machine-readable
@@ -144,3 +231,120 @@ new release through `minimumReleaseAgeExclude`, runs installs through Corepack f
 root, removes obsolete Lumen release-age exceptions, verifies the unified resolved version, and
 runs available framework checks, builds, and browser scripts. It refuses dirty repositories,
 missing exact pnpm declarations, and unsupported Node runtimes unless `--allow-dirty` is explicit.
+
+## Consumer upgrade and theme audits
+
+```bash
+lumen audit-consumer ../my-app --json
+lumen audit-theme ./semantic-theme-scopes.json --json
+lumen add validated-form --target react
+lumen add operational-records --target react
+```
+
+The consumer audit reports declared and resolved versions, patch configuration and `ui-*` CSS
+review signals without rewriting files. Selectors are advisory customization review signals.
+Version migration previews include the same audit when the consumer has a manifest.
+
+The theme file maps scope names to complete semantic-token objects, such as
+`{ "light": { "canvas": "0 0% 100%", "ink": "0 0% 0%", ... } }`. Supply every semantic color
+mapping with resolved opaque HSL channels. Missing or unresolved values and failing normal-text
+contrast produce findings and a failing theme-audit exit status. Inspect computed mappings with
+`inspectLumenTheme` from core for CSS variable resolution in actual light, dark and nested scopes.
+
+See [consumer workflows](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#executable-consumer-workflows) for
+the installable React form and operational-record recipes.
+
+## Content flow
+
+Stack and Grid own sibling spacing. Their gap accepts `related`, `group` (default) and `section`,
+or canonical `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` sizes. Card owns the inset and gap
+between its visible parts; use `density="compact"`, `"comfortable"` (default) or `"spacious"`.
+Elements uses the same names as attributes. Use a nested Stack for CardContent groups and Field
+for label/control/feedback. See [content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) and the
+[v4 migration guide](https://github.com/santi020k/lumen/blob/main/docs/migrating-to-lumen.md) for ownership and changed explicit gaps.
+
+### Reading and complete compositions
+
+Prose and Typography trim outer child margins and separate headings from preceding text.
+Container gutters grow from 16px to 32px with viewport width; override `--ui-container-gutter`
+when a product needs fixed gutters. Card allows interactive overflow; use AspectRatio to clip media.
+Install `content-flow-header`, `content-flow-settings`, `content-flow-list` or `content-flow-actions`
+with `lumen add <recipe> --target astro|react|elements`. MCP returns the same complete examples.
+Connect application actions and replace sample IDs before reuse. See
+[content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) for composition and migration guidance.
+
+React is an optional peer for the published React starter templates. Astro and Elements consumers
+do not need it; React consumers should follow the React adapter's existing installation contract.
+
+## Appearance presets
+
+Choose Default, Studio or Glass with `data-lumen-preset` on a scoped web container.
+Use the [appearance guide](https://github.com/santi020k/lumen/blob/main/docs/appearance-presets.md) for semantic overrides,
+ThemeBuilder controls and native fallbacks. The Studio preset uses PostLens as its visual reference.
+
+## Preview a v4 migration
+
+```bash
+pnpm exec lumen migrate v4 --dry-run --json
+pnpm exec lumen migrate v4 --apply
+```
+
+The default is a preview. Deterministic edits cover four known static MCP SDK v1 import paths in
+`.ts`, `.js`, and `.mjs` files. The report inventories resolved installed versions and lists v4
+UI/native review triggers. SDK dependency manifests, comments, examples, dynamic imports, JSX, Astro,
+and native SDK imports remain review tasks. Review triggers are not proof of a defect. The v2 migration
+command remains available separately for older consumers.
+
+The integrated `lumen migrate v4` command also retains the release's web spacing migrations and
+optional coordinated dependency workflow. SDK edits compose into that command's source transform,
+so its apply ledger fingerprints the final source and repeat runs do not rewrite spacing twice.
+SDK import edits remain limited to `.ts`, `.js`, and `.mjs`; this restriction does not disable the
+separate documented JSX/Astro spacing migration. The JSON report includes installed package
+versions and explicit SDK dependency-review findings.
+
+## Dashboard header recipes
+
+Install `page-header` and `section-header` with `lumen add <recipe> --target astro|react|elements`.
+These compositions provide page identity, optional breadcrumbs and metadata, translated action-group
+labels, and responsive action wrapping using the existing primitives. The application owns its
+routes and action handlers. See the [header recipe guide](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#page-and-section-headers).
+
+The `auth-onboarding` recipe includes visual email-code sign-in, code verification, and passkey
+recovery examples for Astro, React, and Elements. Controls stay disabled until the consumer connects
+its authentication service. See the [login and Auth integration reference](https://lumen.santi020k.com/templates/auth-onboarding#login-examples-title).
+
+## Visual interactions and product blocks
+
+See [visual interactions](https://github.com/santi020k/lumen/blob/main/docs/visual-interactions.md) for keyed motion, semantic effects,
+chart continuity, AI surfaces, optional SDK integrations, and the four installable product recipes.
+## Presence motion
+
+`animateLumenPresence` is available from the umbrella package or `@santi020k/lumen-core` for
+optional browser-based enter/exit effects. See the [core motion contract](https://github.com/santi020k/lumen/blob/main/packages/core/README.md#presence-motion)
+for presets, semantic timing, cancellation, reduced motion, and consumer-owned DOM/focus behavior.
+The optional motion stylesheet progressively enhances native disclosures with natural-height transitions;
+unsupported browsers keep native immediate toggles.
+
+Import `@santi020k/lumen/styles/motion.css` alongside the base stylesheet to opt into native
+disclosure height transitions and the CSS reduction scope. This small optional stylesheet works
+with Astro, React, and Elements and keeps those effects out of the default stylesheet. The presence
+helper's system and local reduced-motion checks work without this CSS import.
+
+## Studio media workspace
+
+Compose MediaViewport, MediaThumbnail, MediaFilmstrip and ImageComparison modes with the
+[Studio media workspace recipes](https://github.com/santi020k/lumen/blob/main/docs/studio-media-workspaces.md). Applications retain
+media loading, selection, adjustment algorithms, processing, export and persistence.
+
+## Resources
+
+| Guide | What you will find |
+| --- | --- |
+| [AI usage examples](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md) | Setup and composition contracts for coding agents. |
+| [Consumer adoption](https://github.com/santi020k/lumen/blob/main/docs/project-adoption.md) | Adoption boundaries and staged migration guidance. |
+| [MCP server](https://github.com/santi020k/lumen/blob/main/packages/mcp/README.md) | Catalog discovery, transport setup, and agent workflows. |
+| [Contributing](https://github.com/santi020k/lumen/blob/main/CONTRIBUTING.md) | Setup, checks, and contribution workflow. |
+| [Release history](https://github.com/santi020k/lumen/releases) | Published releases and version notes. |
+
+Part of [Lumen UI](https://lumen.santi020k.com), created by [Santiago Molina](https://santi020k.com).
+Licensed under [MIT](https://github.com/santi020k/lumen/blob/main/LICENSE); third-party artwork retains its own notices.

package/dist/cli.js

@@ -1,11 +1,14 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { auditLumenTheme } from '@santi020k/lumen-core';
 import { consumerRolloutSucceeded, formatConsumerRollout, resolveConsumerRolloutTargets, runConsumerRollout } from './consumer-rollout.js';
+import { formatLumenConsumerUpgradeAudit, inspectLumenConsumerUpgrade } from './consumer-upgrade-audit.js';
 import { createLumenSetup, formatLumenDiagnostics, inspectLumenIntegration } from './integration-diagnostics.js';
 import { formatNativeAdoptionAudit, inspectNativeAdoption } from './native-audit.js';
 import { addLumenRegistryItem, getLumenRegistryEntries, getLumenRegistryItem, loadLumenRegistry, lumenRegistry } from './registry.js';
 import { auditLumenTokenCss } from './token-audit.js';
 import { formatLumenV2Migration, migrateLumenV2 } from './v2-migration.js';
+import { formatLumenVersionMigration, migrateLumenVersion } from './version-migration.js';
 const args = process.argv.slice(2);
 const [command = 'help', name] = args;
 const dryRun = args.includes('--dry-run');
@@ -187,11 +190,14 @@ const help = [
     '  lumen add <name>       Install a recipe or component into the current project',
     '  lumen install          Print install commands',
     '  lumen audit-tokens     Report incompatible semantic color custom properties',
+    '  lumen audit-theme <json>  Check named semantic palettes and text contrast',
+    '  lumen audit-consumer   Review versions, local patches and Lumen CSS overrides',
     '  lumen doctor           Inspect styles, adapters, runtime mounts, and selector usage',
     '  lumen doctor-native    Inspect native versions, package pins, and theme placement',
     '  lumen init             Print canonical framework setup without changing files',
     '  lumen rollout [version] [repositories...]  Inventory or upgrade pnpm consumers',
-    '  lumen migrate v2       Preview or apply the candidate Lumen v2 source migrations',
+    '  lumen migrate v2|v3|v4 Preview source migrations and manual review findings',
+    '  --dependencies        Include coordinated pnpm upgrades for v3/v4 migrations',
     '',
     'Options:',
     '  --cwd <path>           Target directory for lumen add',
@@ -206,7 +212,7 @@ const help = [
     '  --tailwind             Include the verified Tailwind cascade setup in lumen init',
     '  --json                 Print lumen doctor output as JSON',
     '  --manifest <path>      Use a specific cross-platform release manifest',
-    '  --apply                Apply a rollout or v2 migration (migrations default to dry-run)',
+    '  --apply                Apply a rollout or supported migration (migrations default to dry-run)',
     '  --allow-dirty          Allow rollout after recording an uncommitted baseline',
     '  --exclude <path>       Exclude a repository (repeatable)',
     '  --no-verify            Skip downstream check, typecheck, build, and browser scripts',
@@ -220,6 +226,33 @@ const run = async () => {
         await loadLumenRegistry(registrySource, registryToken ? { token: registryToken } : {}) :
         lumenRegistry;
     switch (command) {
+        case 'audit-consumer': {
+            const report = await inspectLumenConsumerUpgrade(cwd ?? name ?? process.cwd());
+            output = json ? JSON.stringify(report, undefined, 2) : formatLumenConsumerUpgradeAudit(report);
+            break;
+        }
+        case 'audit-theme': {
+            if (!name)
+                throw new Error('Provide a JSON file mapping scope names to resolved semantic palettes.');
+            const value = JSON.parse(await readFile(resolve(cwd ?? process.cwd(), name), 'utf8'));
+            if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length === 0)
+                throw new Error('Theme audit requires a nonempty scope-to-palette object.');
+            const palettes = Object.entries(value);
+            const scopes = palettes.map(([scope, palette]) => {
+                if (!palette || typeof palette !== 'object' || Array.isArray(palette))
+                    throw new Error(`Invalid palette for ${scope}.`);
+                const entries = Object.entries(palette);
+                if (entries.some(([, channel]) => typeof channel !== 'string')) {
+                    throw new Error(`Palette ${scope} must contain string HSL channels.`);
+                }
+                const tokens = Object.fromEntries(entries.map(([token, channel]) => [token, String(channel)]));
+                return { scope, ...auditLumenTheme(tokens) };
+            });
+            output = json ? JSON.stringify(scopes, undefined, 2) : scopes.map(scope => `${scope.scope}: ${scope.healthy ? 'passed' : 'needs review'}\n${scope.findings.map(item => `  [${item.rule}] ${item.message}`).join('\n')}`).join('\n');
+            if (scopes.some(scope => !scope.healthy))
+                process.exitCode = 1;
+            break;
+        }
         case 'audit-tokens': {
             output = await formatTokenAudit(name ?? cwd ?? process.cwd());
             break;
@@ -256,10 +289,21 @@ const run = async () => {
             break;
         }
         case 'migrate': {
-            if (name !== 'v2')
-                throw new Error('Missing or invalid migration. Use lumen migrate v2.');
+            if (name !== 'v2' && name !== 'v3' && name !== 'v4')
+                throw new Error('Missing or invalid migration. Use lumen migrate v2, v3 or v4.');
             if (applyRollout && dryRun)
-                throw new Error('Choose either --dry-run or --apply for lumen migrate v2.');
+                throw new Error('Choose either --dry-run or --apply for lumen migrate.');
+            if (name !== 'v2') {
+                const report = await migrateLumenVersion({
+                    allowDirty, apply: applyRollout, ...(cwd ? { cwd } : {}), dependencies: args.includes('--dependencies'), version: name
+                });
+                output = json ? JSON.stringify(report, undefined, 2) : formatLumenVersionMigration(report);
+                if (report.dependencies && !consumerRolloutSucceeded(report.dependencies))
+                    process.exitCode = 1;
+                break;
+            }
+            if (args.includes('--dependencies'))
+                throw new Error('For v2 dependencies, use lumen rollout separately.');
             const report = await migrateLumenV2({
                 apply: applyRollout,
                 cwd: cwd ?? process.cwd()

package/dist/consumer-upgrade-audit.d.ts

@@ -0,0 +1,10 @@
+import type { LumenDiagnosticFinding } from './integration-diagnostics.js';
+export interface LumenConsumerUpgradeAudit {
+    findings: LumenDiagnosticFinding[];
+    repository: string;
+    targetVersion: string;
+}
+/** Advisory inventory only: patches and product CSS are never deleted or rewritten. */
+export declare const inspectLumenConsumerUpgrade: (repository: string, targetVersion?: string) => Promise<LumenConsumerUpgradeAudit>;
+export declare const formatLumenConsumerUpgradeAudit: (report: LumenConsumerUpgradeAudit) => string;
+//# sourceMappingURL=consumer-upgrade-audit.d.ts.map

package/dist/consumer-upgrade-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-upgrade-audit.d.ts","sourceRoot":"","sources":["../src/consumer-upgrade-audit.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAG1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,sBAAsB,EAAE,CAAA;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;CACtB;AA0CD,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,GACtC,YAAY,MAAM,EAAE,sBAAuB,KAC1C,OAAO,CAAC,yBAAyB,CAWnC,CAAA;AAED,eAAO,MAAM,+BAA+B,GAAI,QAAQ,yBAAyB,KAAG,MAIxE,CAAA"}

package/dist/consumer-upgrade-audit.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { satisfies, valid } from 'semver';
+import { inspectLumenConsumer } from './consumer-rollout.js';
+import { discoverSourceFiles } from './v2-migration.js';
+const review = (file, rule, message, remediation) => ({ file, rule, message, remediation, severity: 'advisory' });
+const versionFindings = (inventory, targetVersion) => {
+    const findings = [];
+    for (const reference of inventory.references) {
+        if (reference.version.startsWith('workspace:') || reference.version.startsWith('catalog:'))
+            continue;
+        if (!satisfies(targetVersion, reference.version)) {
+            findings.push(review(reference.file, 'consumer-package-version', `${reference.packageName} ${reference.version} does not include target ${targetVersion}.`, 'Preview lumen migrate v4 --dependencies, align the adapter and companion packages, then validate the consumer.'));
+        }
+    }
+    for (const [name, versions] of Object.entries(inventory.resolvedVersions)) {
+        if (versions.some(version => version !== targetVersion)) {
+            findings.push(review('pnpm-lock.yaml', 'consumer-resolved-version', `${name} resolves ${versions.join(', ')}; target is ${targetVersion}.`, 'Update through the repository package manager and inspect the resulting lockfile; a compatible manifest range does not prove installation.'));
+        }
+    }
+    return findings;
+};
+const sourceFindings = (file, source) => {
+    const findings = [];
+    if (file.endsWith('.patch') && (file.includes('lumen') || source.includes('@santi020k/lumen'))) {
+        findings.push(review(file, 'consumer-package-patch', 'A local Lumen package patch needs migration review.', 'Compare each patch with the target implementation. Chart padding/axis fixes may already be upstream; remove only after equivalent behavior and mobile/desktop visuals pass.'));
+    }
+    if ((file.endsWith('.yaml') || file.endsWith('.json')) && source.includes('patchedDependencies') && source.includes('@santi020k/lumen')) {
+        findings.push(review(file, 'consumer-patch-configuration', 'Lumen dependencies and package patch configuration coexist in this file.', 'Inspect the exact patched dependency keys and patch paths before upgrading; this signal alone does not establish that every Lumen dependency is patched.'));
+    }
+    if (file.endsWith('.css') && source.includes('.ui-')) {
+        findings.push(review(file, 'consumer-css-review', 'CSS references Lumen component classes.', 'Check selectors against the public styling contract. Keep supported customization; review chart axes, hidden states, button children, record layouts and overlay offsets against target behavior.'));
+    }
+    return findings;
+};
+/** Advisory inventory only: patches and product CSS are never deleted or rewritten. */
+export const inspectLumenConsumerUpgrade = async (repository, targetVersion = '4.0.0') => {
+    if (!valid(targetVersion))
+        throw new Error('Consumer audit requires an exact semantic target version.');
+    const root = resolve(repository);
+    const inventory = await inspectLumenConsumer(root);
+    const findings = versionFindings(inventory, targetVersion);
+    const files = await discoverSourceFiles(root, new Set(['.css', '.patch', '.yaml', '.json']));
+    for (const path of files)
+        findings.push(...sourceFindings(relative(root, path), await readFile(path, 'utf8')));
+    return { findings, repository: root, targetVersion };
+};
+export const formatLumenConsumerUpgradeAudit = (report) => [
+    `Consumer upgrade review for ${report.targetVersion}: ${report.repository}`,
+    ...report.findings.map(item => `${item.file} [${item.rule}] ${item.message}\n  ${item.remediation}`),
+    report.findings.length ? 'These are review signals, not permission to remove consumer code.' : 'No package-version, patch or CSS review signals found.'
+].join('\n');

package/dist/index.d.ts

@@ -7,7 +7,10 @@ export declare const lumen: {
     readonly packageName: "@santi020k/lumen";
     readonly scope: "@santi020k";
 };
+export { formatLumenConsumerUpgradeAudit, inspectLumenConsumerUpgrade, type LumenConsumerUpgradeAudit } from './consumer-upgrade-audit.js';
 export { createLumenSetup, formatLumenDiagnostics, inspectLumenIntegration, type LumenDiagnosticFinding, type LumenDiagnosticReport, type LumenDiagnosticSeverity } from './integration-diagnostics.js';
 export { auditLumenTokenCss, type LumenTokenAuditFinding } from './token-audit.js';
 export { formatLumenV2Migration, type LumenV2MigrationFinding, type LumenV2MigrationKind, type LumenV2MigrationOptions, type LumenV2MigrationReport, type LumenV2SourceMigration, migrateLumenV2, migrateLumenV2Source } from './v2-migration.js';
+export { formatLumenVersionMigration, type LumenMigrationVersion, type LumenVersionMigrationFinding, type LumenVersionMigrationOptions, type LumenVersionMigrationReport, type LumenVersionSourceMigration, migrateLumenVersion, migrateLumenVersionSource } from './version-migration.js';
+export { animateLumenPresence, type LumenMotionDuration, type LumenMotionPreset, type LumenMotionResult, type LumenPresenceOptions } from '@santi020k/lumen-core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -7,6 +7,9 @@ export const lumen = {
     packageName: '@santi020k/lumen',
     scope: '@santi020k'
 };
+export { formatLumenConsumerUpgradeAudit, inspectLumenConsumerUpgrade } from './consumer-upgrade-audit.js';
 export { createLumenSetup, formatLumenDiagnostics, inspectLumenIntegration } from './integration-diagnostics.js';
 export { auditLumenTokenCss } from './token-audit.js';
 export { formatLumenV2Migration, migrateLumenV2, migrateLumenV2Source } from './v2-migration.js';
+export { formatLumenVersionMigration, migrateLumenVersion, migrateLumenVersionSource } from './version-migration.js';
+export { animateLumenPresence } from '@santi020k/lumen-core';

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAA;AAQtB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAA;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAA;IAChD,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAA;AAE3D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,IAAI,EAAE,kBAAkB,CAAA;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AA8PD,eAAO,MAAM,oBAAoB,GAAU,MAAM,MAAM,EAAE,UAAS,eAAoB,KAAG,OAAO,CAAC,cAAc,CA6C9G,CAAA"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAA;AAStB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAA;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAA;IAChD,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAA;AAE3D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,IAAI,EAAE,kBAAkB,CAAA;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAkRD,eAAO,MAAM,oBAAoB,GAAU,MAAM,MAAM,EAAE,UAAS,eAAoB,KAAG,OAAO,CAAC,cAAc,CAgD9G,CAAA"}

package/dist/installer.js

@@ -2,8 +2,10 @@ import { access, lstat, mkdir, readdir, readFile, writeFile } from 'node:fs/prom
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getLumenRegistryItem } from './registry.js';
+import { isSafeRegistryComponentName } from './registry-component-name.js';
 import { assertSafeRegistryFilePath } from './registry-path.js';
 const templatesRoot = fileURLToPath(new URL('../templates/', import.meta.url));
+const visualProductBlocks = new Set(['interactive-pricing', 'feature-preview', 'guided-onboarding', 'command-center']);
 const productTemplateRecipes = new Set([
     'analytics-dashboard',
     'auth-onboarding',
@@ -32,6 +34,7 @@ const loadTemplateDirectory = async (templateDir) => {
 const loadRecipeTemplateFiles = async (itemName, target) => {
     const templateDirectories = [
         ...(productTemplateRecipes.has(itemName) ? [join(templatesRoot, 'shared', 'common')] : []),
+        ...(target !== 'react' && visualProductBlocks.has(itemName) ? [join(templatesRoot, 'shared', 'visual-blocks')] : []),
         join(templatesRoot, 'shared', itemName),
         join(templatesRoot, target, itemName)
     ];
@@ -94,6 +97,9 @@ declare global {
     };
 };
 const createComponentFile = (name, target) => {
+    if (!isSafeRegistryComponentName(name)) {
+        throw new Error('Registry component names must be safe identifiers without reserved keywords.');
+    }
     if (target === 'react')
         return createReactComponentFile(name);
     if (target === 'elements')
@@ -178,6 +184,15 @@ const validateInstallFiles = async (files, cwd) => {
         await assertNoSymlinkSegments(cwd, file.path);
     }
 };
+const validateInstallConflicts = async (files, cwd, conflict) => {
+    if (conflict !== 'error')
+        return;
+    for (const file of files) {
+        if (await fileExists(join(cwd, file.path))) {
+            throw new Error(`Refusing to overwrite existing file: ${file.path}`);
+        }
+    }
+};
 const installRegistryFile = async (file, cwd, options, conflict) => {
     const target = join(cwd, file.path);
     const exists = await fileExists(target);
@@ -203,6 +218,7 @@ export const addLumenRegistryItem = async (name, options = {}) => {
     await validateInstallFiles(files, cwd);
     const added = [];
     const conflict = getConflictMode(options);
+    await validateInstallConflicts(files, cwd, conflict);
     const merged = [];
     const skipped = [];
     for (const file of files) {

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"integration-diagnostics.d.ts","sourceRoot":"","sources":["../src/integration-diagnostics.ts"],"names":[],"mappings":"AAgBA,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;AA6/BD,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"}