@astrale-os/cli 1.0.0-beta.20 → 1.0.0-beta.22

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.20",
+    version: "1.0.0-beta.22",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -84421,7 +84421,7 @@ function parseUiLock(value3) {
     throw new UiError("UI_LOCK_INVALID", UI_LOCK_FILE + " is structurally invalid.");
   }
   for (const [address, item] of Object.entries(lock.items)) {
-    if (!/^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(address) || !isRecord8(item) || item.address !== address || !isDigest(item.sourceDigest) || !isRecord8(item.files)) {
+    if (!/^(?:(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(address) || !isRecord8(item) || item.address !== address || !isDigest(item.sourceDigest) || !isRecord8(item.files)) {
       throw new UiError("UI_LOCK_INVALID", UI_LOCK_FILE + " contains an invalid item record.");
     }
     for (const [file2, expected] of Object.entries(item.files)) {
@@ -84776,7 +84776,10 @@ function isInstallableItem(item) {
   if (!item || typeof item !== "object")
     return false;
   const candidate2 = item;
-  return typeof candidate2.name === "string" && /^(?:pattern|block)-[a-z0-9-]+$/u.test(candidate2.name) && candidate2.type === "registry:block" && (candidate2.dependencies === undefined || Array.isArray(candidate2.dependencies) && candidate2.dependencies.every((dependency2) => typeof dependency2 === "string" && /^(?:@[a-z0-9-]+\/)?[a-z0-9-]+@[~^<>=0-9A-Za-z.* -]+$/u.test(dependency2))) && Array.isArray(candidate2.files) && candidate2.files.length > 0 && candidate2.files.every((file2) => file2 && typeof file2.path === "string" && isSafeRelative2(file2.path) && typeof file2.type === "string" && typeof file2.target === "string" && file2.target.startsWith("components/astrale/") && isSafeRelative2(file2.target)) && typeof candidate2.meta?.canonicalAddress === "string" && /^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(candidate2.meta.canonicalAddress);
+  const address = candidate2.meta?.canonicalAddress;
+  const isTheme = candidate2.type === "registry:theme" && typeof candidate2.name === "string" && /^theme-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(candidate2.name) && typeof address === "string" && /^theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(address);
+  const isComposition = candidate2.type === "registry:block" && typeof candidate2.name === "string" && /^(?:pattern|block)-[a-z0-9-]+$/u.test(candidate2.name) && typeof address === "string" && /^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(address);
+  return (isTheme || isComposition) && (candidate2.dependencies === undefined || Array.isArray(candidate2.dependencies) && candidate2.dependencies.every((dependency2) => typeof dependency2 === "string" && /^(?:@[a-z0-9-]+\/)?[a-z0-9-]+@[~^<>=0-9A-Za-z.* -]+$/u.test(dependency2))) && Array.isArray(candidate2.files) && candidate2.files.length > 0 && candidate2.files.every((file2) => file2 && typeof file2.path === "string" && isSafeRelative2(file2.path) && typeof file2.type === "string" && typeof file2.target === "string" && file2.target.startsWith("components/astrale/") && isSafeRelative2(file2.target) && (!isTheme || candidate2.files?.length === 1 && file2.type === "registry:file" && file2.target === "components/astrale/theme/" + address.slice("theme/".length) + ".css")) && typeof address === "string";
 }
 async function readUiRegistryItem(release, expected, fetcher = fetch) {
   const item = await json4(fetcher, registryItemUrl(release, expected.name), "UI registry item " + expected.name);
@@ -84829,6 +84832,32 @@ async function readOptional(target2) {
     return;
   });
 }
+function isLocalThemeAddress(address) {
+  return (address.startsWith("./") || address.startsWith("../")) && address.endsWith(".css");
+}
+function admitLocalThemeCss(source2, slug) {
+  if (new TextEncoder().encode(source2).byteLength > LOCAL_THEME_MAX_BYTES) {
+    throw new UiError("UI_ITEM_CONFLICT", "Local theme CSS exceeds 128 KiB.");
+  }
+  if (!source2.includes("Consumer-owned after installation.") || !source2.includes("[data-ui-theme='" + slug + "']") || !source2.includes("[data-ui-theme='" + slug + "'].dark") || /@import\b|url\s*\(/iu.test(source2) || REQUIRED_THEME_TOKENS.some((token) => source2.match(new RegExp(`--ui-${token}:`, "gu"))?.length !== 2)) {
+    throw new UiError("UI_ITEM_CONFLICT", "Local theme CSS is not an admitted Astrale playground export.", "Export the CSS from the Astrale UI playground, keep its filename aligned with the theme name, and try again.");
+  }
+}
+function themeImport(project2, target2) {
+  let relative = path6.relative(path6.dirname(project2.cssPath), target2).split(path6.sep).join("/");
+  if (!relative.startsWith("."))
+    relative = "./" + relative;
+  return "@import '" + relative + "';";
+}
+function activateTheme(current, statement) {
+  const lines = current.split(/\r?\n/u).filter((line) => !/^@import\s+['"][^'"]*components\/astrale\/theme\/[a-z][a-z0-9-]*\.css['"];?\s*$/u.test(line));
+  const packageImport = lines.reduce((last, line, index3) => /^@import\s+['"]@astrale-os\/ui\/(?:theme\.css|presets\/[a-z-]+\.css)['"];?\s*$/u.test(line) ? index3 : last, -1);
+  lines.splice(packageImport + 1, 0, statement);
+  return lines.join(`
+`).replace(/\n{3,}/gu, `
+
+`).replace(/^\n/u, "");
+}
 function manifestDependencies(manifest) {
   return { ...manifest.dependencies };
 }
@@ -84936,6 +84965,7 @@ async function writeDomainRegistryWorkspace(project2, manifest) {
 }
 async function initUi(options, dependencies = {}) {
   const project2 = await discoverUiProject(options.path);
+  await assertSafePlannedTarget(project2, UI_LOCK_FILE);
   assertSupportedUiProject(project2);
   const preset = options.preset ?? "astrale";
   if (!UI_PRESETS.includes(preset)) {
@@ -85113,16 +85143,111 @@ async function lockedRelease(project2, fetcher) {
   }, fetcher);
   return { lock, release };
 }
+async function addLocalTheme(address, project2, options) {
+  const sourcePath = path6.resolve(project2.root, address);
+  const sourceInfo = await lstat2(sourcePath).catch(() => {
+    return;
+  });
+  if (!sourceInfo?.isFile() || sourceInfo.isSymbolicLink()) {
+    throw new UiError("UI_ITEM_NOT_FOUND", "Local theme is not a regular file: " + address);
+  }
+  const slug = path6.basename(sourcePath, ".css");
+  if (!THEME_SLUG.test(slug)) {
+    throw new UiError("UI_ITEM_CONFLICT", "Local theme filename must be a kebab-case theme name.", "Rename it to a name such as observatory.css.");
+  }
+  const source2 = await readFile18(sourcePath, "utf8");
+  admitLocalThemeCss(source2, slug);
+  return installThemeCss(slug, source2, digest5(source2), address, project2, options);
+}
+async function installThemeCss(slug, source2, sourceDigest, sourceLabel, project2, options) {
+  const lock = await readUiLock(project2.uiLockPath);
+  const canonicalAddress = "theme/" + slug;
+  const relativeTarget = "components/astrale/theme/" + slug + ".css";
+  const target2 = await assertSafePlannedTarget(project2, relativeTarget);
+  const existing = await readOptional(target2);
+  const installed = lock.items[canonicalAddress];
+  if (existing !== undefined && !installed && !options.overwrite) {
+    throw new UiError("UI_LOCAL_CHANGES", "Theme target already exists outside the Astrale UI lock: " + relativeTarget, "Review the file, then repeat with explicit --overwrite --yes.");
+  }
+  if (installed && !options.overwrite) {
+    const expected = installed.files[relativeTarget];
+    if (!expected || digest5(existing ?? "") !== expected) {
+      throw new UiError("UI_LOCAL_CHANGES", "Installed UI file has local changes: " + relativeTarget, "Review the file, then repeat add with explicit --overwrite --yes.");
+    }
+  }
+  const statement = themeImport(project2, target2);
+  const result = {
+    status: options.dryRun ? "planned" : "installed",
+    items: [canonicalAddress],
+    files: { [canonicalAddress]: { [relativeTarget]: digest5(source2) } },
+    activation: { file: projectRelative(project2, project2.cssPath), import: statement },
+    source: sourceLabel
+  };
+  if (options.dryRun)
+    return result;
+  const snapshots = new Map;
+  for (const mutation of [target2, project2.cssPath, project2.uiLockPath]) {
+    snapshots.set(mutation, await readOptional(mutation));
+  }
+  try {
+    await mkdir10(path6.dirname(target2), { recursive: true });
+    await writeFile6(target2, source2, "utf8");
+    const css = await readOptional(project2.cssPath) ?? "";
+    await writeFile6(project2.cssPath, activateTheme(css, statement), "utf8");
+    lock.items[canonicalAddress] = {
+      address: canonicalAddress,
+      sourceDigest,
+      files: { [relativeTarget]: digest5(source2) }
+    };
+    await writeJson(project2.uiLockPath, lock);
+    return result;
+  } catch (error52) {
+    for (const [mutation, previous] of snapshots) {
+      if (previous === undefined)
+        await rm3(mutation, { force: true });
+      else
+        await writeFile6(mutation, previous, "utf8");
+    }
+    throw error52;
+  }
+}
+async function addReleasedTheme(item, document, project2, options) {
+  const slug = item.meta.canonicalAddress.slice("theme/".length);
+  const source2 = document.files[0]?.content;
+  if (typeof source2 !== "string") {
+    throw new UiError("UI_REGISTRY_UNAVAILABLE", "The released theme has no admitted CSS source.");
+  }
+  admitLocalThemeCss(source2, slug);
+  return installThemeCss(slug, source2, digest5(JSON.stringify(document)), item.meta.canonicalAddress, project2, options);
+}
 async function addUi(addresses, options, dependencies = {}) {
   if (addresses.length === 0) {
     throw new UiError("UI_ITEM_NOT_FOUND", "No UI item was provided.");
   }
   const project2 = await discoverUiProject(options.project);
+  await assertSafePlannedTarget(project2, UI_LOCK_FILE);
+  if (options.overwrite && !options.yes) {
+    throw new UiError("UI_LOCAL_CHANGES", "Replacing installed UI source requires explicit confirmation.", "Review the locally edited files, then repeat with both --overwrite and --yes.");
+  }
+  const localThemes = addresses.filter(isLocalThemeAddress);
+  if (localThemes.length > 0) {
+    if (addresses.length !== 1) {
+      throw new UiError("UI_ITEM_CONFLICT", "Install one local theme at a time and do not mix local files with registry addresses.");
+    }
+    return addLocalTheme(localThemes[0], project2, options);
+  }
   const { lock, release } = await lockedRelease(project2, dependencies.fetcher);
   const items = addresses.map((address) => findItem(release, address));
+  const themes = items.filter((item) => item.type === "registry:theme");
+  if (themes.length > 1) {
+    throw new UiError("UI_ITEM_CONFLICT", "Only one theme can be activated per add operation.");
+  }
   const itemDocuments = await Promise.all(items.map((item) => readUiRegistryItem(release, item, dependencies.fetcher)));
-  if (options.overwrite && !options.yes) {
-    throw new UiError("UI_LOCAL_CHANGES", "Replacing installed UI source requires explicit confirmation.", "Review the locally edited files, then repeat with both --overwrite and --yes.");
+  if (themes.length === 1) {
+    if (items.length !== 1) {
+      throw new UiError("UI_ITEM_CONFLICT", "Install a released theme separately from patterns and blocks.");
+    }
+    return addReleasedTheme(themes[0], itemDocuments[0], project2, options);
   }
   await rejectLocalChanges(project2, lock, items, options.overwrite === true);
   const targets = (await Promise.all(items.flatMap((item) => item.files.filter((file2) => file2.target).map((file2) => assertSafePlannedTarget(project2, file2.target))))).filter((target2, index3, all) => all.indexOf(target2) === index3);
@@ -85137,7 +85262,13 @@ async function addUi(addresses, options, dependencies = {}) {
   ]);
   const snapshots = new Map;
   if (!options.dryRun) {
-    for (const target2 of [project2.packageJsonPath, project2.lockPath, ...targets]) {
+    for (const target2 of [
+      project2.packageJsonPath,
+      project2.lockPath,
+      project2.cssPath,
+      project2.uiLockPath,
+      ...targets
+    ]) {
       snapshots.set(target2, await readOptional(target2));
     }
   }
@@ -85154,6 +85285,13 @@ async function addUi(addresses, options, dependencies = {}) {
         }
       }
       await pinUiDependency(project2, lock.package.version, dependencies.runner ?? defaultUiRunner);
+      const theme = themes[0];
+      const themeTarget = theme?.files[0]?.target;
+      if (themeTarget) {
+        const target2 = await safeTarget(project2, themeTarget);
+        const css = await readOptional(project2.cssPath) ?? "";
+        await writeFile6(project2.cssPath, activateTheme(css, themeImport(project2, target2)), "utf8");
+      }
     }
   } catch (error52) {
     for (const [target2, previous] of snapshots) {
@@ -85174,7 +85312,11 @@ async function addUi(addresses, options, dependencies = {}) {
         files: item.files.map((file2) => file2.target).filter(Boolean)
       })),
       command: [invocation3.file, ...invocation3.args],
-      output: result.stdout
+      output: result.stdout,
+      activation: themes[0] ? {
+        file: projectRelative(project2, project2.cssPath),
+        import: themeImport(project2, targets.find((target2) => target2.endsWith(".css")))
+      } : undefined
     };
   }
   try {
@@ -85246,6 +85388,11 @@ async function doctorUi(input) {
         checks3.push({ check: "item:" + item.address + ":" + file2, ok: actual === expected });
       }
     }
+    const themeFiles = Object.values(lock.items).filter((item) => item.address.startsWith("theme/")).flatMap((item) => Object.keys(item.files).filter((file2) => file2.endsWith(".css")));
+    if (themeFiles.length > 0) {
+      const active = themeFiles.some((file2) => css.includes(themeImport(project2, path6.join(project2.root, file2))));
+      checks3.push({ check: "theme-active", ok: active });
+    }
   }
   return { healthy: checks3.every((check3) => check3.ok), checks: checks3 };
 }
@@ -85254,6 +85401,7 @@ async function applyPreset(preset, options) {
     throw new UiError("UI_ITEM_NOT_FOUND", "Unknown preset: " + preset);
   }
   const project2 = await discoverUiProject(options.project);
+  await assertSafePlannedTarget(project2, UI_LOCK_FILE);
   const lock = await readUiLock(project2.uiLockPath);
   const css = await readOptional(project2.cssPath) ?? "";
   const next = css.replace(/@astrale-os\/ui\/presets\/[a-z-]+\.css/gu, "@astrale-os/ui/presets/" + preset + ".css");
@@ -85336,6 +85484,7 @@ async function writeJson(target2, value3) {
   await writeFile6(target2, JSON.stringify(value3, null, 2) + `
 `, "utf8");
 }
+var LOCAL_THEME_MAX_BYTES = 131072, THEME_SLUG, REQUIRED_THEME_TOKENS;
 var init_operations3 = __esm(() => {
   init_dist();
   init_lock();
@@ -85343,6 +85492,44 @@ var init_operations3 = __esm(() => {
   init_project3();
   init_release();
   init_runner();
+  THEME_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+  REQUIRED_THEME_TOKENS = [
+    "background",
+    "foreground",
+    "card",
+    "card-foreground",
+    "popover",
+    "popover-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "destructive",
+    "destructive-foreground",
+    "border",
+    "input",
+    "ring",
+    "chart-1",
+    "chart-2",
+    "chart-3",
+    "chart-4",
+    "chart-5",
+    "font-body",
+    "font-heading",
+    "radius",
+    "radius-panel",
+    "control-height",
+    "control-height-sm",
+    "control-height-lg",
+    "shadow-control",
+    "shadow-panel",
+    "motion-fast",
+    "motion-standard"
+  ];
 });
 
 // src/ui/index.ts
@@ -85425,13 +85612,13 @@ var init_list = __esm(() => {
   init_shared();
   list_default = {
     name: "list",
-    description: "List or search Astrale patterns and blocks",
+    description: "List or search Astrale patterns, blocks, and themes",
     arguments: [{ name: "query", description: "Optional search text", required: false }],
     options: [
       {
         flags: "--type <type>",
-        description: "Restrict to pattern or block",
-        choices: ["pattern", "block"]
+        description: "Restrict to pattern, block, or theme",
+        choices: ["pattern", "block", "theme"]
       },
       { flags: "--limit <n>", description: "Maximum results", default: "100" },
       { flags: "--version <version>", description: "Exact release to inspect" },
@@ -85453,11 +85640,11 @@ var init_add = __esm(() => {
   init_shared();
   add_default = {
     name: "add",
-    description: "Install consumer-owned Astrale pattern or block source",
+    description: "Install consumer-owned Astrale pattern, block, or theme source",
     arguments: [
       {
         name: "items",
-        description: "Canonical pattern or block addresses",
+        description: "Canonical registry addresses or a local exported theme CSS file",
         required: false,
         variadic: true
       }
@@ -85470,8 +85657,8 @@ var init_add = __esm(() => {
       UI_JSON_OPTION
     ],
     afterHelpText: `
-Installed source belongs to the application. Ordinary add never overwrites local edits.
-Run astrale ui doctor before intentionally replacing local source with --overwrite --yes.
+Installed source belongs to the application. Use theme/<name> for a released theme or ./theme.css for a playground export.
+Ordinary add never overwrites local edits. Run astrale ui doctor before intentionally replacing local source with --overwrite --yes.
 `,
     action: async (items, options) => runUiCommand(options, async () => {
       let selected = items;
@@ -85506,8 +85693,13 @@ var init_doctor = __esm(() => {
     name: "doctor",
     description: "Verify Astrale UI package, CSS, config, lock, and installed source integrity",
     arguments: [{ name: "path", description: "Application directory", required: false }],
-    options: [UI_JSON_OPTION],
-    action: async (path7, options) => runUiCommand(options, () => doctorUi(path7))
+    options: [UI_PROJECT_OPTION, UI_JSON_OPTION],
+    action: async (path7, options) => runUiCommand(options, () => {
+      if (path7 && options.project) {
+        throw new UiError("UI_ITEM_CONFLICT", "Choose either the positional application path or --project, not both.");
+      }
+      return doctorUi(options.project ?? path7);
+    })
   };
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.20",
+  "version": "1.0.0-beta.22",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/commands/ui/add.ts

@@ -8,11 +8,11 @@ type Options = UiCommandOptions & { dryRun?: boolean; overwrite?: boolean; yes?:
 
 export default {
   name: 'add',
-  description: 'Install consumer-owned Astrale pattern or block source',
+  description: 'Install consumer-owned Astrale pattern, block, or theme source',
   arguments: [
     {
       name: 'items',
-      description: 'Canonical pattern or block addresses',
+      description: 'Canonical registry addresses or a local exported theme CSS file',
       required: false,
       variadic: true,
     },
@@ -25,7 +25,7 @@ export default {
     UI_JSON_OPTION,
   ],
   afterHelpText:
-    '\nInstalled source belongs to the application. Ordinary add never overwrites local edits.\nRun astrale ui doctor before intentionally replacing local source with --overwrite --yes.\n',
+    '\nInstalled source belongs to the application. Use theme/<name> for a released theme or ./theme.css for a playground export.\nOrdinary add never overwrites local edits. Run astrale ui doctor before intentionally replacing local source with --overwrite --yes.\n',
   action: async (items: string[], options: Options) =>
     runUiCommand(options, async () => {
       let selected = items

package/src/commands/ui/doctor.ts

@@ -1,13 +1,21 @@
 import type { CommandDefinition } from '../../program'
 
-import { doctorUi } from '../../ui'
-import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+import { doctorUi, UiError } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_OPTION, runUiCommand, type UiCommandOptions } from './shared'
 
 export default {
   name: 'doctor',
   description: 'Verify Astrale UI package, CSS, config, lock, and installed source integrity',
   arguments: [{ name: 'path', description: 'Application directory', required: false }],
-  options: [UI_JSON_OPTION],
+  options: [UI_PROJECT_OPTION, UI_JSON_OPTION],
   action: async (path: string | undefined, options: UiCommandOptions) =>
-    runUiCommand(options, () => doctorUi(path)),
+    runUiCommand(options, () => {
+      if (path && options.project) {
+        throw new UiError(
+          'UI_ITEM_CONFLICT',
+          'Choose either the positional application path or --project, not both.',
+        )
+      }
+      return doctorUi(options.project ?? path)
+    }),
 } satisfies CommandDefinition

package/src/commands/ui/list.ts

@@ -7,13 +7,13 @@ type Options = UiCommandOptions & { type?: string; limit?: string; version?: str
 
 export default {
   name: 'list',
-  description: 'List or search Astrale patterns and blocks',
+  description: 'List or search Astrale patterns, blocks, and themes',
   arguments: [{ name: 'query', description: 'Optional search text', required: false }],
   options: [
     {
       flags: '--type <type>',
-      description: 'Restrict to pattern or block',
-      choices: ['pattern', 'block'],
+      description: 'Restrict to pattern, block, or theme',
+      choices: ['pattern', 'block', 'theme'],
     },
     { flags: '--limit <n>', description: 'Maximum results', default: '100' },
     { flags: '--version <version>', description: 'Exact release to inspect' },

package/src/lib/__tests__/view-assets.test.ts

@@ -26,6 +26,17 @@ afterEach(async () => {
 })
 
 describe('viewer asset resolution', () => {
+  test('keeps long placement labels from widening the mounted View viewport', async () => {
+    const source = await readFile(
+      join(import.meta.dirname, '..', '..', '..', 'viewer', 'index.html'),
+      'utf8',
+    )
+
+    expect(source).toContain('#view-label,')
+    expect(source).toContain('text-overflow: ellipsis;')
+    expect(source).toContain('#frame {\n        flex: 1;\n        min-width: 0;')
+  })
+
   test('skips partial candidates and prefers complete package-owned assets', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-view-candidates-'))
     temporaryDirectories.push(root)

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '51546dd7ea5cbf25efbd41f0cd09ceb480abad5be489fc16743500a18e3a02c6',
+      '913d37eab2f603cc745bd9a1c10763a57bc9c2425d0181958d458b80e4a451d7',
     )
   })
 

package/src/ui/.spec/architecture.md

@@ -4,7 +4,10 @@ This private CLI owner manages an existing local React project. It does not conn
 does not add React, Base UI, Tailwind, shadcn, or the UI runtime to the installed CLI dependency
 graph.
 
-One operation resolves one immutable UI commit. Package compatibility and registry reads use that
-commit, and the detected package manager invokes the release-qualified shadcn CLI on demand.
-Application writes complete before the lock advances. Dry-run, list, view, diff, and doctor do not
+One registry operation resolves one immutable UI commit. Package compatibility and registry reads
+use that commit. Patterns and blocks invoke the release-qualified shadcn CLI on demand through the
+detected package manager. Released themes copy the exact admitted embedded CSS directly, while a
+local playground export is admitted and copied without registry or shadcn. Both theme paths install
+consumer-owned source and activate it through one project-relative CSS
+import, and complete application writes before the lock advances. Dry-run, list, and doctor do not
 claim a file mutation.

package/src/ui/.spec/laws.ts

@@ -24,10 +24,17 @@ export const CLI_UI_BOUNDED_REMOTE_DOCUMENTS = defineLaw({
 export const CLI_UI_EXACT_ITEM_SOURCE = defineLaw({
   id: 'CLI-UI-EXACT-ITEM-SOURCE',
   statement:
-    'An add operation admits the exact built item document against the release index and records a content-bearing source digest before invoking project tooling.',
+    'An add operation admits the exact built item document against the release index and records its content-bearing source digest before any consumer mutation; only patterns and blocks invoke project tooling.',
   tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-EXACT-ITEM-SOURCE' }],
 })
 
+export const CLI_UI_THEME_OWNERSHIP = defineLaw({
+  id: 'CLI-UI-THEME-OWNERSHIP',
+  statement:
+    'A released or locally exported theme becomes one project-contained consumer-owned CSS file, is activated by one relative host stylesheet import, and rolls back file, import, and lock together on failure.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-THEME-OWNERSHIP' }],
+})
+
 export const CLI_UI_SEMANTIC_DIFF = defineLaw({
   id: 'CLI-UI-SEMANTIC-DIFF',
   statement:

package/src/ui/__tests__/ui.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from 'bun:test'
-import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 
 import { digest, parseUiLock } from '../lock'
 import { UiError, type UiLock, type UiRegistry } from '../model'
-import { addUi, applyPreset, doctorUi, initUi } from '../operations'
+import { addUi, applyPreset, doctorUi, initUi, listUi } from '../operations'
 import { resolveUiRelease } from '../release'
 import { shadcnInvocation } from '../runner'
 
@@ -28,6 +28,102 @@ const registry: UiRegistry = {
     },
   ],
 }
+const themeCss = `/* Generated from observatory.astrale-theme.json. Consumer-owned after installation. */
+:root,
+[data-ui-theme='observatory'] {
+  --ui-background: #ffffff;
+  --ui-foreground: #111111;
+  --ui-card: #ffffff;
+  --ui-card-foreground: #111111;
+  --ui-popover: #ffffff;
+  --ui-popover-foreground: #111111;
+  --ui-primary: #2244aa;
+  --ui-primary-foreground: #ffffff;
+  --ui-secondary: #eeeeee;
+  --ui-secondary-foreground: #111111;
+  --ui-muted: #eeeeee;
+  --ui-muted-foreground: #555555;
+  --ui-accent: #ddeeff;
+  --ui-accent-foreground: #111111;
+  --ui-destructive: #aa2222;
+  --ui-destructive-foreground: #ffffff;
+  --ui-border: #dddddd;
+  --ui-input: #dddddd;
+  --ui-ring: #2244aa;
+  --ui-chart-1: #2244aa;
+  --ui-chart-2: #228844;
+  --ui-chart-3: #aa7722;
+  --ui-chart-4: #aa2222;
+  --ui-chart-5: #7722aa;
+  --ui-font-body: ui-sans-serif;
+  --ui-font-heading: ui-serif;
+  --ui-radius: 0.5rem;
+  --ui-radius-panel: 0.75rem;
+  --ui-control-height: 2.25rem;
+  --ui-control-height-sm: 2rem;
+  --ui-control-height-lg: 2.5rem;
+  --ui-shadow-control: none;
+  --ui-shadow-panel: none;
+  --ui-motion-fast: 120ms;
+  --ui-motion-standard: 180ms;
+}
+[data-ui-theme='observatory'].dark {
+  --ui-background: #111111;
+  --ui-foreground: #ffffff;
+  --ui-card: #191919;
+  --ui-card-foreground: #ffffff;
+  --ui-popover: #191919;
+  --ui-popover-foreground: #ffffff;
+  --ui-primary: #88aaff;
+  --ui-primary-foreground: #111111;
+  --ui-secondary: #292929;
+  --ui-secondary-foreground: #ffffff;
+  --ui-muted: #292929;
+  --ui-muted-foreground: #bbbbbb;
+  --ui-accent: #334455;
+  --ui-accent-foreground: #ffffff;
+  --ui-destructive: #ff7777;
+  --ui-destructive-foreground: #111111;
+  --ui-border: #333333;
+  --ui-input: #333333;
+  --ui-ring: #88aaff;
+  --ui-chart-1: #88aaff;
+  --ui-chart-2: #77dd99;
+  --ui-chart-3: #ffcc77;
+  --ui-chart-4: #ff7777;
+  --ui-chart-5: #cc88ff;
+  --ui-font-body: ui-sans-serif;
+  --ui-font-heading: ui-serif;
+  --ui-radius: 0.5rem;
+  --ui-radius-panel: 0.75rem;
+  --ui-control-height: 2.25rem;
+  --ui-control-height-sm: 2rem;
+  --ui-control-height-lg: 2.5rem;
+  --ui-shadow-control: none;
+  --ui-shadow-panel: none;
+  --ui-motion-fast: 120ms;
+  --ui-motion-standard: 180ms;
+}
+`
+const themeRegistry: UiRegistry = {
+  name: 'astrale-ui',
+  items: [
+    {
+      name: 'theme-observatory',
+      type: 'registry:theme',
+      description: 'An owned theme.',
+      dependencies: ['@astrale-os/ui@^0.3.0-beta.0'],
+      files: [
+        {
+          path: 'observatory.css',
+          type: 'registry:file',
+          target: 'components/astrale/theme/observatory.css',
+        },
+      ],
+      meta: { canonicalAddress: 'theme/observatory', ownership: 'consumer-source' },
+    },
+  ],
+}
 const compatibility = {
   version: 1,
   shadcn: '4.18.0',
@@ -74,6 +170,38 @@ function mockFetch(seen: string[] = [], suppliedRegistry: UiRegistry = registry)
   }) as typeof fetch
 }
 
+function themeFetch(seen: string[] = []): typeof fetch {
+  return (async (input: string | URL | Request) => {
+    const url = String(input)
+    seen.push(url)
+    if (url.includes('/git/ref/tags/')) {
+      return Response.json({ object: { type: 'commit', sha: commit, url: '' } })
+    }
+    if (url.endsWith('/tooling/compatibility.json')) return Response.json(compatibility)
+    if (url.endsWith('/' + commit + '/registry.json')) {
+      return Response.json({ name: 'astrale-ui', include: ['registry/themes/registry.json'] })
+    }
+    if (url.endsWith('/registry/themes/registry.json')) return Response.json(themeRegistry)
+    if (url.endsWith('/registry/public/r/theme-observatory.json')) {
+      return Response.json(builtThemeItem())
+    }
+    return new Response('not found', { status: 404 })
+  }) as typeof fetch
+}
+
+function builtThemeItem() {
+  return {
+    ...themeRegistry.items[0],
+    files: [
+      {
+        ...themeRegistry.items[0]!.files[0],
+        path: 'registry/themes/observatory.css',
+        content: themeCss,
+      },
+    ],
+  }
+}
+
 function builtItem(item: UiRegistry['items'][number]) {
   return {
     ...item,
@@ -176,6 +304,33 @@ describe('UI release and runner contracts', () => {
     )
   })
 
+  test('admits a release theme as one canonical consumer-owned CSS target', async () => {
+    const release = await resolveUiRelease('0.3.0-beta.0', themeFetch())
+    expect(release.registry.items).toEqual([
+      expect.objectContaining({
+        name: 'theme-observatory',
+        type: 'registry:theme',
+        meta: expect.objectContaining({ canonicalAddress: 'theme/observatory' }),
+        files: [
+          expect.objectContaining({
+            type: 'registry:file',
+            path: 'registry/themes/observatory.css',
+            target: 'components/astrale/theme/observatory.css',
+          }),
+        ],
+      }),
+    ])
+  })
+
+  test('lists release themes through the public type filter', async () => {
+    const themes = await listUi(
+      undefined,
+      { type: 'theme', version: '0.3.0-beta.0' },
+      { fetcher: themeFetch() },
+    )
+    expect(themes.map((item) => item.meta.canonicalAddress)).toEqual(['theme/observatory'])
+  })
+
   test('constructs exact on-demand commands for every supported package manager', () => {
     expect(shadcnInvocation('pnpm', '4.18.0', ['add', 'item'])).toEqual({
       file: 'pnpm',
@@ -724,6 +879,169 @@ describe('UI source operations', () => {
     expect(await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8')).toBe(before)
   })
 
+  /** @evidence TEST-CLI-UI-THEME-OWNERSHIP */
+  test('installs and activates a released theme while recording owned source', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({ style: 'base-nova', tailwind: { css: 'src/index.css' } }),
+    )
+    await writeFile(
+      path.join(root, 'src/index.css'),
+      "@import '@astrale-os/ui/theme.css';\n@import '@astrale-os/ui/presets/astrale.css';\n",
+    )
+    const target = path.join(root, 'components/astrale/theme/observatory.css')
+    let invoked = false
+    const result = await addUi(
+      ['theme/observatory'],
+      { project: root, yes: true },
+      {
+        fetcher: themeFetch(),
+        runner: async () => {
+          invoked = true
+          return { code: 0, stdout: '', stderr: '' }
+        },
+      },
+    )
+
+    expect(invoked).toBe(false)
+    expect(result).toMatchObject({ status: 'installed', items: ['theme/observatory'] })
+    expect(await readFile(target, 'utf8')).toBe(themeCss)
+    expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toContain(
+      "@import '../components/astrale/theme/observatory.css';",
+    )
+    const written = JSON.parse(await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8'))
+    expect(written.items['theme/observatory']).toMatchObject({
+      address: 'theme/observatory',
+      sourceDigest: digest(JSON.stringify(builtThemeItem())),
+      files: { 'components/astrale/theme/observatory.css': digest(themeCss) },
+    })
+    expect((await doctorUi(root)).healthy).toBe(true)
+  })
+
+  /** @evidence TEST-CLI-UI-THEME-OWNERSHIP */
+  test('installs a playground-exported theme without registry or shadcn and preserves edits', async () => {
+    const root = await lockedFixture()
+    const source = path.join(root, 'observatory.css')
+    const target = path.join(root, 'components/astrale/theme/observatory.css')
+    await writeFile(source, themeCss)
+    let invoked = false
+
+    const planned = await addUi(
+      ['./observatory.css'],
+      { project: root, dryRun: true },
+      {
+        fetcher: (async () => {
+          invoked = true
+          throw new Error('must not fetch')
+        }) as unknown as typeof fetch,
+        runner: async () => {
+          invoked = true
+          return { code: 1, stdout: '', stderr: '' }
+        },
+      },
+    )
+    expect(planned).toMatchObject({
+      status: 'planned',
+      items: ['theme/observatory'],
+      activation: {
+        file: 'src/index.css',
+        import: "@import '../components/astrale/theme/observatory.css';",
+      },
+    })
+    expect(await Bun.file(target).exists()).toBe(false)
+
+    await addUi(
+      ['./observatory.css'],
+      { project: root },
+      {
+        fetcher: (async () => {
+          invoked = true
+          throw new Error('must not fetch')
+        }) as unknown as typeof fetch,
+        runner: async () => {
+          invoked = true
+          return { code: 1, stdout: '', stderr: '' }
+        },
+      },
+    )
+    expect(invoked).toBe(false)
+    expect(await readFile(target, 'utf8')).toBe(themeCss)
+    expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toContain(
+      "@import '../components/astrale/theme/observatory.css';",
+    )
+
+    await writeFile(target, 'consumer edit\n')
+    await expect(addUi(['./observatory.css'], { project: root })).rejects.toMatchObject({
+      code: 'UI_LOCAL_CHANGES',
+    })
+    await addUi(['./observatory.css'], { project: root, overwrite: true, yes: true })
+    expect(await readFile(target, 'utf8')).toBe(themeCss)
+  })
+
+  test('rejects malformed and symlinked local themes before project mutation', async () => {
+    const root = await lockedFixture()
+    const cssBefore = await readFile(path.join(root, 'src/index.css'), 'utf8')
+    await writeFile(path.join(root, 'unsafe.css'), "@import 'https://example.invalid/theme.css';\n")
+    await expect(addUi(['./unsafe.css'], { project: root })).rejects.toMatchObject({
+      code: 'UI_ITEM_CONFLICT',
+    })
+
+    const outside = await mkdtemp(path.join(tmpdir(), 'astrale-ui-theme-'))
+    temporary.push(outside)
+    await writeFile(path.join(outside, 'observatory.css'), themeCss)
+    await symlink(path.join(outside, 'observatory.css'), path.join(root, 'linked.css'))
+    await expect(addUi(['./linked.css'], { project: root })).rejects.toMatchObject({
+      code: 'UI_ITEM_NOT_FOUND',
+    })
+    expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toBe(cssBefore)
+  })
+
+  test('rejects a symlinked UI lock before a theme can mutate outside the project', async () => {
+    const root = await lockedFixture()
+    const source = path.join(root, 'observatory.css')
+    await writeFile(source, themeCss)
+    const lockPath = path.join(root, 'astrale-ui.lock.json')
+    const outside = await mkdtemp(path.join(tmpdir(), 'astrale-ui-lock-'))
+    temporary.push(outside)
+    const outsideLock = path.join(outside, 'astrale-ui.lock.json')
+    const lockSource = await readFile(lockPath, 'utf8')
+    await writeFile(outsideLock, lockSource)
+    await rm(lockPath)
+    await symlink(outsideLock, lockPath)
+    const cssBefore = await readFile(path.join(root, 'src/index.css'), 'utf8')
+
+    await expect(addUi(['./observatory.css'], { project: root })).rejects.toMatchObject({
+      code: 'UI_LOCK_INVALID',
+    })
+    expect(await readFile(outsideLock, 'utf8')).toBe(lockSource)
+    expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toBe(cssBefore)
+    expect(
+      await Bun.file(path.join(root, 'components/astrale/theme/observatory.css')).exists(),
+    ).toBe(false)
+  })
+
+  test('rolls back a newly copied local theme and activation when the lock commit fails', async () => {
+    const root = await lockedFixture()
+    await writeFile(path.join(root, 'observatory.css'), themeCss)
+    const lockPath = path.join(root, 'astrale-ui.lock.json')
+    const cssPath = path.join(root, 'src/index.css')
+    const target = path.join(root, 'components/astrale/theme/observatory.css')
+    const lockBefore = await readFile(lockPath, 'utf8')
+    const cssBefore = await readFile(cssPath, 'utf8')
+    await chmod(lockPath, 0o444)
+
+    try {
+      await expect(addUi(['./observatory.css'], { project: root })).rejects.toBeInstanceOf(Error)
+    } finally {
+      await chmod(lockPath, 0o644)
+    }
+
+    expect(await Bun.file(target).exists()).toBe(false)
+    expect(await readFile(cssPath, 'utf8')).toBe(cssBefore)
+    expect(await readFile(lockPath, 'utf8')).toBe(lockBefore)
+  })
+
   test('successful add records installed file digests and doctor detects later edits', async () => {
     const root = await lockedFixture()
     await writeFile(

package/src/ui/lock.ts

@@ -32,7 +32,9 @@ export function parseUiLock(value: unknown): UiLock {
   }
   for (const [address, item] of Object.entries(lock.items)) {
     if (
-      !/^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(address) ||
+      !/^(?:(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(
+        address,
+      ) ||
       !isRecord(item) ||
       item.address !== address ||
       !isDigest(item.sourceDigest) ||

package/src/ui/operations.ts

@@ -6,6 +6,7 @@ import { digest, parseUiLock, readUiLock } from './lock'
 import {
   UI_PACKAGE,
   UI_PRESETS,
+  UI_LOCK_FILE,
   UiError,
   type UiLock,
   type UiPreset,
@@ -28,6 +29,46 @@ import { defaultUiRunner, shadcnInvocation, type UiRunner } from './runner'
 
 type Dependencies = { fetcher?: typeof fetch; runner?: UiRunner }
 
+const LOCAL_THEME_MAX_BYTES = 131_072
+const THEME_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u
+const REQUIRED_THEME_TOKENS = [
+  'background',
+  'foreground',
+  'card',
+  'card-foreground',
+  'popover',
+  'popover-foreground',
+  'primary',
+  'primary-foreground',
+  'secondary',
+  'secondary-foreground',
+  'muted',
+  'muted-foreground',
+  'accent',
+  'accent-foreground',
+  'destructive',
+  'destructive-foreground',
+  'border',
+  'input',
+  'ring',
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'font-body',
+  'font-heading',
+  'radius',
+  'radius-panel',
+  'control-height',
+  'control-height-sm',
+  'control-height-lg',
+  'shadow-control',
+  'shadow-panel',
+  'motion-fast',
+  'motion-standard',
+] as const
+
 async function exists(target: string): Promise<boolean> {
   return access(target).then(
     () => true,
@@ -39,6 +80,60 @@ async function readOptional(target: string): Promise<string | undefined> {
   return readFile(target, 'utf8').catch(() => undefined)
 }
 
+function isLocalThemeAddress(address: string): boolean {
+  return (address.startsWith('./') || address.startsWith('../')) && address.endsWith('.css')
+}
+
+function admitLocalThemeCss(source: string, slug: string): void {
+  if (new TextEncoder().encode(source).byteLength > LOCAL_THEME_MAX_BYTES) {
+    throw new UiError('UI_ITEM_CONFLICT', 'Local theme CSS exceeds 128 KiB.')
+  }
+  if (
+    !source.includes('Consumer-owned after installation.') ||
+    !source.includes("[data-ui-theme='" + slug + "']") ||
+    !source.includes("[data-ui-theme='" + slug + "'].dark") ||
+    /@import\b|url\s*\(/iu.test(source) ||
+    REQUIRED_THEME_TOKENS.some(
+      (token) => source.match(new RegExp(`--ui-${token}:`, 'gu'))?.length !== 2,
+    )
+  ) {
+    throw new UiError(
+      'UI_ITEM_CONFLICT',
+      'Local theme CSS is not an admitted Astrale playground export.',
+      'Export the CSS from the Astrale UI playground, keep its filename aligned with the theme name, and try again.',
+    )
+  }
+}
+
+function themeImport(project: UiProject, target: string): string {
+  let relative = path.relative(path.dirname(project.cssPath), target).split(path.sep).join('/')
+  if (!relative.startsWith('.')) relative = './' + relative
+  return "@import '" + relative + "';"
+}
+
+function activateTheme(current: string, statement: string): string {
+  const lines = current
+    .split(/\r?\n/u)
+    .filter(
+      (line) =>
+        !/^@import\s+['"][^'"]*components\/astrale\/theme\/[a-z][a-z0-9-]*\.css['"];?\s*$/u.test(
+          line,
+        ),
+    )
+  const packageImport = lines.reduce(
+    (last, line, index) =>
+      /^@import\s+['"]@astrale-os\/ui\/(?:theme\.css|presets\/[a-z-]+\.css)['"];?\s*$/u.test(line)
+        ? index
+        : last,
+    -1,
+  )
+  lines.splice(packageImport + 1, 0, statement)
+  return lines
+    .join('\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .replace(/^\n/u, '')
+}
+
 function manifestDependencies(manifest: Record<string, unknown>): Record<string, string> {
   return { ...(manifest.dependencies as Record<string, string> | undefined) }
 }
@@ -191,6 +286,7 @@ export async function initUi(
   dependencies: Dependencies = {},
 ): Promise<Record<string, unknown>> {
   const project = await discoverUiProject(options.path)
+  await assertSafePlannedTarget(project, UI_LOCK_FILE)
   assertSupportedUiProject(project)
   const preset = options.preset ?? 'astrale'
   if (!UI_PRESETS.includes(preset)) {
@@ -427,6 +523,118 @@ async function lockedRelease(
   return { lock, release }
 }
 
+async function addLocalTheme(
+  address: string,
+  project: UiProject,
+  options: { dryRun?: boolean; overwrite?: boolean },
+): Promise<Record<string, unknown>> {
+  const sourcePath = path.resolve(project.root, address)
+  const sourceInfo = await lstat(sourcePath).catch(() => undefined)
+  if (!sourceInfo?.isFile() || sourceInfo.isSymbolicLink()) {
+    throw new UiError('UI_ITEM_NOT_FOUND', 'Local theme is not a regular file: ' + address)
+  }
+  const slug = path.basename(sourcePath, '.css')
+  if (!THEME_SLUG.test(slug)) {
+    throw new UiError(
+      'UI_ITEM_CONFLICT',
+      'Local theme filename must be a kebab-case theme name.',
+      'Rename it to a name such as observatory.css.',
+    )
+  }
+  const source = await readFile(sourcePath, 'utf8')
+  admitLocalThemeCss(source, slug)
+
+  return installThemeCss(slug, source, digest(source), address, project, options)
+}
+
+async function installThemeCss(
+  slug: string,
+  source: string,
+  sourceDigest: string,
+  sourceLabel: string,
+  project: UiProject,
+  options: { dryRun?: boolean; overwrite?: boolean },
+): Promise<Record<string, unknown>> {
+  const lock = await readUiLock(project.uiLockPath)
+  const canonicalAddress = 'theme/' + slug
+  const relativeTarget = 'components/astrale/theme/' + slug + '.css'
+  const target = await assertSafePlannedTarget(project, relativeTarget)
+  const existing = await readOptional(target)
+  const installed = lock.items[canonicalAddress]
+  if (existing !== undefined && !installed && !options.overwrite) {
+    throw new UiError(
+      'UI_LOCAL_CHANGES',
+      'Theme target already exists outside the Astrale UI lock: ' + relativeTarget,
+      'Review the file, then repeat with explicit --overwrite --yes.',
+    )
+  }
+  if (installed && !options.overwrite) {
+    const expected = installed.files[relativeTarget]
+    if (!expected || digest(existing ?? '') !== expected) {
+      throw new UiError(
+        'UI_LOCAL_CHANGES',
+        'Installed UI file has local changes: ' + relativeTarget,
+        'Review the file, then repeat add with explicit --overwrite --yes.',
+      )
+    }
+  }
+  const statement = themeImport(project, target)
+  const result = {
+    status: options.dryRun ? 'planned' : 'installed',
+    items: [canonicalAddress],
+    files: { [canonicalAddress]: { [relativeTarget]: digest(source) } },
+    activation: { file: projectRelative(project, project.cssPath), import: statement },
+    source: sourceLabel,
+  }
+  if (options.dryRun) return result
+
+  const snapshots = new Map<string, string | undefined>()
+  for (const mutation of [target, project.cssPath, project.uiLockPath]) {
+    snapshots.set(mutation, await readOptional(mutation))
+  }
+  try {
+    await mkdir(path.dirname(target), { recursive: true })
+    await writeFile(target, source, 'utf8')
+    const css = (await readOptional(project.cssPath)) ?? ''
+    await writeFile(project.cssPath, activateTheme(css, statement), 'utf8')
+    lock.items[canonicalAddress] = {
+      address: canonicalAddress,
+      sourceDigest,
+      files: { [relativeTarget]: digest(source) },
+    }
+    await writeJson(project.uiLockPath, lock)
+    return result
+  } catch (error) {
+    for (const [mutation, previous] of snapshots) {
+      if (previous === undefined) await rm(mutation, { force: true })
+      else await writeFile(mutation, previous, 'utf8')
+    }
+    throw error
+  }
+}
+
+async function addReleasedTheme(
+  item: UiRegistryItem,
+  document: UiRegistryItem,
+  project: UiProject,
+  options: { dryRun?: boolean; overwrite?: boolean },
+): Promise<Record<string, unknown>> {
+  const slug = item.meta.canonicalAddress.slice('theme/'.length)
+  const source = document.files[0]?.content
+  if (typeof source !== 'string') {
+    throw new UiError('UI_REGISTRY_UNAVAILABLE', 'The released theme has no admitted CSS source.')
+  }
+  admitLocalThemeCss(source, slug)
+  return installThemeCss(
+    slug,
+    source,
+    digest(JSON.stringify(document)),
+    item.meta.canonicalAddress,
+    project,
+    options,
+  )
+}
+
 export async function addUi(
   addresses: string[],
   options: { project?: string; dryRun?: boolean; overwrite?: boolean; yes?: boolean },
@@ -436,11 +644,7 @@ export async function addUi(
     throw new UiError('UI_ITEM_NOT_FOUND', 'No UI item was provided.')
   }
   const project = await discoverUiProject(options.project)
-  const { lock, release } = await lockedRelease(project, dependencies.fetcher)
-  const items = addresses.map((address) => findItem(release, address))
-  const itemDocuments = await Promise.all(
-    items.map((item) => readUiRegistryItem(release, item, dependencies.fetcher)),
-  )
+  await assertSafePlannedTarget(project, UI_LOCK_FILE)
   if (options.overwrite && !options.yes) {
     throw new UiError(
       'UI_LOCAL_CHANGES',
@@ -448,6 +652,34 @@ export async function addUi(
       'Review the locally edited files, then repeat with both --overwrite and --yes.',
     )
   }
+  const localThemes = addresses.filter(isLocalThemeAddress)
+  if (localThemes.length > 0) {
+    if (addresses.length !== 1) {
+      throw new UiError(
+        'UI_ITEM_CONFLICT',
+        'Install one local theme at a time and do not mix local files with registry addresses.',
+      )
+    }
+    return addLocalTheme(localThemes[0]!, project, options)
+  }
+  const { lock, release } = await lockedRelease(project, dependencies.fetcher)
+  const items = addresses.map((address) => findItem(release, address))
+  const themes = items.filter((item) => item.type === 'registry:theme')
+  if (themes.length > 1) {
+    throw new UiError('UI_ITEM_CONFLICT', 'Only one theme can be activated per add operation.')
+  }
+  const itemDocuments = await Promise.all(
+    items.map((item) => readUiRegistryItem(release, item, dependencies.fetcher)),
+  )
+  if (themes.length === 1) {
+    if (items.length !== 1) {
+      throw new UiError(
+        'UI_ITEM_CONFLICT',
+        'Install a released theme separately from patterns and blocks.',
+      )
+    }
+    return addReleasedTheme(themes[0]!, itemDocuments[0]!, project, options)
+  }
   await rejectLocalChanges(project, lock, items, options.overwrite === true)
   const targets = (
     await Promise.all(
@@ -469,7 +701,13 @@ export async function addUi(
   ])
   const snapshots = new Map<string, string | undefined>()
   if (!options.dryRun) {
-    for (const target of [project.packageJsonPath, project.lockPath!, ...targets]) {
+    for (const target of [
+      project.packageJsonPath,
+      project.lockPath!,
+      project.cssPath,
+      project.uiLockPath,
+      ...targets,
+    ]) {
       snapshots.set(target, await readOptional(target))
     }
   }
@@ -494,6 +732,13 @@ export async function addUi(
         }
       }
       await pinUiDependency(project, lock.package.version, dependencies.runner ?? defaultUiRunner)
+      const theme = themes[0]
+      const themeTarget = theme?.files[0]?.target
+      if (themeTarget) {
+        const target = await safeTarget(project, themeTarget)
+        const css = (await readOptional(project.cssPath)) ?? ''
+        await writeFile(project.cssPath, activateTheme(css, themeImport(project, target)), 'utf8')
+      }
     }
   } catch (error) {
     for (const [target, previous] of snapshots) {
@@ -513,6 +758,15 @@ export async function addUi(
       })),
       command: [invocation.file, ...invocation.args],
       output: result.stdout,
+      activation: themes[0]
+        ? {
+            file: projectRelative(project, project.cssPath),
+            import: themeImport(
+              project,
+              targets.find((target) => target.endsWith('.css'))!,
+            ),
+          }
+        : undefined,
     }
   }
 
@@ -589,6 +843,15 @@ export async function doctorUi(
         checks.push({ check: 'item:' + item.address + ':' + file, ok: actual === expected })
       }
     }
+    const themeFiles = Object.values(lock.items)
+      .filter((item) => item.address.startsWith('theme/'))
+      .flatMap((item) => Object.keys(item.files).filter((file) => file.endsWith('.css')))
+    if (themeFiles.length > 0) {
+      const active = themeFiles.some((file) =>
+        css.includes(themeImport(project, path.join(project.root, file))),
+      )
+      checks.push({ check: 'theme-active', ok: active })
+    }
   }
   return { healthy: checks.every((check) => check.ok), checks }
 }
@@ -601,6 +864,7 @@ export async function applyPreset(
     throw new UiError('UI_ITEM_NOT_FOUND', 'Unknown preset: ' + preset)
   }
   const project = await discoverUiProject(options.project)
+  await assertSafePlannedTarget(project, UI_LOCK_FILE)
   const lock = await readUiLock(project.uiLockPath)
   const css = (await readOptional(project.cssPath)) ?? ''
   const next = css.replace(

package/src/ui/release.ts

@@ -237,10 +237,21 @@ function qualifyRegistryItemPaths(item: unknown, sourceDirectory: string): unkno
 function isInstallableItem(item: unknown): item is UiRegistry['items'][number] {
   if (!item || typeof item !== 'object') return false
   const candidate = item as Partial<UiRegistry['items'][number]>
-  return (
+  const address = candidate.meta?.canonicalAddress
+  const isTheme =
+    candidate.type === 'registry:theme' &&
     typeof candidate.name === 'string' &&
-    /^(?:pattern|block)-[a-z0-9-]+$/u.test(candidate.name) &&
+    /^theme-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(candidate.name) &&
+    typeof address === 'string' &&
+    /^theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(address)
+  const isComposition =
     candidate.type === 'registry:block' &&
+    typeof candidate.name === 'string' &&
+    /^(?:pattern|block)-[a-z0-9-]+$/u.test(candidate.name) &&
+    typeof address === 'string' &&
+    /^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(address)
+  return (
+    (isTheme || isComposition) &&
     (candidate.dependencies === undefined ||
       (Array.isArray(candidate.dependencies) &&
         candidate.dependencies.every(
@@ -258,10 +269,14 @@ function isInstallableItem(item: unknown): item is UiRegistry['items'][number] {
         typeof file.type === 'string' &&
         typeof file.target === 'string' &&
         file.target.startsWith('components/astrale/') &&
-        isSafeRelative(file.target),
+        isSafeRelative(file.target) &&
+        (!isTheme ||
+          (candidate.files?.length === 1 &&
+            file.type === 'registry:file' &&
+            file.target ===
+              'components/astrale/theme/' + address!.slice('theme/'.length) + '.css')),
     ) &&
-    typeof candidate.meta?.canonicalAddress === 'string' &&
-    /^(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+$/u.test(candidate.meta.canonicalAddress)
+    typeof address === 'string'
   )
 }
 

package/viewer/dist/index.html

@@ -32,6 +32,8 @@
         display: flex;
         gap: 12px;
         align-items: center;
+        min-width: 0;
+        overflow: hidden;
         padding: 6px 10px;
         border-bottom: 1px solid #26262e;
         flex: none;
@@ -56,6 +58,23 @@
         font-weight: 600;
         color: #e8e8f0;
       }
+      #view-label,
+      #target-label,
+      #identity-label {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      #view-label {
+        flex-shrink: 1;
+      }
+      #target-label {
+        flex-shrink: 2;
+      }
+      #identity-label {
+        flex-shrink: 3;
+      }
       .dim {
         color: #7a7a86;
       }
@@ -68,6 +87,8 @@
       }
       #frame {
         flex: 1;
+        min-width: 0;
+        min-height: 0;
         position: relative;
       }
       #frame iframe {