@sequenceholdings/artifact-studio 0.2.2 → 0.2.3

package/VERSION-PIN.md

@@ -43,12 +43,15 @@ source (and older rows with null peer fields are rebuilt once to populate them).
 `seq-studio artifact plan` reports the same decision, so its `action:` line
 never claims `no-op` for a deploy that would actually rebuild.
 
-## V2 CSS sheets (sandbox previews)
-
-`seq-studio artifact build` idempotently injects `tokens.v2.css` + `theme.v2.css`
-when the artifact CSS entry lacks them (iframes do not inherit Atlas CSSOM; the
-host only stamps `data-tokens` / brand vars). Keep listing `tokens.css` for the
-ungated standalone/`vite dev` fallback. **Do not** import `tokens.v2.tenants.css`.
-
-**DES-227 cutover:** remove the build inject; make `tokens.css` the v2 default;
-optionally sweep hand-written `@import …/tokens.v2.css` / `theme.v2.css` lines.
+## CSS entry points (sandbox previews)
+
+`tokens.css` is the canonical stylesheet and includes semantic roles plus the
+Tailwind utility bridge. The legacy `tokens.v2.css` and `theme.v2.css` paths are
+temporary forwarding aliases; the compiler normalizes their source imports to one
+canonical layer and reports a migration warning. An explicit
+`seq-studio artifact dev --link <atlas-ui-package-dir>` preview additionally
+reports retired numbered black/white opacity utilities and uncertain dynamic
+class construction; ordinary released-CLI builds stay compatible until global
+cutover. The runtime forwards brand variables independently of `data-tokens`.
+Import `tokens.css` for standalone/`vite dev` compatibility. **Do not** import
+`tokens.v2.tenants.css`.

package/dist/active-deploy-policy.d.ts

@@ -1,8 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from a **clean
- * `main` checkout with a resolved commit** — whether the source is a platform
- * git-service repo (`--repo`) or a monorepo / local checkout. Preview deploys
- * may use feature branches, dirty trees, or other refs.
+ * Official (active-channel) Artifact Studio deploys must come from `main` with
+ * a resolved commit and a clean artifact source directory — whether the source
+ * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
  * It does **not** independently verify that `gitCommit` equals the remote

package/dist/active-deploy-policy.js

@@ -1,8 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from a **clean
- * `main` checkout with a resolved commit** — whether the source is a platform
- * git-service repo (`--repo`) or a monorepo / local checkout. Preview deploys
- * may use feature branches, dirty trees, or other refs.
+ * Official (active-channel) Artifact Studio deploys must come from `main` with
+ * a resolved commit and a clean artifact source directory — whether the source
+ * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
  * It does **not** independently verify that `gitCommit` equals the remote
@@ -41,9 +41,12 @@ export function isActiveDeployDefaultBranch(branch) {
  * Preview callers must not invoke this.
  */
 export function assertActiveDeployProvenance(provenance) {
-    // Require an explicit clean recording — omitting gitDirty must not pass.
+    // Require an explicit clean source-directory recording — omitting gitDirty
+    // must not pass. The local source resolver scopes this value to the
+    // artifact directory, so unrelated changes elsewhere in a containing
+    // checkout do not block an official deploy.
     if (provenance.gitDirty !== false) {
-        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a clean git tree ' +
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a clean artifact source tree ' +
             '(`gitDirty: false`). Commit or stash your changes, or use ' +
             '`seq-studio artifact dev` / a preview deploy for dirty feature-branch work.');
     }

package/dist/atlas-ui-css-plugin.d.ts

@@ -1,15 +1,36 @@
 import type { Plugin } from 'vite';
+export interface AtlasUiResolvedTokenSelection {
+    specifier: '@sequenceholdings/atlas-ui/tokens.css';
+    injectedBy: string | null;
+}
 /**
- * Idempotent v2 token sheets for Artifact Studio builds. Sandbox iframes do not
- * inherit Atlas CSSOM; the host stamps `data-tokens` (floors to v2) but roles
- * only resolve if the bundle includes these sheets. Skip when the entry already
- * imports them. Remove this inject at DES-227 cutover when `tokens.css` *is* v2.
+ * Every supported source shape becomes one canonical import before Tailwind
+ * expands it. The aliases remain package-compatible, but are no longer allowed
+ * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
-export declare function cssAlreadyImportsSheet(code: string, sheetFileName: string): boolean;
-/** Absolute or package `@import` lines to prepend when the CSS entry lacks v2 sheets. */
-export declare function planAtlasUiV2CssImports(code: string, _atlasUiDir: string): string[];
-export declare function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, }: {
+export declare function normalizeAtlasUiTokenImports(code: string): {
+    code: string;
+    deprecatedImports: string[];
+};
+/**
+ * Evidence mirrors the CSS transform: aliases are normalized away, so the only
+ * selected sheet is the canonical token entry point.
+ */
+export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
+    cssModules: readonly {
+        id: string;
+        code: string;
+    }[];
+    atlasUiDir: string;
+    atlasUiDist: string;
+    formRendererDist: string | null;
+}): AtlasUiResolvedTokenSelection[];
+export declare function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
     atlasUiDir: string;
     atlasUiDist: string;
     formRendererDist: string | null;
+    onTransform?: (cssModule: {
+        id: string;
+        code: string;
+    }) => void;
 }): Plugin;

package/dist/atlas-ui-css-plugin.js

@@ -17,36 +17,67 @@ function resolveTwAnimateCssPath() {
     }
     return resolved;
 }
+const CANONICAL_TOKEN_IMPORT = '@import "@sequenceholdings/atlas-ui/tokens.css";';
+const ATLAS_UI_TOKEN_IMPORT = /@import\s+(?:url\(\s*)?(?:["'][^"']*?@sequenceholdings\/atlas-ui\/|[^"'()\s;]*@sequenceholdings\/atlas-ui\/)(tokens\.css|tokens\.v2\.css|theme\.v2\.css)(?:["'])?\s*\)?[^;\n]*;/gi;
+function atlasUiTokenImportSheets(code) {
+    return [...code.matchAll(ATLAS_UI_TOKEN_IMPORT)]
+        .map((match) => match[1]?.toLowerCase())
+        .filter((sheet) => sheet !== undefined);
+}
 /**
- * Idempotent v2 token sheets for Artifact Studio builds. Sandbox iframes do not
- * inherit Atlas CSSOM; the host stamps `data-tokens` (floors to v2) but roles
- * only resolve if the bundle includes these sheets. Skip when the entry already
- * imports them. Remove this inject at DES-227 cutover when `tokens.css` *is* v2.
+ * Every supported source shape becomes one canonical import before Tailwind
+ * expands it. The aliases remain package-compatible, but are no longer allowed
+ * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
-export function cssAlreadyImportsSheet(code, sheetFileName) {
-    return code.includes(sheetFileName);
+export function normalizeAtlasUiTokenImports(code) {
+    const deprecatedImports = new Set();
+    const withoutTokenImports = code.replace(ATLAS_UI_TOKEN_IMPORT, (importLine, sheet) => {
+        const normalizedSheet = String(sheet).toLowerCase();
+        if (normalizedSheet !== 'tokens.css')
+            deprecatedImports.add(normalizedSheet);
+        return '';
+    });
+    return {
+        code: insertAfterImports(withoutTokenImports, [CANONICAL_TOKEN_IMPORT]),
+        deprecatedImports: [...deprecatedImports],
+    };
 }
-/** Absolute or package `@import` lines to prepend when the CSS entry lacks v2 sheets. */
-export function planAtlasUiV2CssImports(code, _atlasUiDir) {
-    const imports = [];
-    // Package subpaths — resolved via Vite alias (PEER_RESOLVE_ALIAS). Prefer
-    // package form over absolute paths so Tailwind/Vite follow the same path as
-    // hand-written author imports.
-    if (!cssAlreadyImportsSheet(code, 'tokens.v2.css')) {
-        imports.push('@import "@sequenceholdings/atlas-ui/tokens.v2.css";');
+/**
+ * Evidence mirrors the CSS transform: aliases are normalized away, so the only
+ * selected sheet is the canonical token entry point.
+ */
+export function collectAtlasUiResolvedTokenSelections({ cssModules, }) {
+    for (const { code } of cssModules) {
+        if (!code.includes('@import "tailwindcss"'))
+            continue;
+        return [{
+                specifier: '@sequenceholdings/atlas-ui/tokens.css',
+                injectedBy: atlasUiTokenImportSheets(code).includes('tokens.css') ? null : 'atlas-ui-css-resolver',
+            }];
     }
-    if (!cssAlreadyImportsSheet(code, 'theme.v2.css')) {
-        imports.push('@import "@sequenceholdings/atlas-ui/theme.v2.css";');
+    return [];
+}
+/** Put Tailwind source directives after the import block but before style rules. */
+function insertAfterImports(code, lines) {
+    const importPattern = /@import\s+[^;]+;/gi;
+    let lastImport = null;
+    for (let match = importPattern.exec(code); match; match = importPattern.exec(code)) {
+        lastImport = match;
     }
-    return imports;
+    const block = `\n${lines.join('\n')}`;
+    if (lastImport?.index === undefined)
+        return `${lines.join('\n')}\n${code}`;
+    const end = lastImport.index + lastImport[0].length;
+    return `${code.slice(0, end)}${block}${code.slice(end)}`;
 }
-export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, }) {
+export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
     return {
         name: 'atlas-ui-css-resolver',
         enforce: 'pre',
         transform(code, id) {
             if (!id.endsWith('.css'))
                 return undefined;
+            onTransform?.({ id, code });
             let result = code;
             if (result.includes('@import "tailwindcss"')) {
                 result = result.replace('@import "tailwindcss"', `@import ${JSON.stringify(tailwindCssPath)}`);
@@ -57,8 +88,9 @@ export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRenderer
                 if (formRendererDist) {
                     sources.push(`@source ${JSON.stringify(formRendererDist)};`);
                 }
-                const v2Imports = planAtlasUiV2CssImports(result, atlasUiDir);
-                result = `${sources.join('\n')}\n${v2Imports.join('\n')}${v2Imports.length > 0 ? '\n' : ''}${result}`;
+                const tokenImports = normalizeAtlasUiTokenImports(result);
+                result = tokenImports.code;
+                result = insertAfterImports(result, sources);
             }
             if (result.includes('@import "tw-animate-css"')) {
                 result = result.replace('@import "tw-animate-css"', `@import ${JSON.stringify(twAnimateCssPath)}`);

package/dist/build-provenance.d.ts

@@ -0,0 +1,50 @@
+import type { ArtifactStudioPeerVersions } from './peer-versions.js';
+import type { AtlasUiResolvedTokenSelection } from './atlas-ui-css-plugin.js';
+export declare const ARTIFACT_BUILD_PROVENANCE_VERSION = 1;
+export interface ArtifactSourceRevision {
+    commit: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+}
+export interface ArtifactTokenResolution {
+    specifier: string;
+    resolvedPath: string;
+    contentHash: string;
+    cssLayers: string[];
+    injectedBy: string | null;
+}
+/** Observed local build evidence; values are not independently verified by Atlas. */
+export interface ObservedBuildEvidence {
+    schemaVersion: typeof ARTIFACT_BUILD_PROVENANCE_VERSION;
+    channel: 'active' | 'preview';
+    toolchain: {
+        cliVersion: string;
+        selection: 'published' | 'linked';
+    };
+    atlasUi: {
+        version: string;
+        contentHash: string;
+    };
+    tokenResolution: {
+        modelVersion: 1;
+        entries: ArtifactTokenResolution[];
+    };
+    sourceRevision: ArtifactSourceRevision;
+}
+/**
+ * Evidence from the exact Atlas UI alias targets selected by this build. The
+ * format deliberately records paths and resolved layers, rather than naming a
+ * migration generation; future canonical token entry points need no schema
+ * change.
+ */
+export declare function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, tokenSelections }: {
+    atlasUiDir: string;
+    atlasUiDist: string;
+    /** Exact tokens.css alias target; releases and linked candidates use different layouts. */
+    atlasUiTokens: string;
+    channel: ObservedBuildEvidence['channel'];
+    linked: boolean;
+    peerVersions: ArtifactStudioPeerVersions;
+    sourceRevision: ArtifactSourceRevision;
+    tokenSelections: readonly AtlasUiResolvedTokenSelection[];
+}): ObservedBuildEvidence;

package/dist/build-provenance.js

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { sha256Hex } from './hash.js';
+export const ARTIFACT_BUILD_PROVENANCE_VERSION = 1;
+function cssLayers(content) {
+    return [...content.matchAll(/@layer\s+([\w-]+)/g)].map((match) => match[1]).filter((x) => x !== undefined);
+}
+function contentIdentity(entries) {
+    return sha256Hex(entries.slice().sort((a, b) => a.path.localeCompare(b.path)).map((entry) => `${entry.path}\0${entry.contentHash}`).join('\0'));
+}
+/**
+ * Evidence from the exact Atlas UI alias targets selected by this build. The
+ * format deliberately records paths and resolved layers, rather than naming a
+ * migration generation; future canonical token entry points need no schema
+ * change.
+ */
+export function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, tokenSelections }) {
+    const knownTargets = new Map([
+        ['@sequenceholdings/atlas-ui/tokens.css', { filePath: atlasUiTokens }],
+        ['@sequenceholdings/atlas-ui/tokens.v2.css', { filePath: `${atlasUiDir}/tokens.v2.css` }],
+        ['@sequenceholdings/atlas-ui/theme.v2.css', { filePath: `${atlasUiDir}/theme.v2.css` }],
+    ]);
+    const entries = tokenSelections.map((target) => {
+        const resolved = knownTargets.get(target.specifier);
+        if (!resolved)
+            throw new Error(`Unknown Atlas UI token target: ${target.specifier}`);
+        const filePath = resolved.filePath;
+        const content = readFileSync(filePath, 'utf8');
+        return { specifier: target.specifier, resolvedPath: relative(atlasUiDir, filePath), contentHash: sha256Hex(content), cssLayers: cssLayers(content), injectedBy: target.injectedBy };
+    });
+    const identityEntries = [
+        ...entries.map((entry) => ({ path: entry.resolvedPath, contentHash: entry.contentHash })),
+        { path: 'dist/index.mjs', contentHash: sha256Hex(readFileSync(`${atlasUiDist}/index.mjs`)) },
+        { path: 'dist/charts.mjs', contentHash: sha256Hex(readFileSync(`${atlasUiDist}/charts.mjs`)) },
+    ];
+    return {
+        schemaVersion: ARTIFACT_BUILD_PROVENANCE_VERSION,
+        channel,
+        toolchain: { cliVersion: peerVersions.cliVersion, selection: linked ? 'linked' : 'published' },
+        atlasUi: { version: peerVersions.atlasUiVersion, contentHash: contentIdentity(identityEntries) },
+        tokenResolution: { modelVersion: 1, entries },
+        sourceRevision,
+    };
+}

package/dist/build-subprocess.d.ts

@@ -6,6 +6,8 @@ export interface IsolatedBuildOptions {
     signal?: AbortSignal;
     /** Parent environment override for deterministic security tests. */
     sourceEnv?: NodeJS.ProcessEnv;
+    /** Explicitly report canonical-token compatibility for an Atlas UI --link preview. */
+    candidateTokenCompatibility?: boolean;
 }
 /**
  * Run a single artifact build in a short-lived child process and return its
@@ -14,4 +16,4 @@ export interface IsolatedBuildOptions {
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal, sourceEnv }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;
+export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal, sourceEnv, candidateTokenCompatibility }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;

package/dist/build-subprocess.js

@@ -17,7 +17,7 @@ const DEFAULT_WORKER_PATH = existsSync(BUILT_WORKER_PATH)
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal, sourceEnv } = {}) {
+export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal, sourceEnv, candidateTokenCompatibility = false } = {}) {
     const scratch = await mkdtemp(join(tmpdir(), 'artifact-build-'));
     const outFile = join(scratch, 'result.json');
     const homeDir = join(scratch, 'home');
@@ -29,6 +29,7 @@ export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEF
             outFile,
             homeDir,
             signal,
+            candidateTokenCompatibility,
             ...(sourceEnv ? { sourceEnv } : {}),
         });
         return JSON.parse(await readFile(outFile, 'utf8'));
@@ -37,7 +38,7 @@ export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEF
         await rm(scratch, { recursive: true, force: true });
     }
 }
-function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, }) {
+function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, candidateTokenCompatibility, }) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new Error('build aborted'));
@@ -46,6 +47,8 @@ function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, }) {
         const workerArgs = workerPath.endsWith('.ts')
             ? ['--import', 'tsx', workerPath, dir, outFile]
             : [workerPath, dir, outFile];
+        if (candidateTokenCompatibility)
+            workerArgs.push('--candidate-token-compatibility');
         const child = spawn(process.execPath, workerArgs, {
             stdio: ['ignore', 'inherit', 'pipe'],
             env: createScrubbedChildEnv({

package/dist/build-worker.js

@@ -13,13 +13,15 @@
 import { writeFile } from 'node:fs/promises';
 import { buildArtifactStudioProject } from './build.js';
 async function main() {
-    const [dir, outFile] = process.argv.slice(2);
+    const [dir, outFile, candidateFlag] = process.argv.slice(2);
     if (!dir || !outFile) {
         process.stderr.write('usage: build-worker <projectDir> <outFile>\n');
         process.exitCode = 2;
         return;
     }
-    const result = await buildArtifactStudioProject(dir);
+    const result = await buildArtifactStudioProject(dir, {
+        candidateTokenCompatibility: candidateFlag === '--candidate-token-compatibility',
+    });
     await writeFile(outFile, JSON.stringify(result), 'utf8');
 }
 main().catch((error) => {

package/dist/build.d.ts

@@ -1,20 +1,14 @@
+import { type ObservedBuildEvidence } from './build-provenance.js';
 import { type ArtifactStudioSourceFile } from './project.js';
 import type { ArtifactStudioManifest } from './manifest.js';
 import { type ArtifactStudioPeerVersions } from './peer-versions.js';
 /**
- * Import aliases for the Vite build. Artifacts are built against their own
- * source tree, which usually has no installed node_modules, so every bare
- * import the scaffold relies on is aliased to this package's pinned copy.
- * This also pins a single instance of each library — one React, one
- * react-query QueryClient context — so a duplicate copy can't silently break
- * hooks or the provider/consumer link. Exported so it can be regression-tested
- * (a missing/unresolvable peer must fail loudly).
- *
- * **CLI atlas-ui stamp (DES-254):** the atlas-ui a bundle gets is whatever
- * *this* CLI package resolves — not a semver the artifact declares.
- * See `VERSION-PIN.md`.
+ * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
+ * candidate layout puts the generated entry at package root so it can be read
+ * before a workspace build. Accept both: ordinary CLI builds retain their
+ * released pin, and explicit linked previews prefer the synced root entry.
  */
-/** Platform + common artifact runtime peers — always aliased over node_modules. */
+export declare function resolveAtlasUiTokensPath(packageDir: string): string;
 export declare const PEER_RESOLVE_ALIAS: Record<string, string>;
 export interface ArtifactStudioRuntimeChunk {
     /** Vite/Rollup output path, always under `chunks/`. */
@@ -39,8 +33,16 @@ export interface ArtifactStudioBuildResult {
     bundleHash: string;
     /** CLI + force-aliased atlas-ui versions that built this bundle (DES-254). */
     peerVersions: ArtifactStudioPeerVersions;
+    /** Exact CLI-resolved UI/token evidence; deployment adds source revision + channel. */
+    observedBuildEvidence: Omit<ObservedBuildEvidence, 'channel' | 'sourceRevision'>;
+    /** Source diagnostics that do not prevent a build. */
+    diagnostics?: string[];
 }
-export declare function buildArtifactStudioProject(rootDir: string): Promise<ArtifactStudioBuildResult>;
+export declare function buildArtifactStudioProject(rootDir: string, { candidateTokenCompatibility, atlasUiPackageDir, }?: {
+    candidateTokenCompatibility?: boolean;
+    /** Explicit linked Atlas UI package, used by candidate toolchain hosts. */
+    atlasUiPackageDir?: string;
+}): Promise<ArtifactStudioBuildResult>;
 export declare function writeBuildArtifact(result: ArtifactStudioBuildResult, outPath: string): Promise<void>;
 export declare function hashBundleAndChunks({ bundle, chunks, }: {
     bundle: string;

package/dist/build.js

@@ -1,14 +1,18 @@
+import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, relative, resolve } from 'node:path';
 import { build as viteBuild } from 'vite';
-import { atlasUiCssResolverPlugin } from './atlas-ui-css-plugin.js';
+import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections } from './atlas-ui-css-plugin.js';
+import { createObservedBuildEvidence } from './build-provenance.js';
 import { sha256Hex } from './hash.js';
 import { isArtifactIgnoredPath } from './artifact-ignore.js';
 import { readArtifactStudioSource } from './project.js';
 import { normalizeArtifactPath } from './paths.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { ARTIFACT_RUNTIME_CHUNK_DIR, assertSafeRuntimeChunkFileName } from './runtime-chunks.js';
+import { rejectOutsideSourcePlugin } from './source-boundary.js';
+import { collectCandidateTokenCompatibilityDiagnostics, collectDeprecatedTokenImportDiagnostics, } from './token-contract.js';
 /** Keep in sync with `atlas/src/server/services/artifact-studio/limits.ts`. */
 const MAX_DEPLOY_SOURCEMAP_BYTES = 10 * 1024 * 1024;
 const cliRequire = createRequire(import.meta.url);
@@ -25,6 +29,17 @@ const reactRouterDomDir = dirname(cliRequire.resolve('react-router-dom/package.j
 const sonnerDir = dirname(cliRequire.resolve('sonner'));
 const atlasUiDir = dirname(cliRequire.resolve('@sequenceholdings/atlas-ui/package.json'));
 const atlasUiDist = resolve(atlasUiDir, 'dist');
+/**
+ * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
+ * candidate layout puts the generated entry at package root so it can be read
+ * before a workspace build. Accept both: ordinary CLI builds retain their
+ * released pin, and explicit linked previews prefer the synced root entry.
+ */
+export function resolveAtlasUiTokensPath(packageDir) {
+    const rootEntry = resolve(packageDir, 'tokens.css');
+    return existsSync(rootEntry) ? rootEntry : resolve(packageDir, 'dist', 'tokens.css');
+}
+const atlasUiTokens = resolveAtlasUiTokensPath(atlasUiDir);
 // The shared Lattice form renderer is aliased the same way as atlas-ui (it is
 // an atlas-ui-peer library, prebuilt to dist). Resolved via ./package.json —
 // the package's exports map exposes it precisely so this resolve (and
@@ -45,53 +60,74 @@ const formRendererDist = resolve(formRendererDir, 'dist');
  * See `VERSION-PIN.md`.
  */
 /** Platform + common artifact runtime peers — always aliased over node_modules. */
-export const PEER_RESOLVE_ALIAS = {
-    'react/jsx-runtime': resolve(reactDir, 'jsx-runtime.js'),
-    'react/jsx-dev-runtime': resolve(reactDir, 'jsx-dev-runtime.js'),
-    react: reactDir,
-    'react-dom/client': resolve(reactDomDir, 'client'),
-    'react-dom': reactDomDir,
-    '@tanstack/react-query': reactQueryDir,
-    'react-router-dom': reactRouterDomDir,
-    sonner: sonnerDir,
-    // v2 token entry points live at the PACKAGE ROOT, not in dist (the generator
-    // writes them there and `files` publishes them from there). Without these
-    // keys the imports fall through to the bare `atlas-ui` alias below — which
-    // prefix-matches and rewrites them to `<dist>/index.mjs/tokens.v2.css`, a
-    // path that doesn't exist, so the artifact build fails on a CSS import.
-    '@sequenceholdings/atlas-ui/tokens.v2.css': resolve(atlasUiDir, 'tokens.v2.css'),
-    '@sequenceholdings/atlas-ui/theme.v2.css': resolve(atlasUiDir, 'theme.v2.css'),
-    '@sequenceholdings/atlas-ui/tokens.css': resolve(atlasUiDist, 'tokens.css'),
-    '@sequenceholdings/atlas-ui/charts': resolve(atlasUiDist, 'charts.mjs'),
-    '@sequenceholdings/atlas-ui': resolve(atlasUiDist, 'index.mjs'),
-    // Alias keys prefix-match, so subpath entries MUST precede their bare key
-    // (same ordering as tokens.css/charts above the bare atlas-ui key).
-    '@sequenceholdings/lattice-form-renderer/golden': resolve(formRendererDist, 'golden.mjs'),
-    '@sequenceholdings/lattice-form-renderer': resolve(formRendererDist, 'index.mjs'),
-};
+function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
+    const selectedAtlasUiDist = resolve(atlasUiPackageDir, 'dist');
+    const selectedAtlasUiTokens = resolveAtlasUiTokensPath(atlasUiPackageDir);
+    return {
+        'react/jsx-runtime': resolve(reactDir, 'jsx-runtime.js'),
+        'react/jsx-dev-runtime': resolve(reactDir, 'jsx-dev-runtime.js'),
+        react: reactDir,
+        'react-dom/client': resolve(reactDomDir, 'client'),
+        'react-dom': reactDomDir,
+        '@tanstack/react-query': reactQueryDir,
+        'react-router-dom': reactRouterDomDir,
+        sonner: sonnerDir,
+        // Candidate Atlas UI exposes canonical tokens at the package root; released
+        // 2.0.1 keeps them in dist. Preserve explicit alias resolution so legacy
+        // source reaches the normalizer instead of falling through to the bare alias.
+        '@sequenceholdings/atlas-ui/tokens.v2.css': resolve(atlasUiPackageDir, 'tokens.v2.css'),
+        '@sequenceholdings/atlas-ui/theme.v2.css': resolve(atlasUiPackageDir, 'theme.v2.css'),
+        '@sequenceholdings/atlas-ui/tokens.css': selectedAtlasUiTokens,
+        '@sequenceholdings/atlas-ui/charts': resolve(selectedAtlasUiDist, 'charts.mjs'),
+        '@sequenceholdings/atlas-ui': resolve(selectedAtlasUiDist, 'index.mjs'),
+        // Alias keys prefix-match, so subpath entries MUST precede their bare key
+        // (same ordering as tokens.css/charts above the bare atlas-ui key).
+        '@sequenceholdings/lattice-form-renderer/golden': resolve(formRendererDist, 'golden.mjs'),
+        '@sequenceholdings/lattice-form-renderer': resolve(formRendererDist, 'index.mjs'),
+    };
+}
+export const PEER_RESOLVE_ALIAS = createPeerResolveAlias();
 function isAssetOutput(value) {
     return value.type === 'asset';
 }
-export async function buildArtifactStudioProject(rootDir) {
+export async function buildArtifactStudioProject(rootDir, { candidateTokenCompatibility = false, atlasUiPackageDir, } = {}) {
+    const peerResolveAlias = atlasUiPackageDir
+        ? createPeerResolveAlias({ atlasUiPackageDir })
+        : PEER_RESOLVE_ALIAS;
+    const selectedAtlasUiDir = atlasUiPackageDir ?? atlasUiDir;
+    const selectedAtlasUiDist = resolve(atlasUiPackageDir ?? atlasUiDir, 'dist');
+    const selectedAtlasUiTokens = resolveAtlasUiTokensPath(selectedAtlasUiDir);
     const source = await readArtifactStudioSource(rootDir);
+    const diagnostics = [
+        ...collectDeprecatedTokenImportDiagnostics({ files: source.files }),
+        ...(candidateTokenCompatibility
+            ? collectCandidateTokenCompatibilityDiagnostics({ files: source.files })
+            : []),
+    ];
     const root = source.root;
+    const transformedCssModules = new Map();
     const result = await viteBuild({
         root,
         configFile: false,
         logLevel: 'silent',
         plugins: [
+            rejectOutsideSourcePlugin({
+                root,
+                trustedExternalRoots: Object.values(peerResolveAlias).map((target) => dirname(target)),
+            }),
             rejectIgnoredSourcePlugin(root, source.ignorePatterns),
             artifactSdkVirtualModule(),
             atlasUiCssResolverPlugin({
-                atlasUiDir,
-                atlasUiDist,
+                atlasUiDir: selectedAtlasUiDir,
+                atlasUiDist: selectedAtlasUiDist,
                 formRendererDist,
+                onTransform: ({ id, code }) => transformedCssModules.set(id, code),
             }),
             nextStubPlugin(),
             (await import('@tailwindcss/vite')).default(),
         ],
         resolve: {
-            alias: PEER_RESOLVE_ALIAS,
+            alias: peerResolveAlias,
         },
         build: {
             write: false,
@@ -119,6 +155,22 @@ export async function buildArtifactStudioProject(rootDir) {
     const bundle = css ? injectCssRuntime(css) + '\n' + entry.code : entry.code;
     const chunks = collectRuntimeChunks(output);
     const sourceMap = fitSourceMapForDeploy(collectSourceMap(output));
+    const peerVersions = resolveArtifactStudioPeerVersions();
+    const observedBuildEvidence = createObservedBuildEvidence({
+        atlasUiDir: selectedAtlasUiDir,
+        atlasUiDist: selectedAtlasUiDist,
+        atlasUiTokens: selectedAtlasUiTokens,
+        channel: 'active',
+        linked: atlasUiPackageDir !== undefined,
+        peerVersions,
+        sourceRevision: { commit: null, branch: null, dirty: null },
+        tokenSelections: collectAtlasUiResolvedTokenSelections({
+            cssModules: [...transformedCssModules].map(([id, code]) => ({ id, code })),
+            atlasUiDir: selectedAtlasUiDir,
+            atlasUiDist: selectedAtlasUiDist,
+            formRendererDist,
+        }),
+    });
     return {
         manifest: source.manifest,
         files: source.files,
@@ -128,7 +180,14 @@ export async function buildArtifactStudioProject(rootDir) {
         bundleFormat: 'esm',
         sourceMap,
         bundleHash: hashBundleAndChunks({ bundle, chunks }),
-        peerVersions: resolveArtifactStudioPeerVersions(),
+        peerVersions,
+        diagnostics,
+        observedBuildEvidence: {
+            schemaVersion: observedBuildEvidence.schemaVersion,
+            toolchain: observedBuildEvidence.toolchain,
+            atlasUi: observedBuildEvidence.atlasUi,
+            tokenResolution: observedBuildEvidence.tokenResolution,
+        },
     };
 }
 /**