@sequenceholdings/artifact-studio 0.1.12 → 0.2.0

package/VERSION-PIN.md

@@ -0,0 +1,54 @@
+# CLI atlas-ui stamp (DES-254)
+
+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.
+
+## What this means
+
+`shared/services/artifact-studio/src/build.ts` force-aliases platform peers via
+`PEER_RESOLVE_ALIAS`, including:
+
+- `@sequenceholdings/atlas-ui` (+ tokens / charts subpaths)
+- `@sequenceholdings/lattice-form-renderer`
+- `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`
+
+So the deploy/build path always bundles the CLI package's copy. Listing
+`@sequenceholdings/atlas-ui` in an artifact's `devDependencies` is for editor /
+type-check only; it does not select the bundled version.
+
+## Why
+
+- One React / atlas-ui instance per bundle (no context-breaking duplicates).
+- No consumer version matrix — artifacts move when rebuilt with a newer CLI
+  (or a monorepo checkout whose workspace atlas-ui changed).
+- Matches the product default: artifacts render as platform UI.
+
+## Observability
+
+Each deployment records:
+
+| Field | Meaning |
+| --- | --- |
+| `cliVersion` | `@sequenceholdings/artifact-studio` version that built the bundle |
+| `atlasUiVersion` | Resolved `@sequenceholdings/atlas-ui` version from that CLI's dependency tree |
+
+These feed blast-radius / "who is on which stamp?" questions (DES-259). They are
+`package.json` versions, not content hashes — a `--link`'d local rebuild can
+change code without bumping the version string.
+
+`seq-studio artifact deploy --skip-unchanged` compares both `sourceHash` and
+these peer versions before no-op'ing, so a newer CLI still rebuilds identical
+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.

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

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ *
+ * This checks reported provenance (branch name + explicit clean flag + commit).
+ * It does **not** independently verify that `gitCommit` equals the remote
+ * `origin/main` tip — callers still need to merge and pull/materialize `main`
+ * before deploying.
+ *
+ * Canonical module for the CLI (`@sequenceholdings/artifact-studio`). Atlas
+ * keeps a behavior-identical copy at
+ * `atlas/src/server/services/artifact-studio/active-deploy-policy.ts` so the
+ * API can enforce the same rule without depending on this package's heavy
+ * build graph — keep the two in sync.
+ */
+export interface ActiveDeployProvenance {
+    gitCommit?: string | null;
+    gitBranch?: string | null;
+    gitDirty?: boolean | null;
+}
+/** Canonical default branch name for official artifact deploys. */
+export declare const ACTIVE_DEPLOY_DEFAULT_BRANCH = "main";
+export declare class ActiveDeployPolicyError extends Error {
+    readonly code: "ACTIVE_DEPLOY_POLICY";
+    constructor(message: string);
+}
+/** Strip `refs/heads/` so `refs/heads/main` and `main` compare equal. */
+export declare function normalizeGitBranchName(branch: string | null | undefined): string | null;
+export declare function isActiveDeployDefaultBranch(branch: string | null | undefined): boolean;
+/**
+ * Throw if provenance is not eligible for an official (active) deploy.
+ * Preview callers must not invoke this.
+ */
+export declare function assertActiveDeployProvenance(provenance: ActiveDeployProvenance): void;

package/dist/active-deploy-policy.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ *
+ * This checks reported provenance (branch name + explicit clean flag + commit).
+ * It does **not** independently verify that `gitCommit` equals the remote
+ * `origin/main` tip — callers still need to merge and pull/materialize `main`
+ * before deploying.
+ *
+ * Canonical module for the CLI (`@sequenceholdings/artifact-studio`). Atlas
+ * keeps a behavior-identical copy at
+ * `atlas/src/server/services/artifact-studio/active-deploy-policy.ts` so the
+ * API can enforce the same rule without depending on this package's heavy
+ * build graph — keep the two in sync.
+ */
+/** Canonical default branch name for official artifact deploys. */
+export const ACTIVE_DEPLOY_DEFAULT_BRANCH = 'main';
+export class ActiveDeployPolicyError extends Error {
+    code = 'ACTIVE_DEPLOY_POLICY';
+    constructor(message) {
+        super(message);
+        this.name = 'ActiveDeployPolicyError';
+    }
+}
+/** Strip `refs/heads/` so `refs/heads/main` and `main` compare equal. */
+export function normalizeGitBranchName(branch) {
+    if (branch == null)
+        return null;
+    const trimmed = branch.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.replace(/^refs\/heads\//, '');
+}
+export function isActiveDeployDefaultBranch(branch) {
+    return normalizeGitBranchName(branch) === ACTIVE_DEPLOY_DEFAULT_BRANCH;
+}
+/**
+ * Throw if provenance is not eligible for an official (active) deploy.
+ * Preview callers must not invoke this.
+ */
+export function assertActiveDeployProvenance(provenance) {
+    // Require an explicit clean recording — omitting gitDirty must not pass.
+    if (provenance.gitDirty !== false) {
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a clean git tree ' +
+            '(`gitDirty: false`). Commit or stash your changes, or use ' +
+            '`seq-studio artifact dev` / a preview deploy for dirty feature-branch work.');
+    }
+    const branch = normalizeGitBranchName(provenance.gitBranch);
+    if (!branch) {
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require git provenance on `main`. ' +
+            'Check out `main` (monorepo or local clone) or deploy with ' +
+            '`seq-studio artifact deploy --repo <ns>/<slug>` (defaults to the repo default branch). ' +
+            'Feature branches and detached HEAD (unless at the tip of `main`) are preview-only.');
+    }
+    if (branch !== ACTIVE_DEPLOY_DEFAULT_BRANCH) {
+        throw new ActiveDeployPolicyError(`Active (official) artifact deploys must use \`${ACTIVE_DEPLOY_DEFAULT_BRANCH}\` ` +
+            `(got branch/ref \`${branch}\`). Merge via a Pull, then redeploy from \`main\`; ` +
+            'use a preview channel for feature-branch or dirty local work.');
+    }
+    if (!provenance.gitCommit?.trim()) {
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a resolved git commit on `main`. ' +
+            'Deploy from a git checkout or `--repo` so provenance is recorded.');
+    }
+}

package/dist/api.js

@@ -1,3 +1,4 @@
+import { authenticatedRequestUrl } from './deployment-validation.js';
 const MAX_503_RETRIES = 5;
 const DEFAULT_RETRY_AFTER_SECONDS = 2;
 /**
@@ -47,18 +48,26 @@ async function fetchWith503Retry(input, init) {
         await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
     }
 }
-export async function getJson({ baseUrl, token, path }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        headers: { ...extraHeaders(), Authorization: `Bearer ${token}` },
+async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
+    const url = authenticatedRequestUrl({ baseUrl, path });
+    return fetchWith503Retry(url, {
+        ...init,
+        redirect: 'manual',
+        headers: {
+            ...extraHeaders(),
+            ...init.headers,
+            Authorization: `Bearer ${token}`,
+        },
     });
+}
+export async function getJson({ baseUrl, token, path }) {
+    const response = await authenticatedFetch({ baseUrl, token, path });
     if (!response.ok)
         throw new Error(await responseError('GET', path, response));
     return response.json();
 }
 export async function getJsonOr404({ baseUrl, token, path }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        headers: { ...extraHeaders(), Authorization: `Bearer ${token}` },
-    });
+    const response = await authenticatedFetch({ baseUrl, token, path });
     if (response.status === 404)
         return null;
     if (!response.ok)
@@ -66,14 +75,15 @@ export async function getJsonOr404({ baseUrl, token, path }) {
     return response.json();
 }
 export async function postJson({ baseUrl, token, path, body, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'POST',
-        headers: {
-            ...extraHeaders(),
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!response.ok)
         throw new Error(await responseError('POST', path, response));
@@ -97,6 +107,14 @@ async function responseError(method, path, response) {
             serverMessage = body.detail;
         else if (typeof body.error === 'string' && body.error)
             serverMessage = body.error;
+        // Zod / registry payloads often put the actionable bits next to a generic
+        // detail ("Validation error"). Append a compact summary so deploys aren't
+        // undebuggable when the CLI only prints `detail`.
+        const extras = summarizeStructuredIssues(body.errors ?? body.issues);
+        if (serverMessage && extras)
+            serverMessage = `${serverMessage}: ${extras}`;
+        else if (!serverMessage && extras)
+            serverMessage = extras;
     }
     catch {
         // Non-JSON body (HTML error page, plain text) — fall back to raw text.
@@ -104,3 +122,31 @@ async function responseError(method, path, response) {
     const summary = serverMessage ?? (text.trim() ? text.trim().slice(0, 300) : '(empty response body)');
     return `${method} ${path} failed (HTTP ${response.status}): ${summary}`;
 }
+function summarizeStructuredIssues(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const parts = [];
+    for (const issue of value.slice(0, 5)) {
+        // RegistryValidationError ships `issues` as string[]; Zod uses objects.
+        if (typeof issue === 'string' && issue.trim()) {
+            parts.push(issue.trim());
+            continue;
+        }
+        if (!issue || typeof issue !== 'object')
+            continue;
+        const row = issue;
+        const path = Array.isArray(row.path) ? row.path.map(String).join('.') : '';
+        const message = typeof row.message === 'string' ? row.message : null;
+        if (message) {
+            parts.push(path ? `${path}: ${message}` : message);
+            continue;
+        }
+        if (row.code === 'too_big' && typeof row.maximum === 'number' && path) {
+            parts.push(`${path}: at most ${row.maximum}`);
+        }
+    }
+    if (parts.length === 0)
+        return null;
+    const more = value.length > parts.length ? ` (+${value.length - parts.length} more)` : '';
+    return parts.join('; ') + more;
+}

package/dist/artifact-ignore.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `.artifactignore` — committed trees that must not ship in a deploy payload.
+ *
+ * Sidecar packs (BI catalogs, local agent workspaces, etc.) can live next to
+ * artifact source in git without counting against the API's 500-file / 10MB
+ * source caps. Patterns are path prefixes relative to the artifact root
+ * (gitignore-lite: comments, blanks, trailing slashes; no globs).
+ *
+ * Ignored paths are also rejected as Vite build dependencies — they are
+ * excluded from sourceHash, so an import under an ignored prefix would let
+ * `deploy --skip-unchanged` keep a stale bundle.
+ */
+export declare const ARTIFACT_IGNORE_FILE = ".artifactignore";
+export declare function parseArtifactIgnore(contents: string): string[];
+/** True when `relPath` is exactly a pattern or under a patterned directory. */
+export declare function isArtifactIgnoredPath(relPath: string, patterns: readonly string[]): boolean;

package/dist/artifact-ignore.js

@@ -0,0 +1,38 @@
+/**
+ * `.artifactignore` — committed trees that must not ship in a deploy payload.
+ *
+ * Sidecar packs (BI catalogs, local agent workspaces, etc.) can live next to
+ * artifact source in git without counting against the API's 500-file / 10MB
+ * source caps. Patterns are path prefixes relative to the artifact root
+ * (gitignore-lite: comments, blanks, trailing slashes; no globs).
+ *
+ * Ignored paths are also rejected as Vite build dependencies — they are
+ * excluded from sourceHash, so an import under an ignored prefix would let
+ * `deploy --skip-unchanged` keep a stale bundle.
+ */
+export const ARTIFACT_IGNORE_FILE = '.artifactignore';
+export function parseArtifactIgnore(contents) {
+    const patterns = [];
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const normalized = line.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+        if (normalized)
+            patterns.push(normalized);
+    }
+    return patterns;
+}
+/** True when `relPath` is exactly a pattern or under a patterned directory. */
+export function isArtifactIgnoredPath(relPath, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const normalized = relPath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    if (!normalized)
+        return false;
+    for (const pattern of patterns) {
+        if (normalized === pattern || normalized.startsWith(`${pattern}/`))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,15 @@
+import type { Plugin } from 'vite';
+/**
+ * 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.
+ */
+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, }: {
+    atlasUiDir: string;
+    atlasUiDist: string;
+    formRendererDist: string | null;
+}): Plugin;

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

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const cliRequire = createRequire(import.meta.url);
+const cliDir = dirname(fileURLToPath(import.meta.url));
+const tailwindCssPath = resolve(dirname(cliRequire.resolve('tailwindcss/package.json')), 'index.css');
+const twAnimateCssPath = resolveTwAnimateCssPath();
+function resolveTwAnimateCssPath() {
+    const candidates = [
+        resolve(cliDir, '..', 'node_modules', 'tw-animate-css', 'dist', 'tw-animate.css'),
+        resolve(cliDir, '..', '..', '..', 'tw-animate-css', 'dist', 'tw-animate.css'),
+    ];
+    const resolved = candidates.find((candidate) => existsSync(candidate));
+    if (!resolved) {
+        throw new Error(`Unable to resolve tw-animate-css dist file. Tried: ${candidates.join(', ')}`);
+    }
+    return resolved;
+}
+/**
+ * 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.
+ */
+export function cssAlreadyImportsSheet(code, sheetFileName) {
+    return code.includes(sheetFileName);
+}
+/** 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";');
+    }
+    if (!cssAlreadyImportsSheet(code, 'theme.v2.css')) {
+        imports.push('@import "@sequenceholdings/atlas-ui/theme.v2.css";');
+    }
+    return imports;
+}
+export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, }) {
+    return {
+        name: 'atlas-ui-css-resolver',
+        enforce: 'pre',
+        transform(code, id) {
+            if (!id.endsWith('.css'))
+                return undefined;
+            let result = code;
+            if (result.includes('@import "tailwindcss"')) {
+                result = result.replace('@import "tailwindcss"', `@import ${JSON.stringify(tailwindCssPath)}`);
+                // Prebuilt dists whose class names Tailwind must scan: CLI-pinned
+                // atlas-ui plus the form renderer (field-scope.tsx emits Tailwind
+                // utility classes that only appear in the renderer's dist).
+                const sources = [`@source ${JSON.stringify(atlasUiDist)};`];
+                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}`;
+            }
+            if (result.includes('@import "tw-animate-css"')) {
+                result = result.replace('@import "tw-animate-css"', `@import ${JSON.stringify(twAnimateCssPath)}`);
+            }
+            return result !== code ? result : undefined;
+        },
+    };
+}

package/dist/build-subprocess.d.ts

@@ -4,6 +4,8 @@ export interface IsolatedBuildOptions {
     workerPath?: string;
     /** Abort to kill the in-flight build child (e.g. on watcher shutdown). */
     signal?: AbortSignal;
+    /** Parent environment override for deterministic security tests. */
+    sourceEnv?: NodeJS.ProcessEnv;
 }
 /**
  * Run a single artifact build in a short-lived child process and return its
@@ -12,4 +14,4 @@ export interface IsolatedBuildOptions {
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;
+export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal, sourceEnv }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;

package/dist/build-subprocess.js

@@ -1,9 +1,15 @@
 import { spawn } from 'node:child_process';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const DEFAULT_WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'build-worker.js');
+import { createScrubbedChildEnv } from './child-environment.js';
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const BUILT_WORKER_PATH = join(MODULE_DIR, 'build-worker.js');
+const DEFAULT_WORKER_PATH = existsSync(BUILT_WORKER_PATH)
+    ? BUILT_WORKER_PATH
+    : join(MODULE_DIR, 'build-worker.ts');
 /**
  * Run a single artifact build in a short-lived child process and return its
  * result. The child exits as soon as the build finishes, so the OS reclaims
@@ -11,25 +17,41 @@ const DEFAULT_WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'build
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal } = {}) {
+export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal, sourceEnv } = {}) {
     const scratch = await mkdtemp(join(tmpdir(), 'artifact-build-'));
     const outFile = join(scratch, 'result.json');
+    const homeDir = join(scratch, 'home');
     try {
-        await runWorker({ workerPath, dir, outFile, signal });
+        await mkdir(homeDir, { recursive: true });
+        await runWorker({
+            workerPath,
+            dir,
+            outFile,
+            homeDir,
+            signal,
+            ...(sourceEnv ? { sourceEnv } : {}),
+        });
         return JSON.parse(await readFile(outFile, 'utf8'));
     }
     finally {
         await rm(scratch, { recursive: true, force: true });
     }
 }
-function runWorker({ workerPath, dir, outFile, signal, }) {
+function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, }) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new Error('build aborted'));
             return;
         }
-        const child = spawn(process.execPath, [workerPath, dir, outFile], {
+        const workerArgs = workerPath.endsWith('.ts')
+            ? ['--import', 'tsx', workerPath, dir, outFile]
+            : [workerPath, dir, outFile];
+        const child = spawn(process.execPath, workerArgs, {
             stdio: ['ignore', 'inherit', 'pipe'],
+            env: createScrubbedChildEnv({
+                homeDir,
+                ...(sourceEnv ? { source: sourceEnv } : {}),
+            }),
         });
         const onAbort = () => {
             child.kill('SIGTERM');

package/dist/build.d.ts

@@ -1,5 +1,6 @@
 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
@@ -8,16 +9,40 @@ import type { ArtifactStudioManifest } from './manifest.js';
  * 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`.
  */
 /** Platform + common artifact runtime peers — always aliased over node_modules. */
 export declare const PEER_RESOLVE_ALIAS: Record<string, string>;
+export interface ArtifactStudioRuntimeChunk {
+    /** Vite/Rollup output path, always under `chunks/`. */
+    fileName: string;
+    code: string;
+}
+export type ArtifactStudioBundleFormat = 'esm';
 export interface ArtifactStudioBuildResult {
     manifest: ArtifactStudioManifest;
     files: ArtifactStudioSourceFile[];
+    /** Entry module (ESM). Lazy routes land in `chunks`. */
     bundle: string;
+    /**
+     * Async/shared sub-chunks emitted by Vite when the graph uses dynamic
+     * `import()`. Empty when the entry graph has no split points.
+     */
+    chunks: ArtifactStudioRuntimeChunk[];
+    /** Deploy/serve format. IIFE is gone — it cannot code-split (REP-87). */
+    bundleFormat: ArtifactStudioBundleFormat;
     sourceMap: string | null;
     sourceHash: string;
     bundleHash: string;
+    /** CLI + force-aliased atlas-ui versions that built this bundle (DES-254). */
+    peerVersions: ArtifactStudioPeerVersions;
 }
 export declare function buildArtifactStudioProject(rootDir: string): Promise<ArtifactStudioBuildResult>;
 export declare function writeBuildArtifact(result: ArtifactStudioBuildResult, outPath: string): Promise<void>;
+export declare function hashBundleAndChunks({ bundle, chunks, }: {
+    bundle: string;
+    chunks: readonly ArtifactStudioRuntimeChunk[];
+}): string;