@sequenceholdings/artifact-studio 0.1.15 → 0.2.1

package/dist/cli.js

@@ -6,6 +6,7 @@ import { getJson, getJsonOr404, postJson } from './api.js';
 import { ENV_URLS, readLocalConfig, resolveEnvironment, writeLocalConfig, } from './config.js';
 import { writeBuildArtifact } from './build.js';
 import { buildArtifactStudioProjectIsolated } from './build-subprocess.js';
+import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { prepareArtifactBuildRoot } from './prepare-build.js';
 import { parseArtifactStudioManifest } from './manifest.js';
 import { hasArtifactStudioManifest, readArtifactStudioSource } from './project.js';
@@ -14,6 +15,7 @@ import { acquireDevLock } from './dev-lock.js';
 import { runWatchLoop } from './watch-loop.js';
 import { hashLinkedSources, parseLinks, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist, } from './dev-link.js';
 import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
+import { assertActiveDeployProvenance } from './active-deploy-policy.js';
 import yaml from 'js-yaml';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
@@ -41,6 +43,11 @@ const USAGE = `usage:
   repo's default branch). The target project comes from the source's
   artifact.bundle.yml project_id.
 
+  Official (active) deploys require a clean \`main\` checkout with a resolved
+  git commit — merge first, then \`deploy --repo …\` (or a clean local \`main\`
+  checkout). Feature branches and dirty trees are preview-only
+  (\`artifact dev\` / preview channel).
+
   Interactive --repo builds clone over smart-HTTP and require a repo:read git
   PAT in ATLAS_GIT_PAT — create one with \`seq-studio auth pat create --scopes
   repo:read\` or in Atlas → Settings → Tokens. Headless M2M builds use JSON
@@ -302,25 +309,31 @@ async function showCommand(args) {
     const deployment = project.activeDeployment;
     if (deployment) {
         console.log(`  active deployment:`);
-        console.log(`    version:    ${deployment.version}`);
-        console.log(`    sourceHash: ${deployment.sourceHash}`);
-        if (deployment.gitCommit) {
-            const dirty = deployment.gitDirty ? ' (dirty)' : '';
-            const branch = deployment.gitBranch ? ` on ${deployment.gitBranch}` : '';
-            console.log(`    git:        ${deployment.gitCommit.slice(0, 12)}${branch}${dirty}`);
-        }
-        if (deployment.deployMessage)
-            console.log(`    message:    ${deployment.deployMessage}`);
-        if (deployment.createdAt)
-            console.log(`    deployedAt: ${deployment.createdAt}`);
-        if (deployment.createdBy)
-            console.log(`    deployedBy: ${deployment.createdBy}`);
+        logActiveDeploymentDetails(deployment);
     }
     else {
         console.log(`  active deployment: none`);
     }
     return 0;
 }
+function logActiveDeploymentDetails(deployment) {
+    console.log(`    version:    ${deployment.version}`);
+    console.log(`    sourceHash: ${deployment.sourceHash}`);
+    if (deployment.gitCommit) {
+        const dirty = deployment.gitDirty ? ' (dirty)' : '';
+        const branch = deployment.gitBranch ? ` on ${deployment.gitBranch}` : '';
+        console.log(`    git:        ${deployment.gitCommit.slice(0, 12)}${branch}${dirty}`);
+    }
+    if (deployment.cliVersion || deployment.atlasUiVersion) {
+        console.log(`    peers:      artifact-studio@${deployment.cliVersion ?? '?'} atlas-ui@${deployment.atlasUiVersion ?? '?'}`);
+    }
+    if (deployment.deployMessage)
+        console.log(`    message:    ${deployment.deployMessage}`);
+    if (deployment.createdAt)
+        console.log(`    deployedAt: ${deployment.createdAt}`);
+    if (deployment.createdBy)
+        console.log(`    deployedBy: ${deployment.createdBy}`);
+}
 async function validateCommand(args) {
     const dir = resolve(args.positional[0] ?? '.');
     const source = await readArtifactStudioSource(dir);
@@ -359,7 +372,8 @@ async function buildCommand(args) {
         await writeBuildArtifact(result, out);
         console.log(`[seq-studio] built ${result.manifest.bundle.name}`);
         console.log(`[seq-studio] source: ${result.sourceHash}`);
-        console.log(`[seq-studio] bundle: ${result.bundleHash}`);
+        console.log(`[seq-studio] bundle: ${result.bundleHash} (${result.bundleFormat}, ${result.chunks.length} chunks)`);
+        console.log(`[seq-studio] peers: artifact-studio@${result.peerVersions.cliVersion} atlas-ui@${result.peerVersions.atlasUiVersion}`);
         console.log(`[seq-studio] wrote ${out}`);
         reportSandboxWarnings(lintArtifactSandbox(result.files));
         return 0;
@@ -388,12 +402,29 @@ async function planCommand(args) {
             return 0;
         }
         const remote = await fetchRemoteProject({ env: env.url, token, slug: result.manifest.artifact.project_id });
-        if (!remote)
+        if (!remote) {
             console.log('  action: create project and deploy');
-        else if (remote.activeDeployment?.sourceHash === result.sourceHash)
+            return 0;
+        }
+        // Mirror the deploy --skip-unchanged decision exactly: identical source
+        // with a different (or unrecorded) CLI/atlas-ui pin still redeploys, so
+        // plan must not report no-op there.
+        const active = remote.activeDeployment;
+        if (activeDeploymentMatchesSkipPin({
+            active,
+            sourceHash: result.sourceHash,
+            peerVersions: result.peerVersions,
+        })) {
             console.log('  action: no-op');
-        else
-            console.log(`  action: deploy over ${remote.activeDeployment?.version ?? 'no active deployment'}`);
+        }
+        else if (active && active.sourceHash === result.sourceHash) {
+            console.log(`  action: deploy over ${active.version} ` +
+                `(source unchanged; pin moves ${active.cliVersion ?? 'unrecorded'}/${active.atlasUiVersion ?? 'unrecorded'} ` +
+                `→ ${result.peerVersions.cliVersion}/${result.peerVersions.atlasUiVersion})`);
+        }
+        else {
+            console.log(`  action: deploy over ${active?.version ?? 'no active deployment'}`);
+        }
         return 0;
     }
     finally {
@@ -412,20 +443,31 @@ async function deployCommand(args) {
         token,
     });
     try {
+        // Fail closed before build / project create — active deploys must already
+        // look like a clean `main` checkout. Preview (`dev`) never hits this path.
+        assertActiveDeployProvenance(source.provenance);
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
-        // the remote active deployment already matches. Lets CI redeploy every
-        // artifact on every release without paying a vite build + upload for the
-        // unchanged ones. sourceHash covers manifest + all source files, so any
-        // real change falls through to a full deploy.
+        // the remote active deployment already matches *and* was built with the
+        // same CLI/atlas-ui pin. Lets CI redeploy every artifact on every release
+        // without paying a vite build + upload for the unchanged ones. sourceHash
+        // covers manifest + all source files; peer versions cover the force-alias
+        // inputs (DES-254) so a newer CLI still rebuilds identical source.
         if (args.flags['skip-unchanged'] === true) {
             const unbuilt = await readArtifactStudioSource(source.dir);
             const slug = unbuilt.manifest.artifact.project_id;
             const remote = explicitProjectId
                 ? (await getJsonOr404({ baseUrl: env.url, token, path: `/api/artifact-studio/projects/${explicitProjectId}` }))?.project ?? null
                 : await fetchRemoteProject({ env: env.url, token, slug });
-            if (remote?.activeDeployment?.sourceHash === unbuilt.sourceHash) {
+            const peerVersions = resolveArtifactStudioPeerVersions();
+            const active = remote?.activeDeployment;
+            if (activeDeploymentMatchesSkipPin({
+                active,
+                sourceHash: unbuilt.sourceHash,
+                peerVersions,
+            }) && active) {
                 console.log(`[seq-studio] ${slug} unchanged on ${env.name} ` +
-                    `(active ${remote.activeDeployment.version} matches source ${unbuilt.sourceHash.slice(0, 12)}) — skipping deploy`);
+                    `(active ${active.version} matches source ${unbuilt.sourceHash.slice(0, 12)} ` +
+                    `+ peers artifact-studio@${peerVersions.cliVersion} atlas-ui@${peerVersions.atlasUiVersion}) — skipping deploy`);
                 return 0;
             }
         }
@@ -692,6 +734,21 @@ async function rollbackCommand(args) {
     console.log(`[seq-studio] rolled back to ${deploymentId}`);
     return 0;
 }
+/**
+ * Whether `--skip-unchanged` may no-op: same source *and* same CLI/atlas-ui
+ * pin. Missing peer fields on older rows force a rebuild so the pin becomes
+ * observable (DES-254).
+ */
+export function activeDeploymentMatchesSkipPin({ active, sourceHash, peerVersions, }) {
+    if (!active)
+        return false;
+    if (active.sourceHash !== sourceHash)
+        return false;
+    if (!active.cliVersion || !active.atlasUiVersion)
+        return false;
+    return (active.cliVersion === peerVersions.cliVersion &&
+        active.atlasUiVersion === peerVersions.atlasUiVersion);
+}
 /**
  * Deploys never change a live project's visibility — the Studio sharing UI /
  * PATCH own that. The manifest's targets.<env>.visibility is honored at
@@ -773,11 +830,15 @@ async function uploadDeployment({ env, token, projectId, result, channel, previe
             manifest: result.manifest,
             files: result.files,
             bundle: result.bundle,
+            chunks: result.chunks.map((chunk) => ({ fileName: chunk.fileName, content: chunk.code })),
+            bundleFormat: result.bundleFormat,
             sourceMap: result.sourceMap,
             ...(version ? { version } : {}),
             channel,
             previewKey,
             deployMessage: message ?? null,
+            cliVersion: result.peerVersions.cliVersion,
+            atlasUiVersion: result.peerVersions.atlasUiVersion,
             ...provenance,
         },
     });

package/dist/peer-versions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Versions of the packages that actually land in an artifact bundle under the
+ * CLI atlas-ui stamp (DES-254). See `VERSION-PIN.md`.
+ *
+ * - `cliVersion` — `@sequenceholdings/artifact-studio` (the build package that
+ *   owns `PEER_RESOLVE_ALIAS`).
+ * - `atlasUiVersion` — the `@sequenceholdings/atlas-ui` copy resolved from
+ *   *that* package's dependency tree (not the artifact's package.json).
+ */
+export interface ArtifactStudioPeerVersions {
+    cliVersion: string;
+    atlasUiVersion: string;
+}
+/**
+ * Resolve the building CLI + force-aliased atlas-ui versions from disk.
+ * Throws if either package.json is unreadable — a silent null here would
+ * undermine the observability DES-254 adds for the blast-radius scanner.
+ */
+export declare function resolveArtifactStudioPeerVersions(): ArtifactStudioPeerVersions;

package/dist/peer-versions.js

@@ -0,0 +1,44 @@
+import { readFileSync } 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 thisModuleDir = dirname(fileURLToPath(import.meta.url));
+function readPackageVersion({ packageJsonPath, expectedName }) {
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed.name === 'string' && parsed.name !== expectedName) {
+        throw new Error(`Expected package name ${expectedName} at ${packageJsonPath}, got ${parsed.name}`);
+    }
+    if (typeof parsed.version !== 'string' || parsed.version.trim() === '') {
+        throw new Error(`Missing version in ${packageJsonPath}`);
+    }
+    return parsed.version.trim();
+}
+/**
+ * Resolve the building CLI + force-aliased atlas-ui versions from disk.
+ * Throws if either package.json is unreadable — a silent null here would
+ * undermine the observability DES-254 adds for the blast-radius scanner.
+ */
+export function resolveArtifactStudioPeerVersions() {
+    // Built code lives in `dist/`; package.json sits one level up. The same
+    // relative path works when vitest loads from `src/`.
+    const cliPackageJson = resolve(thisModuleDir, '..', 'package.json');
+    const atlasUiPackageJson = cliRequire.resolve('@sequenceholdings/atlas-ui/package.json');
+    return {
+        cliVersion: readPackageVersion({
+            packageJsonPath: cliPackageJson,
+            expectedName: '@sequenceholdings/artifact-studio',
+        }),
+        atlasUiVersion: readPackageVersion({
+            packageJsonPath: atlasUiPackageJson,
+            expectedName: '@sequenceholdings/atlas-ui',
+        }),
+    };
+}

package/dist/project.d.ts

@@ -9,6 +9,9 @@ export interface ArtifactStudioSource {
     manifest: ArtifactStudioManifest;
     files: ArtifactStudioSourceFile[];
     sourceHash: string;
+    /** Path prefixes from `.artifactignore` — also enforced as non-importable by Vite. */
+    ignorePatterns: string[];
 }
 export declare function hasArtifactStudioManifest(rootDir: string): boolean;
 export declare function readArtifactStudioSource(rootDir: string): Promise<ArtifactStudioSource>;
+export declare function loadArtifactIgnorePatterns(root: string): Promise<string[]>;

package/dist/project.js

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import yaml from 'js-yaml';
+import { ARTIFACT_IGNORE_FILE, isArtifactIgnoredPath, parseArtifactIgnore, } from './artifact-ignore.js';
 import { computeSourceHash } from './hash.js';
 import { parseArtifactStudioManifest } from './manifest.js';
 import { normalizeArtifactPath } from './paths.js';
@@ -16,7 +17,8 @@ export async function readArtifactStudioSource(rootDir) {
     const root = resolve(rootDir);
     const rawManifest = yaml.load(await readFile(join(root, 'artifact.bundle.yml'), 'utf8'));
     const manifest = parseArtifactStudioManifest(rawManifest);
-    const files = await collectSourceFiles(root);
+    const ignorePatterns = await loadArtifactIgnorePatterns(root);
+    const files = await collectSourceFiles(root, ignorePatterns);
     if (!files.some((file) => file.path === manifest.artifact.entrypoint)) {
         throw new Error(`Entrypoint file not found: ${manifest.artifact.entrypoint}`);
     }
@@ -26,22 +28,28 @@ export async function readArtifactStudioSource(rootDir) {
         files,
         // Hash the RAW manifest, not the parsed one — see computeSourceHash.
         sourceHash: computeSourceHash({ files, manifest: rawManifest }),
+        ignorePatterns,
     };
 }
-async function collectSourceFiles(root) {
+async function collectSourceFiles(root, ignorePatterns) {
     const files = [];
     async function walk(dir) {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
+            // Built-in ignores first — `normalizeArtifactPath` rejects `node_modules`
+            // (and similar) as source paths, so we must not normalize those names.
+            if (entry.isDirectory() && IGNORED_DIRS.has(entry.name))
+                continue;
             const absolute = join(dir, entry.name);
+            const path = normalizeArtifactPath(relative(root, absolute));
+            if (isArtifactIgnoredPath(path, ignorePatterns))
+                continue;
             if (entry.isDirectory()) {
-                if (!IGNORED_DIRS.has(entry.name))
-                    await walk(absolute);
+                await walk(absolute);
                 continue;
             }
             if (!entry.isFile())
                 continue;
-            const path = normalizeArtifactPath(relative(root, absolute));
             if (!isTextFile(path))
                 continue;
             files.push({
@@ -54,9 +62,17 @@ async function collectSourceFiles(root) {
     await walk(root);
     return files.sort((a, b) => a.path.localeCompare(b.path));
 }
+export async function loadArtifactIgnorePatterns(root) {
+    const ignorePath = join(root, ARTIFACT_IGNORE_FILE);
+    if (!existsSync(ignorePath))
+        return [];
+    return parseArtifactIgnore(await readFile(ignorePath, 'utf8'));
+}
 function isTextFile(path) {
     const ext = path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
-    return path === 'artifact.bundle.yml' || TEXT_EXTENSIONS.has(ext);
+    return (path === 'artifact.bundle.yml' ||
+        path === ARTIFACT_IGNORE_FILE ||
+        TEXT_EXTENSIONS.has(ext));
 }
 function inferContentType(path) {
     if (path.endsWith('.tsx') || path.endsWith('.ts'))

package/dist/runtime-chunks.d.ts

@@ -0,0 +1,4 @@
+/** Vite async-chunk namespace. Keep in sync with atlas `limits.ts` (ARTIFACT_RUNTIME_CHUNK_DIR). */
+export declare const ARTIFACT_RUNTIME_CHUNK_DIR = "chunks";
+export declare function isArtifactRuntimeChunkPath(path: string): boolean;
+export declare function assertSafeRuntimeChunkFileName(fileName: string): string;

package/dist/runtime-chunks.js

@@ -0,0 +1,15 @@
+/** Vite async-chunk namespace. Keep in sync with atlas `limits.ts` (ARTIFACT_RUNTIME_CHUNK_DIR). */
+export const ARTIFACT_RUNTIME_CHUNK_DIR = 'chunks';
+export function isArtifactRuntimeChunkPath(path) {
+    return path === ARTIFACT_RUNTIME_CHUNK_DIR || path.startsWith(`${ARTIFACT_RUNTIME_CHUNK_DIR}/`);
+}
+export function assertSafeRuntimeChunkFileName(fileName) {
+    const normalized = fileName.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!isArtifactRuntimeChunkPath(normalized)) {
+        throw new Error(`Runtime chunk path must be under ${ARTIFACT_RUNTIME_CHUNK_DIR}/: ${fileName}`);
+    }
+    if (normalized.includes('..') || normalized.startsWith('/')) {
+        throw new Error(`Invalid runtime chunk path: ${fileName}`);
+    }
+    return normalized;
+}

package/dist/sdk.d.ts

@@ -10,6 +10,12 @@ export interface SequenceApiFetchResponse<TBody = unknown> {
 }
 export interface SequenceApiUploadOptions {
     timeoutMs?: number;
+    /**
+     * HTTP method for the multipart request. Defaults to POST; PUT is allowed
+     * for update-with-file routes (e.g. replacing an existing disclosure's
+     * file). Both are gated by the same `capabilities.api.write` check.
+     */
+    method?: 'POST' | 'PUT';
 }
 export interface SequenceApi {
     fetch<TBody = unknown>(path: string, options?: SequenceApiFetchOptions): Promise<SequenceApiFetchResponse<TBody>>;
@@ -90,6 +96,17 @@ export interface SequenceHost {
      * user to an external origin.
      */
     navigate(path: string): void;
+    /**
+     * Coordinate a viewport-modal scrim with the parent Atlas shell. The
+     * artifact keeps ownership of its dialog and in-frame scrim; the host only
+     * dims shell chrome outside the iframe. Calls are reference-counted by
+     * `overlayId`, so every open transition must eventually send `open: false`.
+     */
+    setOverlayState(state: {
+        overlayId: string;
+        scope: 'viewport';
+        open: boolean;
+    }): void;
 }
 export interface SequenceArtifactSdk {
     api: SequenceApi;

package/dist/source-resolver.js

@@ -153,14 +153,38 @@ export function localGitMetadata(dir) {
     };
     try {
         const gitCommit = String(execFileSync('git', ['rev-parse', 'HEAD'], gitOpts)).trim();
-        const gitBranch = String(execFileSync('git', ['branch', '--show-current'], gitOpts)).trim();
+        let gitBranch = String(execFileSync('git', ['branch', '--show-current'], gitOpts)).trim();
+        // GitHub Actions (and similar) check out a SHA → detached HEAD even when
+        // deploying main. Map that back to `main` only when HEAD equals the tip of
+        // main / origin/main — do not trust GITHUB_REF alone (workflow branch can
+        // differ from the checked-out SHA).
+        if (!gitBranch) {
+            gitBranch = resolveDetachedMainBranch({ gitOpts, gitCommit }) ?? '';
+        }
         const gitDirty = String(execFileSync('git', ['status', '--porcelain'], gitOpts)).trim().length > 0;
-        return { gitCommit, gitBranch, gitDirty };
+        return { gitCommit, gitBranch: gitBranch || null, gitDirty };
     }
     catch {
         return { gitCommit: null, gitBranch: null, gitDirty: null };
     }
 }
+/**
+ * When `git branch --show-current` is empty (detached HEAD), return `main` if
+ * HEAD is exactly the tip of a local/remote main ref — otherwise null.
+ */
+function resolveDetachedMainBranch({ gitOpts, gitCommit, }) {
+    for (const ref of ['refs/heads/main', 'main', 'refs/remotes/origin/main', 'origin/main']) {
+        try {
+            const tip = String(execFileSync('git', ['rev-parse', ref], gitOpts)).trim();
+            if (tip === gitCommit)
+                return 'main';
+        }
+        catch {
+            // ref missing in this clone (shallow / no remotes) — try the next one
+        }
+    }
+    return null;
+}
 async function makeTempDir() {
     const dir = await mkdtemp(join(tmpdir(), 'artifact-src-'));
     // Canonicalize: the Vite html plugin emits the entry file name relative to

package/dist/templates/react-vite/AGENTS.md

@@ -0,0 +1,90 @@
+# Sequence Artifact Studio app
+
+This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend routes through a postMessage bridge exposed as `seq.api.*` from `@sequenceholdings/artifact-studio`. No direct network access, no API keys in the bundle — everything goes through the bridge, and every endpoint the artifact uses must be declared in `artifact.bundle.yml`.
+
+## Three rules that bite
+
+1. **Envelope unwrap.** Atlas wraps every CRM-style response in `{ success: true, data: T }`. The bridge passes that envelope through raw — it does **not** unwrap automatically. Route every read/write through `unwrap<T>()` in `src/lib/api.ts`:
+   ```ts
+   import { unwrap, seq } from './lib/api'
+   const customer = await unwrap<Customer>(seq.api.get(`/api/crm/customers/${id}`))
+   ```
+   For endpoints with extra envelope fields (pagination `meta`, warnings), drop to `seq.api.fetch` and read `res.body` directly.
+
+2. **FormData blocker.** `seq.api.fetch` `JSON.stringify`s any non-string `body` value, which silently turns `FormData` into `"{}"`. For multipart uploads, use `seq.api.upload(path, file, fields?, options?)`; the bridge constructs `FormData` in the trusted host and returns the usual `{ ok, status, body }` envelope.
+
+3. **Capability matcher: exact paths, `/*` prefix wildcards, and single-segment `*` patterns.** `{id}` template forms do **not** match. List both the bare path and the prefix wildcard for broad resources, or use a least-privilege segment pattern for dynamic routes:
+   ```yaml
+   - /api/crm/customers
+   - /api/crm/customers/*
+   - /api/lattice/runs/*/advance
+   ```
+
+## Prerequisite
+
+None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
+
+## Package manager
+
+Use **pnpm** for artifacts you will deploy from git — `seq-studio artifact build|deploy --repo/--git-url` runs `pnpm install --frozen-lockfile --prod` when `package.json` is present, so commit `pnpm-lock.yaml`. Local editor-only installs can use another package manager, but pnpm keeps Sequence's `minimumReleaseAge` supply-chain quarantine in effect (see the studio-cli README). If you have a stale checkout from the old `file:`-link era, `rm -rf node_modules` and reinstall.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `artifact.bundle.yml` | Capability manifest — every API path the artifact calls: exact paths, `/*` prefix wildcards, or single-segment `*` patterns |
+| `src/main.tsx` | Providers: `QueryClientProvider` → `PortalContainerProvider` → `App` |
+| `src/App.tsx` | Entrypoint UI |
+| `src/lib/api.ts` | `unwrap<T>` envelope helper + re-export of `seq` |
+| `src/styles.css` | Tailwind v4 + `@sequenceholdings/atlas-ui/tokens.css` (+ v2 sheets; build injects them when missing) |
+| `vite.config.ts` | Vite + React + Tailwind v4 plugin |
+
+## Defaults
+
+- UI: prefer `@sequenceholdings/atlas-ui` primitives (`Button`, `Card`, `Input`, `Dialog`, `Select`, `Checkbox`, `DropdownMenu`, `KpiTile`, `Switch`, …) over raw Tailwind. The design-system cutover made `Select`, `Checkbox`, `DropdownMenu`, `Command`, `Calendar`, `ScrollArea`, `Table`, and the Task family first-class exports — use them directly; fall back to `Popover` compositions or native controls only when a component is genuinely missing.
+- Routing: `HashRouter`. Mount routes at `/`, not at the Atlas app prefix.
+- Data: React Query is wired in `src/main.tsx`. Use `useQuery` / `useMutation` against `unwrap(seq.api.*)`.
+- Icons: do **not** add third-party deps like `@tabler/icons-react`. Deploys from git (`--repo` / `--git-url`) build a bare tree — `seq-studio` runs `pnpm install --prod` from your lockfile, then aliases platform peers (`react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, `@sequenceholdings/atlas-ui`). List only app-specific imports (e.g. `recharts`) in `dependencies`; do not add file/workspace `@sequenceholdings/*` specs in git-service repos, because remote installs only accept registry semver specs. Inline SVG components in `src/icons.tsx`.
+
+## Tokens — colour comes from semantic roles, never a raw ramp
+
+This app bundles `@sequenceholdings/atlas-ui/tokens.css` and re-themes per tenant for free. Reach for a **semantic role** and colour follows the host brand and light/dark automatically.
+
+**Never** use the numbered `black-*` / `white-*` opacity scales (`text-black-40`, `bg-black-6`, `border-black-10`), raw Tailwind neutrals (`gray|slate|zinc|neutral|stone-N`), arbitrary hex in class strings (`bg-[#1f2937]`), or `var(--black-*)` / `var(--color-black-*)`. These are **retired** — post-cutover they resolve to nothing or to a fixed ink that won't flip in dark. Bare `text-white` / `bg-black` and opacity modifiers like `bg-foreground/10` stay legal; only the numbered steps and raw palettes are banned. There is no old→new lookup table on purpose — pick by *what the element is and what it sits on*.
+
+| Situation | Role |
+|---|---|
+| The page surface | `bg-background` — the page only, never a panel |
+| Bordered/rounded panel, card, list | `bg-card` — a border is not a surface; every bordered container needs an explicit surface |
+| Inset well inside a card (code block, read-only value) | `bg-muted` |
+| Form field (input, textarea, select trigger) | `bg-field` |
+| Interactive / hover fill | `bg-accent` / `bg-surface-hover` |
+| Selected / active / focus state fill | `bg-foreground/8`–`bg-foreground/15` overlay |
+| Modal scrim behind a dialog | `bg-overlay` — never `bg-foreground/N` (washes lighter in dark) |
+| Primary text | `text-foreground` |
+| Resting nav items, meta rows | `text-foreground-secondary` |
+| Section labels, captions | `text-muted-foreground` |
+| Standard border | `border-border` (form controls: `border-input`) |
+
+Surfaces **nest** — never repeat a rung (`bg-card` inside `bg-card` is invisible): `bg-background` (page) → `bg-card` (panel, + border + `shadow-xs` to lift) → `bg-muted` (inset well).
+
+**Dual-runtime.** Inside Atlas the artifact runs in its own iframe and inherits nothing — the runtime posts the host's resolved brand in as inline custom properties (theme channel + `data-tokens`). Standalone `vite dev` has no host, so the artifact must still render on the base semantic roles. **Do not** bundle `tokens.v2.tenants.css`, hardcode an opco's brand, or add `[data-theme]` selectors — that pins the artifact to one tenant.
+
+## Bridge methods
+
+Two primitives on `seq.api`:
+
+- `seq.api.fetch(path, options?)` returns `{ ok, status, body }` — does not throw on non-2xx. Use when you need the status (e.g. handle 409) or the raw envelope with extra fields like `meta`.
+- `seq.api.request(method, path, body?)` throws on non-2xx and returns parsed JSON. Sugar wrappers `seq.api.get / .post / .patch / .delete` are thin shells around `request`, so they also throw.
+
+Wrap reads/writes that should auto-throw through `unwrap()` in `src/lib/api.ts`. Drop to `seq.api.fetch` when you need pagination `meta` or status inspection.
+
+## Lattice embed context
+
+When the artifact is served from a Lattice human node (the **Tasks/Inbox** task surface, or the builder Artifacts tab), `seq.lattice.context()` tells you which run/node/step you're rendering for:
+
+```ts
+const { runId, nodeId, stepId, processId } = seq.lattice.context()
+```
+
+It's **synchronous** (the host injects this into the sandbox up front — no bridge round trip) and each field is `null` when unavailable. The Inbox provides all four; the builder Artifacts tab has no live `stepId`; a standalone open has no context at all. Use it instead of hand-parsing `window.location` — that's the sanctioned, stable accessor, and you don't need to declare anything in `artifact.bundle.yml` for it. To read step-scoped data, pass `runId`/`stepId` to the relevant Atlas endpoint (which still authorizes the caller server-side).

package/dist/templates/react-vite/CLAUDE.md

@@ -1,66 +1,7 @@
 # Sequence Artifact Studio app
 
-This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend routes through a postMessage bridge exposed as `seq.api.*` from `@sequenceholdings/artifact-studio`. No direct network access, no API keys in the bundle — everything goes through the bridge, and every endpoint the artifact uses must be declared in `artifact.bundle.yml`.
+Agent instructions for this artifact live in `AGENTS.md` — one file every coding agent reads
+(Cursor and Codex load `AGENTS.md` natively; the import below pulls it in for Claude Code).
+Add or edit guidance in `AGENTS.md`, not here.
 
-## Three rules that bite
-
-1. **Envelope unwrap.** Atlas wraps every CRM-style response in `{ success: true, data: T }`. The bridge passes that envelope through raw — it does **not** unwrap automatically. Route every read/write through `unwrap<T>()` in `src/lib/api.ts`:
-   ```ts
-   import { unwrap, seq } from './lib/api'
-   const customer = await unwrap<Customer>(seq.api.get(`/api/crm/customers/${id}`))
-   ```
-   For endpoints with extra envelope fields (pagination `meta`, warnings), drop to `seq.api.fetch` and read `res.body` directly.
-
-2. **FormData blocker.** `seq.api.fetch` `JSON.stringify`s any non-string `body` value, which silently turns `FormData` into `"{}"`. For uploads, base64-encode the bytes and POST as JSON, or patch the Atlas bridge first.
-
-3. **Capability matcher: exact paths, `/*` prefix wildcards, and single-segment `*` patterns.** `{id}` template forms do **not** match. List both the bare path and the prefix wildcard for broad resources, or use a least-privilege segment pattern for dynamic routes:
-   ```yaml
-   - /api/crm/customers
-   - /api/crm/customers/*
-   - /api/lattice/runs/*/advance
-   ```
-
-## Prerequisite
-
-None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
-
-## Package manager
-
-Use **pnpm** for artifacts you will deploy from git — `seq-studio artifact build|deploy --repo/--git-url` runs `pnpm install --frozen-lockfile --prod` when `package.json` is present, so commit `pnpm-lock.yaml`. Local editor-only installs can use another package manager, but pnpm keeps Sequence's `minimumReleaseAge` supply-chain quarantine in effect (see the studio-cli README). If you have a stale checkout from the old `file:`-link era, `rm -rf node_modules` and reinstall.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `artifact.bundle.yml` | Capability manifest — every API path the artifact calls: exact paths, `/*` prefix wildcards, or single-segment `*` patterns |
-| `src/main.tsx` | Providers: `QueryClientProvider` → `PortalContainerProvider` → `App` |
-| `src/App.tsx` | Entrypoint UI |
-| `src/lib/api.ts` | `unwrap<T>` envelope helper + re-export of `seq` |
-| `src/styles.css` | Tailwind v4 + `@sequenceholdings/atlas-ui/tokens.css` |
-| `vite.config.ts` | Vite + React + Tailwind v4 plugin |
-
-## Defaults
-
-- UI: prefer `@sequenceholdings/atlas-ui` primitives (`Button`, `Card`, `Input`, `Dialog`, `Select`, `Checkbox`, `DropdownMenu`, `KpiTile`, `Switch`, …) over raw Tailwind. The design-system cutover made `Select`, `Checkbox`, `DropdownMenu`, `Command`, `Calendar`, `ScrollArea`, `Table`, and the Task family first-class exports — use them directly; fall back to `Popover` compositions or native controls only when a component is genuinely missing.
-- Routing: `HashRouter`. Mount routes at `/`, not at the Atlas app prefix.
-- Data: React Query is wired in `src/main.tsx`. Use `useQuery` / `useMutation` against `unwrap(seq.api.*)`.
-- Icons: do **not** add third-party deps like `@tabler/icons-react`. Deploys from git (`--repo` / `--git-url`) build a bare tree — `seq-studio` runs `pnpm install --prod` from your lockfile, then aliases platform peers (`react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, `@sequenceholdings/atlas-ui`). List only app-specific imports (e.g. `recharts`) in `dependencies`; do not add file/workspace `@sequenceholdings/*` specs in git-service repos, because remote installs only accept registry semver specs. Inline SVG components in `src/icons.tsx`.
-
-## Bridge methods
-
-Two primitives on `seq.api`:
-
-- `seq.api.fetch(path, options?)` returns `{ ok, status, body }` — does not throw on non-2xx. Use when you need the status (e.g. handle 409) or the raw envelope with extra fields like `meta`.
-- `seq.api.request(method, path, body?)` throws on non-2xx and returns parsed JSON. Sugar wrappers `seq.api.get / .post / .patch / .delete` are thin shells around `request`, so they also throw.
-
-Wrap reads/writes that should auto-throw through `unwrap()` in `src/lib/api.ts`. Drop to `seq.api.fetch` when you need pagination `meta` or status inspection.
-
-## Lattice embed context
-
-When the artifact is served from a Lattice human node (the **Tasks/Inbox** task surface, or the builder Artifacts tab), `seq.lattice.context()` tells you which run/node/step you're rendering for:
-
-```ts
-const { runId, nodeId, stepId, processId } = seq.lattice.context()
-```
-
-It's **synchronous** (the host injects this into the sandbox up front — no bridge round trip) and each field is `null` when unavailable. The Inbox provides all four; the builder Artifacts tab has no live `stepId`; a standalone open has no context at all. Use it instead of hand-parsing `window.location` — that's the sanctioned, stable accessor, and you don't need to declare anything in `artifact.bundle.yml` for it. To read step-scoped data, pass `runId`/`stepId` to the relevant Atlas endpoint (which still authorizes the caller server-side).
+@AGENTS.md

package/dist/templates/react-vite/src/main.tsx

@@ -7,7 +7,13 @@ import './styles.css'
 
 const queryClient = new QueryClient()
 
-createRoot(document.getElementById('root')!).render(
+const root = createRoot(document.getElementById('root')!)
+// Platform (same-document) runtime: register so the host can unmount on
+// navigation. No-op inside the sandboxed iframe (registry is never installed).
+;(window as Window & { __atlasArtifactReactRoots__?: Set<{ unmount: () => void }> })
+  .__atlasArtifactReactRoots__?.add(root)
+
+root.render(
   <React.StrictMode>
     <QueryClientProvider client={queryClient}>
       <PortalContainerProvider>

package/dist/templates/react-vite/src/styles.css

@@ -1,11 +1,14 @@
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "@sequenceholdings/atlas-ui/tokens.css";
+@import "@sequenceholdings/atlas-ui/tokens.v2.css";
+@import "@sequenceholdings/atlas-ui/theme.v2.css";
 
 /* Tailwind v4 skips node_modules during automatic source detection, so the
    utility classes compiled into atlas-ui's components are never generated under
-   raw `pnpm dev`. The deploy build auto-injects this @source (build.ts's
-   atlasUiCssResolverPlugin), but plain Vite dev does not — declare it here so
-   scaffolded artifacts render atlas-ui correctly in local dev too. Idempotent
-   with the build-time injection. */
+   raw `pnpm dev`. The deploy build auto-injects this @source and the v2 sheets
+   above when missing (build.ts → atlas-ui-css-plugin); declare them here so
+   scaffolded artifacts render correctly in local vite dev too. Idempotent with
+   build-time injection. At DES-227 cutover, tokens.css becomes v2 — drop the
+   explicit tokens.v2 / theme.v2 imports (and the CLI stops injecting them). */
 @source "../node_modules/@sequenceholdings/atlas-ui/dist";