@sequenceholdings/artifact-studio 0.2.3 → 0.2.4

package/VERSION-PIN.md

@@ -4,6 +4,12 @@ A (re)built Artifact Studio app gets whatever `@sequenceholdings/atlas-ui` the
 **building CLI** carries — not a semver the artifact's own `package.json`
 declares.
 
+Artifact Studio 0.2.4 (Studio CLI 0.1.30) pins Atlas UI 3.1.1 exactly.
+Ordinary builds now use its canonical, mode-aware `tokens.css`. Rebuilding an
+existing artifact adopts this toolchain; previously uploaded immutable bundles
+keep their original CSS. Migrate retired numbered black/white utilities to
+semantic roles and verify a preview before activating a rebuilt artifact.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via
@@ -51,7 +57,8 @@ temporary forwarding aliases; the compiler normalizes their source imports to on
 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`.
+class construction. Legacy stylesheet aliases normalize to canonical tokens;
+they do not restore retired utility scales. 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/atlas-ui-package-contract.d.ts

@@ -0,0 +1,7 @@
+export declare class AtlasUiPackageContractError extends Error {
+    constructor(message: string);
+}
+export declare function validateAtlasUiTokenStylesheetContract({ packageDir, resolvedTokensCssPath, }: {
+    packageDir: string;
+    resolvedTokensCssPath: string;
+}): string;

package/dist/atlas-ui-package-contract.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const ATLAS_UI_PACKAGE = '@sequenceholdings/atlas-ui';
+const TOKENS_CSS_EXPORT = './tokens.css';
+export class AtlasUiPackageContractError extends Error {
+    constructor(message) {
+        super(`Atlas UI package contract error: ${message}`);
+        this.name = 'AtlasUiPackageContractError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readExportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isRecord(value)) {
+        for (const key of ['style', 'default', 'import']) {
+            const target = value[key];
+            if (typeof target === 'string')
+                return target;
+        }
+    }
+    return null;
+}
+export function validateAtlasUiTokenStylesheetContract({ packageDir, resolvedTokensCssPath, }) {
+    const packageJsonPath = resolve(packageDir, 'package.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch (error) {
+        throw new AtlasUiPackageContractError(`unable to read ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new AtlasUiPackageContractError(`${packageJsonPath} is not a JSON object`);
+    }
+    if (parsed.name !== ATLAS_UI_PACKAGE) {
+        throw new AtlasUiPackageContractError(`${packageJsonPath} must be ${ATLAS_UI_PACKAGE}, got ${String(parsed.name)}`);
+    }
+    const exportsMap = parsed.exports;
+    if (!isRecord(exportsMap)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE} package.json must declare an exports map`);
+    }
+    const exportTarget = readExportTarget(exportsMap[TOKENS_CSS_EXPORT]);
+    if (!exportTarget) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE} must export ${TOKENS_CSS_EXPORT} to a CSS file included in the package`);
+    }
+    const declaredPath = resolve(packageDir, exportTarget);
+    if (!existsSync(declaredPath)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} points to ${exportTarget}, but ${declaredPath} does not exist`);
+    }
+    if (!existsSync(resolvedTokensCssPath)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} resolved to ${resolvedTokensCssPath}, but that file does not exist`);
+    }
+    if (resolve(resolvedTokensCssPath) !== declaredPath) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} export target (${declaredPath}) and build resolver (${resolvedTokensCssPath}) disagree`);
+    }
+    return declaredPath;
+}

package/dist/build-provenance.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedStylesheet } from './resolved-stylesheets.js';
 import type { ArtifactStudioPeerVersions } from './peer-versions.js';
 import type { AtlasUiResolvedTokenSelection } from './atlas-ui-css-plugin.js';
 export declare const ARTIFACT_BUILD_PROVENANCE_VERSION = 1;
@@ -17,6 +18,7 @@ export interface ArtifactTokenResolution {
 export interface ObservedBuildEvidence {
     schemaVersion: typeof ARTIFACT_BUILD_PROVENANCE_VERSION;
     channel: 'active' | 'preview';
+    /** `cliVersion` is retained for historical records and identifies Artifact Studio. */
     toolchain: {
         cliVersion: string;
         selection: 'published' | 'linked';
@@ -29,6 +31,8 @@ export interface ObservedBuildEvidence {
         modelVersion: 1;
         entries: ArtifactTokenResolution[];
     };
+    /** CSS modules that actually contribute to this artifact's visible cascade. */
+    stylesheets: ResolvedStylesheet[];
     sourceRevision: ArtifactSourceRevision;
 }
 /**
@@ -37,7 +41,7 @@ export interface ObservedBuildEvidence {
  * migration generation; future canonical token entry points need no schema
  * change.
  */
-export declare function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, tokenSelections }: {
+export declare function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, stylesheets, tokenSelections }: {
     atlasUiDir: string;
     atlasUiDist: string;
     /** Exact tokens.css alias target; releases and linked candidates use different layouts. */
@@ -46,5 +50,6 @@ export declare function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, a
     linked: boolean;
     peerVersions: ArtifactStudioPeerVersions;
     sourceRevision: ArtifactSourceRevision;
+    stylesheets?: ResolvedStylesheet[];
     tokenSelections: readonly AtlasUiResolvedTokenSelection[];
 }): ObservedBuildEvidence;

package/dist/build-provenance.js

@@ -14,7 +14,7 @@ function contentIdentity(entries) {
  * migration generation; future canonical token entry points need no schema
  * change.
  */
-export function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, tokenSelections }) {
+export function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, stylesheets = [], tokenSelections }) {
     const knownTargets = new Map([
         ['@sequenceholdings/atlas-ui/tokens.css', { filePath: atlasUiTokens }],
         ['@sequenceholdings/atlas-ui/tokens.v2.css', { filePath: `${atlasUiDir}/tokens.v2.css` }],
@@ -39,6 +39,7 @@ export function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTo
         toolchain: { cliVersion: peerVersions.cliVersion, selection: linked ? 'linked' : 'published' },
         atlasUi: { version: peerVersions.atlasUiVersion, contentHash: contentIdentity(identityEntries) },
         tokenResolution: { modelVersion: 1, entries },
+        stylesheets,
         sourceRevision,
     };
 }

package/dist/build.js

@@ -4,7 +4,9 @@ import { createRequire } from 'node:module';
 import { dirname, relative, resolve } from 'node:path';
 import { build as viteBuild } from 'vite';
 import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections } from './atlas-ui-css-plugin.js';
+import { validateAtlasUiTokenStylesheetContract } from './atlas-ui-package-contract.js';
 import { createObservedBuildEvidence } from './build-provenance.js';
+import { collectResolvedStylesheets } from './resolved-stylesheets.js';
 import { sha256Hex } from './hash.js';
 import { isArtifactIgnoredPath } from './artifact-ignore.js';
 import { readArtifactStudioSource } from './project.js';
@@ -37,7 +39,8 @@ const atlasUiDist = resolve(atlasUiDir, 'dist');
  */
 export function resolveAtlasUiTokensPath(packageDir) {
     const rootEntry = resolve(packageDir, 'tokens.css');
-    return existsSync(rootEntry) ? rootEntry : resolve(packageDir, 'dist', 'tokens.css');
+    const resolvedTokensCssPath = existsSync(rootEntry) ? rootEntry : resolve(packageDir, 'dist', 'tokens.css');
+    return validateAtlasUiTokenStylesheetContract({ packageDir, resolvedTokensCssPath });
 }
 const atlasUiTokens = resolveAtlasUiTokensPath(atlasUiDir);
 // The shared Lattice form renderer is aliased the same way as atlas-ui (it is
@@ -156,20 +159,28 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
     const chunks = collectRuntimeChunks(output);
     const sourceMap = fitSourceMapForDeploy(collectSourceMap(output));
     const peerVersions = resolveArtifactStudioPeerVersions();
+    const cssModules = [...transformedCssModules].map(([id, code]) => ({ id, code }));
+    const tokenSelections = collectAtlasUiResolvedTokenSelections({
+        cssModules,
+        atlasUiDir: selectedAtlasUiDir,
+        atlasUiDist: selectedAtlasUiDist,
+        formRendererDist,
+    });
     const observedBuildEvidence = createObservedBuildEvidence({
         atlasUiDir: selectedAtlasUiDir,
         atlasUiDist: selectedAtlasUiDist,
         atlasUiTokens: selectedAtlasUiTokens,
         channel: 'active',
+        stylesheets: collectResolvedStylesheets({
+            root,
+            atlasUiTokens: selectedAtlasUiTokens,
+            cssModules,
+            tokenSelections,
+        }),
         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,
-        }),
+        tokenSelections,
     });
     return {
         manifest: source.manifest,
@@ -187,6 +198,7 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
             toolchain: observedBuildEvidence.toolchain,
             atlasUi: observedBuildEvidence.atlasUi,
             tokenResolution: observedBuildEvidence.tokenResolution,
+            stylesheets: observedBuildEvidence.stylesheets,
         },
     };
 }

package/dist/resolved-stylesheets.d.ts

@@ -0,0 +1,21 @@
+import type { AtlasUiResolvedTokenSelection } from './atlas-ui-css-plugin.js';
+export interface ResolvedStylesheet {
+    /** Stable display identifier, never an absolute local path. */
+    identifier: string;
+    contentHash: string;
+}
+/**
+ * Records CSS modules Vite actually transformed for the artifact, plus the
+ * canonical Atlas UI sheet selected by the resolver. It deliberately excludes
+ * JavaScript/TypeScript and `?raw` imports: neither participates in CSS
+ * cascade order.
+ */
+export declare function collectResolvedStylesheets({ root, cssModules, tokenSelections, atlasUiTokens, }: {
+    root: string;
+    cssModules: readonly {
+        id: string;
+        code: string;
+    }[];
+    tokenSelections: readonly AtlasUiResolvedTokenSelection[];
+    atlasUiTokens: string;
+}): ResolvedStylesheet[];

package/dist/resolved-stylesheets.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { sha256Hex } from './hash.js';
+const MAX_RECORDED_STYLESHEETS = 100;
+/**
+ * Records CSS modules Vite actually transformed for the artifact, plus the
+ * canonical Atlas UI sheet selected by the resolver. It deliberately excludes
+ * JavaScript/TypeScript and `?raw` imports: neither participates in CSS
+ * cascade order.
+ */
+export function collectResolvedStylesheets({ root, cssModules, tokenSelections, atlasUiTokens, }) {
+    const stylesheets = new Map();
+    if (tokenSelections.some((selection) => selection.specifier === '@sequenceholdings/atlas-ui/tokens.css')) {
+        stylesheets.set('@sequenceholdings/atlas-ui/tokens.css', {
+            identifier: '@sequenceholdings/atlas-ui/tokens.css',
+            contentHash: sha256Hex(readFileSync(atlasUiTokens, 'utf8')),
+        });
+    }
+    for (const { id, code } of cssModules) {
+        if (id.includes('?'))
+            continue;
+        const identifier = relative(root, id).replaceAll('\\', '/');
+        if (!identifier.endsWith('.css') || identifier === '' || identifier.startsWith('../'))
+            continue;
+        stylesheets.set(identifier, { identifier, contentHash: sha256Hex(code) });
+    }
+    // The deployment API accepts at most 100 evidence records. Evidence is
+    // observational, so it must never turn an otherwise valid build into a
+    // failed deployment merely because Vite transformed many stylesheets.
+    return [...stylesheets.values()]
+        .sort((left, right) => left.identifier.localeCompare(right.identifier))
+        .slice(0, MAX_RECORDED_STYLESHEETS);
+}

package/dist/templates/react-vite/package.json

@@ -9,8 +9,8 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.2.1",
-    "@sequenceholdings/atlas-ui": "^2.0.1",
+    "@sequenceholdings/artifact-studio": "^0.2.4",
+    "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",
     "@tanstack/react-query": "^4.36.1",

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -72,7 +72,7 @@
     "VERSION-PIN.md"
   ],
   "dependencies": {
-    "@sequenceholdings/atlas-ui": "2.0.1",
+    "@sequenceholdings/atlas-ui": "3.1.1",
     "@tailwindcss/postcss": "^4.1.8",
     "@tailwindcss/vite": "^4.1.8",
     "@tanstack/react-query": "^4.36.1",
@@ -85,7 +85,7 @@
     "tw-animate-css": "^1.4.0",
     "vite": "8.0.16",
     "zod": "^4.1.13",
-    "@sequenceholdings/lattice-form-renderer": "0.1.2"
+    "@sequenceholdings/lattice-form-renderer": "0.1.3"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/templates/react-vite/package.json

@@ -9,8 +9,8 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.2.1",
-    "@sequenceholdings/atlas-ui": "^2.0.1",
+    "@sequenceholdings/artifact-studio": "^0.2.4",
+    "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",
     "@tanstack/react-query": "^4.36.1",