@astrale-os/cli 1.0.0-beta.14 → 1.0.0-beta.16

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.14",
+    version: "1.0.0-beta.16",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -83525,7 +83525,8 @@ async function discoverUiProject(input = process.cwd()) {
     lockPath,
     cssPath: path5.join(root, cssRelative),
     componentsPath,
-    uiLockPath: path5.join(root, "astrale-ui.lock.json")
+    uiLockPath: path5.join(root, "astrale-ui.lock.json"),
+    isAstraleDomain: await exists(path5.join(root, "astrale.config.ts")) && await exists(path5.join(root, "ui/index.ts")) && await exists(path5.join(root, "frontend/package.json"))
   };
 }
 function assertSupportedUiProject(project2) {
@@ -83655,7 +83656,10 @@ async function readRegistry(commit, fetcher) {
   return { name: root.name ?? "astrale-ui", homepage: root.homepage, items: installable };
 }
 async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited) {
-  const direct = Array.isArray(source2.items) ? source2.items : [];
+  const releaseRoot = RAW + "/" + commit + "/";
+  const sourceRelative = sourceUrl.slice(releaseRoot.length);
+  const sourceDirectory = sourceRelative.slice(0, Math.max(0, sourceRelative.lastIndexOf("/")));
+  const direct = Array.isArray(source2.items) ? source2.items.map((item) => qualifyRegistryItemPaths(item, sourceDirectory)) : [];
   const includes = source2.include ?? [];
   if (!Array.isArray(includes)) {
     throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry include must be an array.");
@@ -83664,12 +83668,12 @@ async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited
     throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains too many included documents.");
   }
   const nested = await Promise.all(includes.map(async (include) => {
-    if (typeof include !== "string" || include.startsWith("/") || !include.endsWith("registry.json") || include.split("/").includes("..")) {
+    if (typeof include !== "string" || !isSafeRelative2(include) || !/^[A-Za-z0-9._/-]+$/u.test(include) || !include.endsWith("registry.json") || include === "registry.json") {
       throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an unsafe include.");
     }
+    const sourceDirectoryUrl = sourceUrl.slice(0, sourceUrl.lastIndexOf("/") + 1);
     const url3 = new URL(include, sourceUrl).toString();
-    const releaseRoot = RAW + "/" + commit + "/";
-    if (!url3.startsWith(releaseRoot) || visited.has(url3)) {
+    if (url3 !== sourceDirectoryUrl + include || !url3.startsWith(releaseRoot) || !url3.startsWith(sourceDirectoryUrl) || visited.has(url3)) {
       throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry include escaped or repeated the release snapshot.");
     }
     visited.add(url3);
@@ -83678,6 +83682,33 @@ async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited
   }));
   return direct.concat(nested.flat());
 }
+function qualifyRegistryItemPaths(item, sourceDirectory) {
+  if (!item || typeof item !== "object")
+    return item;
+  const candidate2 = item;
+  if (!Array.isArray(candidate2.files))
+    return item;
+  return {
+    ...candidate2,
+    files: candidate2.files.map((file2) => {
+      if (!file2 || typeof file2 !== "object")
+        return file2;
+      const candidateFile = file2;
+      if (typeof candidateFile.path !== "string")
+        return file2;
+      if (!isSafeRelative2(candidateFile.path) || sourceDirectory !== "" && (candidateFile.path === sourceDirectory || candidateFile.path.startsWith(sourceDirectory + "/"))) {
+        throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an invalid installable item path.");
+      }
+      if (sourceDirectory === "")
+        return file2;
+      const qualified = sourceDirectory + "/" + candidateFile.path;
+      if (!isSafeRelative2(qualified)) {
+        throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an invalid installable item path.");
+      }
+      return { ...candidateFile, path: qualified };
+    })
+  };
+}
 function isInstallableItem(item) {
   if (!item || typeof item !== "object")
     return false;
@@ -83695,7 +83726,11 @@ async function readUiRegistryItem(release, expected, fetcher = fetch) {
   return item;
 }
 function isSafeRelative2(value3) {
-  return value3.length > 0 && !value3.startsWith("/") && !/^[A-Za-z]:[\\/]/u.test(value3) && !value3.includes("\\") && !value3.split("/").includes("..");
+  const segments = value3.split("/");
+  return value3.length > 0 && !value3.startsWith("/") && !/^[A-Za-z]:[\\/]/u.test(value3) && !value3.includes("\\") && !/[?#%]/u.test(value3) && ![...value3].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 31 || code === 127;
+  }) && segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 function registryItemUrl(release, itemName) {
   return RAW + "/" + release.commit + "/registry/public/r/" + encodeURIComponent(itemName) + ".json";
@@ -83734,6 +83769,108 @@ async function readOptional(target2) {
 function manifestDependencies(manifest) {
   return { ...manifest.dependencies };
 }
+function domainRegistryPackagePath(project2) {
+  return path6.join(project2.root, "components/package.json");
+}
+function pnpmWorkspacePath(project2) {
+  return path6.join(project2.root, "pnpm-workspace.yaml");
+}
+function domainRegistryPackageName(manifest) {
+  const name = typeof manifest.name === "string" ? manifest.name : "astrale-domain";
+  return name + "-ui-registry";
+}
+function appendWorkspace(manifest, workspace) {
+  const configured = manifest.workspaces;
+  if (configured === undefined) {
+    manifest.workspaces = [workspace];
+    return;
+  }
+  if (Array.isArray(configured) && configured.every((value3) => typeof value3 === "string")) {
+    if (!configured.includes(workspace))
+      manifest.workspaces = [...configured, workspace];
+    return;
+  }
+  if (configured && typeof configured === "object") {
+    const candidate2 = configured;
+    if (Array.isArray(candidate2.packages) && candidate2.packages.every((value3) => typeof value3 === "string")) {
+      if (!candidate2.packages.includes(workspace)) {
+        manifest.workspaces = { ...candidate2, packages: [...candidate2.packages, workspace] };
+      }
+      return;
+    }
+  }
+  throw new UiError("UI_PROJECT_UNSUPPORTED", "package.json has an invalid workspaces field.");
+}
+async function appendPnpmWorkspace(project2, workspace) {
+  const target2 = pnpmWorkspacePath(project2);
+  const source2 = await readOptional(target2);
+  if (source2 === undefined) {
+    await writeFile6(target2, `packages:
+  - '` + workspace + `'
+`, "utf8");
+    return;
+  }
+  const document = $parseDocument(source2);
+  if (document.errors.length > 0) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml is not valid YAML.");
+  }
+  const packages = document.get("packages", true);
+  if (!$isSeq(packages)) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml must declare a packages sequence.");
+  }
+  const values = packages.toJSON();
+  if (!Array.isArray(values) || !values.every((value3) => typeof value3 === "string")) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml must declare a packages sequence.");
+  }
+  if (!values.includes(workspace))
+    packages.add(workspace);
+  await writeFile6(target2, String(document), "utf8");
+}
+async function hasDomainRegistryWorkspace(project2) {
+  if (!project2.isAstraleDomain || !await exists2(domainRegistryPackagePath(project2)))
+    return false;
+  const registryManifest = JSON.parse(await readFile18(domainRegistryPackagePath(project2), "utf8"));
+  if (registryManifest.private !== true || typeof registryManifest.name !== "string" || registryManifest.name === UI_PACKAGE || registryManifest.name === project2.packageJson.name) {
+    return false;
+  }
+  if (project2.manager === "pnpm") {
+    const source2 = await readOptional(pnpmWorkspacePath(project2));
+    if (source2 === undefined)
+      return false;
+    const document = $parseDocument(source2);
+    if (document.errors.length > 0)
+      return false;
+    const packages = document.get("packages", true);
+    const values = $isSeq(packages) ? packages.toJSON() : undefined;
+    return Array.isArray(values) && values.includes("components");
+  }
+  const configured = project2.packageJson.workspaces;
+  const workspaces = Array.isArray(configured) ? configured : configured && typeof configured === "object" ? configured.packages : undefined;
+  return Array.isArray(workspaces) && workspaces.includes("components");
+}
+async function writeDomainRegistryWorkspace(project2, manifest) {
+  if (!project2.isAstraleDomain)
+    return;
+  if (project2.manager === "pnpm")
+    await appendPnpmWorkspace(project2, "components");
+  else
+    appendWorkspace(manifest, "components");
+  const target2 = domainRegistryPackagePath(project2);
+  const existing = await readOptional(target2);
+  const registryManifest = existing ? JSON.parse(existing) : { name: domainRegistryPackageName(manifest) };
+  if (registryManifest.private === false) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "The Astrale registry source workspace must remain private.");
+  }
+  if (registryManifest.name === UI_PACKAGE || registryManifest.name === manifest.name || registryManifest.name !== undefined && typeof registryManifest.name !== "string") {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "The Astrale registry source workspace must have a distinct package name.");
+  }
+  await writeJson(target2, {
+    ...registryManifest,
+    name: registryManifest.name ?? domainRegistryPackageName(manifest),
+    private: true,
+    type: registryManifest.type ?? "module"
+  });
+}
 async function initUi(options, dependencies = {}) {
   const project2 = await discoverUiProject(options.path);
   assertSupportedUiProject(project2);
@@ -83748,7 +83885,7 @@ async function initUi(options, dependencies = {}) {
       return;
     });
     const requestedVersion = options.version?.replace(/^v/u, "");
-    const desired = (!requestedVersion || requestedVersion === lock.package.version) && (!options.preset || options.preset === lock.preset) && css.includes(UI_PACKAGE + "/theme.css") && css.includes(UI_PACKAGE + "/presets/" + lock.preset + ".css") && components?.style === "base-nova";
+    const desired = (!requestedVersion || requestedVersion === lock.package.version) && (!options.preset || options.preset === lock.preset) && css.includes(UI_PACKAGE + "/theme.css") && css.includes(UI_PACKAGE + "/presets/" + lock.preset + ".css") && components?.style === "base-nova" && (!project2.isAstraleDomain || await hasDomainRegistryWorkspace(project2));
     if (!desired) {
       throw new UiError("UI_ITEM_CONFLICT", "Existing Astrale UI initialization differs from the requested state.", "Run astrale ui doctor, then repeat init with --force after reviewing the changes.");
     }
@@ -83767,6 +83904,8 @@ async function initUi(options, dependencies = {}) {
       cssRelative,
       "components.json",
       "astrale-ui.lock.json",
+      ...project2.isAstraleDomain ? ["components/package.json"] : [],
+      ...project2.isAstraleDomain && project2.manager === "pnpm" ? ["pnpm-workspace.yaml"] : [],
       ...project2.lockPath ? [projectRelative(project2, project2.lockPath)] : []
     ],
     tooling: {
@@ -83778,11 +83917,19 @@ async function initUi(options, dependencies = {}) {
   };
   if (options.dryRun)
     return plan;
+  if (project2.isAstraleDomain) {
+    await assertSafePlannedTarget(project2, "components/package.json");
+    if (project2.manager === "pnpm") {
+      await assertSafePlannedTarget(project2, "pnpm-workspace.yaml");
+    }
+  }
   const mutationPaths = [
     project2.packageJsonPath,
     project2.cssPath,
     project2.componentsPath,
     project2.uiLockPath,
+    ...project2.isAstraleDomain ? [domainRegistryPackagePath(project2)] : [],
+    ...project2.isAstraleDomain && project2.manager === "pnpm" ? [pnpmWorkspacePath(project2)] : [],
     ...project2.lockPath ? [project2.lockPath] : []
   ];
   const snapshots = new Map;
@@ -83794,6 +83941,7 @@ async function initUi(options, dependencies = {}) {
       ...manifestDependencies(manifest),
       [UI_PACKAGE]: release.version
     };
+    await writeDomainRegistryWorkspace(project2, manifest);
     await writeJson(project2.packageJsonPath, manifest);
     const currentCss = await readOptional(project2.cssPath) ?? "";
     const imports = [
@@ -83866,6 +84014,17 @@ async function initUi(options, dependencies = {}) {
     throw error52;
   }
 }
+async function pinUiDependency(project2, version2, runner) {
+  const manifest = JSON.parse(await readFile18(project2.packageJsonPath, "utf8"));
+  if (manifestDependencies(manifest)[UI_PACKAGE] === version2)
+    return;
+  manifest.dependencies = { ...manifestDependencies(manifest), [UI_PACKAGE]: version2 };
+  await writeJson(project2.packageJsonPath, manifest);
+  const result = await runner(project2.manager, ["install"], project2.root);
+  if (result.code !== 0) {
+    throw new UiError("UI_DEPENDENCY_INSTALL_FAILED", project2.manager + " install failed while restoring the locked UI release.", result.stderr.trim() || undefined);
+  }
+}
 async function listUi(query4, options, dependencies = {}) {
   const release = await resolveUiRelease(options.version, dependencies.fetcher);
   const needle = query4?.trim().toLowerCase();
@@ -83931,6 +84090,7 @@ async function addUi(addresses, options, dependencies = {}) {
           throw new UiError("UI_TOOL_FAILED", "The pinned shadcn operation omitted an item file.");
         }
       }
+      await pinUiDependency(project2, lock.package.version, dependencies.runner ?? defaultUiRunner);
     }
   } catch (error52) {
     for (const [target2, previous] of snapshots) {
@@ -84114,6 +84274,7 @@ async function writeJson(target2, value3) {
 `, "utf8");
 }
 var init_operations3 = __esm(() => {
+  init_dist();
   init_lock();
   init_model7();
   init_project3();

package/package.json

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

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

@@ -135,7 +135,14 @@ function mockFetch(seen: string[] = []): typeof fetch {
       })
     }
     if (url.endsWith('/registry/patterns/chart/registry.json')) {
-      return Response.json({ items: [item] })
+      return Response.json({
+        items: [
+          {
+            ...item,
+            files: item.files.map((file) => ({ ...file, path: 'line-basic.tsx' })),
+          },
+        ],
+      })
     }
     if (url.endsWith('/registry.json')) {
       return Response.json({ include: ['registry/patterns/chart/registry.json'] })

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

@@ -19,7 +19,7 @@ const registry: UiRegistry = {
       description: 'A controlled chart.',
       files: [
         {
-          path: 'registry/patterns/chart/line-basic.tsx',
+          path: 'line-basic.tsx',
           type: 'registry:component',
           target: 'components/astrale/pattern/chart/line-basic.tsx',
         },
@@ -79,6 +79,7 @@ function builtItem(item: UiRegistry['items'][number]) {
     ...item,
     files: item.files.map((file, index) => ({
       ...file,
+      path: `registry/patterns/chart/${file.path}`,
       content: index === 0 ? 'export const Chart = true\n' : 'export const Summary = true\n',
     })),
   }
@@ -93,7 +94,11 @@ async function fixture(): Promise<string> {
     JSON.stringify({
       name: 'fixture',
       private: true,
-      dependencies: { react: '19.2.8', 'react-dom': '19.2.8', tailwindcss: '4.3.3' },
+      dependencies: {
+        react: '19.2.8',
+        'react-dom': '19.2.8',
+        tailwindcss: '4.3.3',
+      },
       packageManager: 'pnpm@11.13.1',
     }),
   )
@@ -101,6 +106,16 @@ async function fixture(): Promise<string> {
   return root
 }
 
+async function lockedFixture(): Promise<string> {
+  const root = await fixture()
+  const manifestPath = path.join(root, 'package.json')
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  manifest.dependencies['@astrale-os/ui'] = '0.3.0-beta.0'
+  await writeFile(manifestPath, JSON.stringify(manifest))
+  await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+  return root
+}
+
 function lock(): UiLock {
   return {
     $schema: 'https://example.invalid/ui-lock.schema.json',
@@ -152,6 +167,7 @@ describe('UI release and runner contracts', () => {
     expect(release.commit).toBe(commit)
     expect(release.compatibility.base).toBe('base')
     expect(release.registry.items).toHaveLength(1)
+    expect(release.registry.items[0]?.files[0]?.path).toBe('registry/patterns/chart/line-basic.tsx')
     expect(seen.filter((url) => new URL(url).hostname === 'raw.githubusercontent.com')).toEqual(
       expect.arrayContaining([
         expect.stringContaining('/' + commit + '/tooling/compatibility.json'),
@@ -193,6 +209,114 @@ describe('UI release and runner contracts', () => {
     expect(seen.some((url) => url.endsWith('/registry/registry.json'))).toBe(false)
   })
 
+  test('rejects noncanonical and encoded registry includes before fetching them', async () => {
+    const unsafeIncludes = [
+      '%2e%2e/other/registry.json',
+      'registry/%2Fother/registry.json',
+      'registry/other/registry.json?raw=1',
+      'registry/other/registry.json#item',
+      'https://example.invalid/registry.json',
+      './registry/other/registry.json',
+    ]
+
+    for (const include of unsafeIncludes) {
+      const seen: string[] = []
+      const fallback = mockFetch(seen)
+      const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+        const url = String(input)
+        if (url.endsWith('/' + commit + '/registry.json')) {
+          return Response.json({ include: [include] })
+        }
+        return fallback(input, init)
+      }) as typeof fetch
+
+      await expect(resolveUiRelease('0.3.0-beta.0', fetcher)).rejects.toMatchObject({
+        code: 'UI_REGISTRY_UNAVAILABLE',
+      })
+      expect(seen.some((url) => url.includes('example.invalid') || url.includes('/other/'))).toBe(
+        false,
+      )
+    }
+  })
+
+  test('rejects malformed and already-qualified family-local item paths', async () => {
+    const unsafePaths = [
+      '',
+      '/absolute.tsx',
+      'C:/windows.tsx',
+      './line-basic.tsx',
+      '../line-basic.tsx',
+      '%2e%2e/line-basic.tsx',
+      'registry/patterns/chart/line-basic.tsx',
+    ]
+
+    for (const unsafePath of unsafePaths) {
+      const supplied = structuredClone(registry)
+      supplied.items[0]!.files[0]!.path = unsafePath
+      await expect(resolveUiRelease('0.3.0-beta.0', mockFetch([], supplied))).rejects.toMatchObject(
+        {
+          code: 'UI_REGISTRY_UNAVAILABLE',
+        },
+      )
+    }
+  })
+
+  test('qualifies every item file relative to its declaring nested registry', async () => {
+    const rootItem = {
+      ...structuredClone(registry.items[0]!),
+      name: 'pattern-chart-root',
+      files: [
+        {
+          ...structuredClone(registry.items[0]!.files[0]!),
+          path: 'registry/root.tsx',
+          target: 'components/astrale/pattern/chart/root.tsx',
+        },
+      ],
+      meta: { canonicalAddress: 'pattern/chart/root' },
+    }
+    const chartItem = {
+      ...structuredClone(registry.items[0]!),
+      files: [
+        structuredClone(registry.items[0]!.files[0]!),
+        {
+          ...structuredClone(registry.items[0]!.files[0]!),
+          path: 'parts/legend.tsx',
+          target: 'components/astrale/pattern/chart/parts/legend.tsx',
+        },
+      ],
+    }
+    const nestedItem = {
+      ...structuredClone(registry.items[0]!),
+      name: 'pattern-chart-nested-line',
+      files: [structuredClone(registry.items[0]!.files[0]!)],
+      meta: { canonicalAddress: 'pattern/chart/nested-line' },
+    }
+    const fallback = mockFetch()
+    const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input)
+      if (url.endsWith('/' + commit + '/registry.json')) {
+        return Response.json({
+          items: [rootItem],
+          include: ['registry/patterns/chart/registry.json'],
+        })
+      }
+      if (url.endsWith('/registry/patterns/chart/registry.json')) {
+        return Response.json({ items: [chartItem], include: ['nested/registry.json'] })
+      }
+      if (url.endsWith('/registry/patterns/chart/nested/registry.json')) {
+        return Response.json({ items: [nestedItem] })
+      }
+      return fallback(input, init)
+    }) as typeof fetch
+
+    const release = await resolveUiRelease('0.3.0-beta.0', fetcher)
+    expect(release.registry.items.map((item) => item.files.map((file) => file.path))).toEqual([
+      ['registry/root.tsx'],
+      ['registry/patterns/chart/line-basic.tsx', 'registry/patterns/chart/parts/legend.tsx'],
+      ['registry/patterns/chart/nested/line-basic.tsx'],
+    ])
+  })
+
   /** @evidence TEST-CLI-UI-BOUNDED-REMOTE-DOCUMENTS */
   test('bounds and normalizes malformed registry responses', async () => {
     const fallback = mockFetch()
@@ -250,6 +374,10 @@ describe('UI initialization transaction', () => {
       JSON.stringify({ name: 'astrale-frontend', private: true, type: 'module' }),
     )
     await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
     const rootCssBefore = await readFile(path.join(root, 'src/index.css'), 'utf8')
 
     await initUi(
@@ -265,8 +393,14 @@ describe('UI initialization transaction', () => {
     expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toBe(rootCssBefore)
     expect(
       JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).dependencies,
-    ).toHaveProperty('@astrale-os/ui')
+    ).toHaveProperty('@astrale-os/ui', '0.3.0-beta.0')
     expect(await Bun.file(path.join(root, 'src/astrale-ui.css')).exists()).toBe(false)
+    expect(JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8'))).toEqual({
+      name: 'fixture-ui-registry',
+      private: true,
+      type: 'module',
+    })
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toContain('components')
 
     await writeFile(path.join(root, 'src/app.css'), '/* later root stylesheet */\n')
     const repeated = await initUi(
@@ -276,6 +410,153 @@ describe('UI initialization transaction', () => {
     expect(repeated.status).toBe('unchanged')
   })
 
+  test('adds the private registry workspace to an npm-authored Domain manifest', async () => {
+    const root = await fixture()
+    const manifestPath = path.join(root, 'package.json')
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    manifest.packageManager = 'npm@11.16.0'
+    manifest.workspaces = ['frontend']
+    await writeFile(manifestPath, JSON.stringify(manifest))
+    await writeFile(path.join(root, 'package-lock.json'), '{}')
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+
+    const result = await initUi(
+      { path: root, version: '0.3.0-beta.0', install: false },
+      { fetcher: mockFetch() },
+    )
+
+    expect(result.files).toEqual(expect.arrayContaining(['components/package.json']))
+    expect(JSON.parse(await readFile(manifestPath, 'utf8')).workspaces).toEqual([
+      'frontend',
+      'components',
+    ])
+    expect(JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8'))).toEqual({
+      name: 'fixture-ui-registry',
+      private: true,
+      type: 'module',
+    })
+  })
+
+  test('rejects a Domain registry workspace whose physical parent escapes the project', async () => {
+    const root = await fixture()
+    const outside = await fixture()
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await symlink(outside, path.join(root, 'components'), 'dir')
+    const outsideManifest = await readFile(path.join(outside, 'package.json'), 'utf8')
+    const rootManifest = await readFile(path.join(root, 'package.json'), 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_LOCK_INVALID' })
+    expect(await readFile(path.join(outside, 'package.json'), 'utf8')).toBe(outsideManifest)
+    expect(await readFile(path.join(root, 'package.json'), 'utf8')).toBe(rootManifest)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+  })
+
+  test('rejects a symlinked pnpm workspace manifest before any Domain mutation', async () => {
+    const root = await fixture()
+    const outside = await fixture()
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    const outsideWorkspace = path.join(outside, 'workspace.yaml')
+    await writeFile(outsideWorkspace, "packages:\n  - 'outside'\n")
+    await symlink(outsideWorkspace, path.join(root, 'pnpm-workspace.yaml'), 'file')
+    const outsideBefore = await readFile(outsideWorkspace, 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_LOCK_INVALID' })
+    expect(await readFile(outsideWorkspace, 'utf8')).toBe(outsideBefore)
+    expect(await Bun.file(path.join(root, 'components/package.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+  })
+
+  test('restores every Domain workspace mutation when dependency installation fails', async () => {
+    const root = await fixture()
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
+    const manifestBefore = await readFile(path.join(root, 'package.json'), 'utf8')
+    const cssBefore = await readFile(path.join(root, 'frontend/src/styles.css'), 'utf8')
+    const workspaceBefore = await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')
+
+    await expect(
+      initUi(
+        { path: root, version: '0.3.0-beta.0' },
+        {
+          fetcher: mockFetch(),
+          runner: async () => ({ code: 1, stdout: '', stderr: 'install failed' }),
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_DEPENDENCY_INSTALL_FAILED' })
+
+    expect(await readFile(path.join(root, 'package.json'), 'utf8')).toBe(manifestBefore)
+    expect(await readFile(path.join(root, 'frontend/src/styles.css'), 'utf8')).toBe(cssBefore)
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toBe(workspaceBefore)
+    expect(await Bun.file(path.join(root, 'components/package.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'components.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'pnpm-lock.yaml')).exists()).toBe(false)
+  })
+
+  test('rejects a registry workspace that could shadow the public UI package', async () => {
+    const root = await fixture()
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
+    await mkdir(path.join(root, 'components'), { recursive: true })
+    await writeFile(
+      path.join(root, 'components/package.json'),
+      JSON.stringify({ name: '@astrale-os/ui', private: true, version: '0.3.0-beta.0' }),
+    )
+    const workspaceBefore = await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toBe(workspaceBefore)
+    expect(
+      JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8')).name,
+    ).toBe('@astrale-os/ui')
+  })
+
   test('rejects configured and discovered stylesheets whose physical parent escapes', async () => {
     const root = await fixture()
     const outside = await fixture()
@@ -416,8 +697,7 @@ describe('UI source operations', () => {
   })
 
   test('add dry-run invokes the exact shadcn version and does not advance the lock', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const before = await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8')
     const calls: Array<{ file: string; args: string[] }> = []
     const result = await addUi(
@@ -445,8 +725,7 @@ describe('UI source operations', () => {
   })
 
   test('successful add records installed file digests and doctor detects later edits', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     await writeFile(
       path.join(root, 'components.json'),
       JSON.stringify({ style: 'base-nova', tailwind: { css: 'src/index.css' } }),
@@ -499,9 +778,80 @@ describe('UI source operations', () => {
     ).rejects.toBeInstanceOf(UiError)
   })
 
+  test('restores the exact locked UI dependency after shadcn applies its compatible range', async () => {
+    const root = await lockedFixture()
+    const installed = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
+    const calls: Array<{ file: string; args: string[] }> = []
+
+    await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async (file, args) => {
+          calls.push({ file, args })
+          if (args[0] === 'dlx') {
+            await mkdir(path.dirname(installed), { recursive: true })
+            await writeFile(installed, 'export const Chart = true\n')
+            const manifestPath = path.join(root, 'package.json')
+            const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+            manifest.dependencies['@astrale-os/ui'] = '^0.3.0-beta.0'
+            await writeFile(manifestPath, JSON.stringify(manifest))
+          }
+          return { code: 0, stdout: '', stderr: '' }
+        },
+      },
+    )
+
+    expect(calls).toEqual([
+      expect.objectContaining({ file: 'pnpm', args: expect.arrayContaining(['dlx']) }),
+      { file: 'pnpm', args: ['install'] },
+    ])
+    expect(
+      JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).dependencies[
+        '@astrale-os/ui'
+      ],
+    ).toBe('0.3.0-beta.0')
+  })
+
+  test('rolls back item and package state when restoring the locked dependency fails', async () => {
+    const root = await lockedFixture()
+    const manifestPath = path.join(root, 'package.json')
+    const lockPath = path.join(root, 'astrale-ui.lock.json')
+    const installed = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
+    const manifestBefore = await readFile(manifestPath, 'utf8')
+    const lockBefore = await readFile(lockPath, 'utf8')
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async (_file, args) => {
+            if (args[0] === 'dlx') {
+              await mkdir(path.dirname(installed), { recursive: true })
+              await writeFile(installed, 'export const Chart = true\n')
+              const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+              manifest.dependencies['@astrale-os/ui'] = '^0.3.0-beta.0'
+              await writeFile(manifestPath, JSON.stringify(manifest))
+              return { code: 0, stdout: '', stderr: '' }
+            }
+            await writeFile(path.join(root, 'pnpm-lock.yaml'), 'partial lock\n')
+            return { code: 1, stdout: '', stderr: 'registry timeout' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_DEPENDENCY_INSTALL_FAILED' })
+
+    expect(await readFile(manifestPath, 'utf8')).toBe(manifestBefore)
+    expect(await readFile(lockPath, 'utf8')).toBe(lockBefore)
+    expect(await Bun.file(installed).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'pnpm-lock.yaml')).exists()).toBe(false)
+  })
+
   test('preflights symlink targets without invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const outside = await mkdtemp(path.join(tmpdir(), 'astrale-ui-outside-'))
     temporary.push(outside)
     await symlink(outside, path.join(root, 'components'))
@@ -523,8 +873,7 @@ describe('UI source operations', () => {
   })
 
   test('restores declared files and package state after a partial shadcn failure', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const first = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
     const second = path.join(root, 'components/astrale/pattern/chart/summary.tsx')
     await mkdir(path.dirname(first), { recursive: true })
@@ -537,7 +886,7 @@ describe('UI source operations', () => {
           files: [
             registry.items[0]!.files[0]!,
             {
-              path: 'registry/patterns/chart/summary.tsx',
+              path: 'summary.tsx',
               type: 'registry:component',
               target: 'components/astrale/pattern/chart/summary.tsx',
             },
@@ -566,8 +915,7 @@ describe('UI source operations', () => {
   })
 
   test('overwrite requires explicit yes confirmation before invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     let invoked = false
     await expect(
       addUi(
@@ -587,8 +935,7 @@ describe('UI source operations', () => {
 
   /** @evidence TEST-CLI-UI-EXACT-ITEM-SOURCE */
   test('rejects a built item that differs from the admitted release index before invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const fallback = mockFetch()
     let invoked = false
     const malformed = (async (input: string | URL | Request, init?: RequestInit) => {

package/src/ui/operations.ts

@@ -1,5 +1,6 @@
 import { access, lstat, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import { isSeq, parseDocument } from 'yaml'
 
 import { digest, parseUiLock, readUiLock } from './lock'
 import {
@@ -42,6 +43,140 @@ function manifestDependencies(manifest: Record<string, unknown>): Record<string,
   return { ...(manifest.dependencies as Record<string, string> | undefined) }
 }
 
+function domainRegistryPackagePath(project: UiProject): string {
+  return path.join(project.root, 'components/package.json')
+}
+
+function pnpmWorkspacePath(project: UiProject): string {
+  return path.join(project.root, 'pnpm-workspace.yaml')
+}
+
+function domainRegistryPackageName(manifest: Record<string, unknown>): string {
+  const name = typeof manifest.name === 'string' ? manifest.name : 'astrale-domain'
+  return name + '-ui-registry'
+}
+
+function appendWorkspace(manifest: Record<string, unknown>, workspace: string): void {
+  const configured = manifest.workspaces
+  if (configured === undefined) {
+    manifest.workspaces = [workspace]
+    return
+  }
+  if (Array.isArray(configured) && configured.every((value) => typeof value === 'string')) {
+    if (!configured.includes(workspace)) manifest.workspaces = [...configured, workspace]
+    return
+  }
+  if (configured && typeof configured === 'object') {
+    const candidate = configured as { packages?: unknown }
+    if (
+      Array.isArray(candidate.packages) &&
+      candidate.packages.every((value) => typeof value === 'string')
+    ) {
+      if (!candidate.packages.includes(workspace)) {
+        manifest.workspaces = { ...candidate, packages: [...candidate.packages, workspace] }
+      }
+      return
+    }
+  }
+  throw new UiError('UI_PROJECT_UNSUPPORTED', 'package.json has an invalid workspaces field.')
+}
+
+async function appendPnpmWorkspace(project: UiProject, workspace: string): Promise<void> {
+  const target = pnpmWorkspacePath(project)
+  const source = await readOptional(target)
+  if (source === undefined) {
+    await writeFile(target, "packages:\n  - '" + workspace + "'\n", 'utf8')
+    return
+  }
+  const document = parseDocument(source)
+  if (document.errors.length > 0) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'pnpm-workspace.yaml is not valid YAML.')
+  }
+  const packages = document.get('packages', true)
+  if (!isSeq(packages)) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'pnpm-workspace.yaml must declare a packages sequence.',
+    )
+  }
+  const values = packages.toJSON()
+  if (!Array.isArray(values) || !values.every((value) => typeof value === 'string')) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'pnpm-workspace.yaml must declare a packages sequence.',
+    )
+  }
+  if (!values.includes(workspace)) packages.add(workspace)
+  await writeFile(target, String(document), 'utf8')
+}
+
+async function hasDomainRegistryWorkspace(project: UiProject): Promise<boolean> {
+  if (!project.isAstraleDomain || !(await exists(domainRegistryPackagePath(project)))) return false
+  const registryManifest = JSON.parse(
+    await readFile(domainRegistryPackagePath(project), 'utf8'),
+  ) as Record<string, unknown>
+  if (
+    registryManifest.private !== true ||
+    typeof registryManifest.name !== 'string' ||
+    registryManifest.name === UI_PACKAGE ||
+    registryManifest.name === project.packageJson.name
+  ) {
+    return false
+  }
+  if (project.manager === 'pnpm') {
+    const source = await readOptional(pnpmWorkspacePath(project))
+    if (source === undefined) return false
+    const document = parseDocument(source)
+    if (document.errors.length > 0) return false
+    const packages = document.get('packages', true)
+    const values = isSeq(packages) ? packages.toJSON() : undefined
+    return Array.isArray(values) && values.includes('components')
+  }
+  const configured = project.packageJson.workspaces
+  const workspaces = Array.isArray(configured)
+    ? configured
+    : configured && typeof configured === 'object'
+      ? (configured as { packages?: unknown }).packages
+      : undefined
+  return Array.isArray(workspaces) && workspaces.includes('components')
+}
+
+async function writeDomainRegistryWorkspace(
+  project: UiProject,
+  manifest: Record<string, unknown>,
+): Promise<void> {
+  if (!project.isAstraleDomain) return
+  if (project.manager === 'pnpm') await appendPnpmWorkspace(project, 'components')
+  else appendWorkspace(manifest, 'components')
+  const target = domainRegistryPackagePath(project)
+  const existing = await readOptional(target)
+  const registryManifest = existing
+    ? (JSON.parse(existing) as Record<string, unknown>)
+    : { name: domainRegistryPackageName(manifest) }
+  if (registryManifest.private === false) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The Astrale registry source workspace must remain private.',
+    )
+  }
+  if (
+    registryManifest.name === UI_PACKAGE ||
+    registryManifest.name === manifest.name ||
+    (registryManifest.name !== undefined && typeof registryManifest.name !== 'string')
+  ) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The Astrale registry source workspace must have a distinct package name.',
+    )
+  }
+  await writeJson(target, {
+    ...registryManifest,
+    name: registryManifest.name ?? domainRegistryPackageName(manifest),
+    private: true,
+    type: registryManifest.type ?? 'module',
+  })
+}
+
 export type InitUiOptions = {
   path?: string
   preset?: UiPreset
@@ -73,7 +208,8 @@ export async function initUi(
       (!options.preset || options.preset === lock.preset) &&
       css.includes(UI_PACKAGE + '/theme.css') &&
       css.includes(UI_PACKAGE + '/presets/' + lock.preset + '.css') &&
-      components?.style === 'base-nova'
+      components?.style === 'base-nova' &&
+      (!project.isAstraleDomain || (await hasDomainRegistryWorkspace(project)))
     if (!desired) {
       throw new UiError(
         'UI_ITEM_CONFLICT',
@@ -96,6 +232,8 @@ export async function initUi(
       cssRelative,
       'components.json',
       'astrale-ui.lock.json',
+      ...(project.isAstraleDomain ? ['components/package.json'] : []),
+      ...(project.isAstraleDomain && project.manager === 'pnpm' ? ['pnpm-workspace.yaml'] : []),
       ...(project.lockPath ? [projectRelative(project, project.lockPath)] : []),
     ],
     tooling: {
@@ -107,11 +245,20 @@ export async function initUi(
   }
   if (options.dryRun) return plan
 
+  if (project.isAstraleDomain) {
+    await assertSafePlannedTarget(project, 'components/package.json')
+    if (project.manager === 'pnpm') {
+      await assertSafePlannedTarget(project, 'pnpm-workspace.yaml')
+    }
+  }
+
   const mutationPaths = [
     project.packageJsonPath,
     project.cssPath,
     project.componentsPath,
     project.uiLockPath,
+    ...(project.isAstraleDomain ? [domainRegistryPackagePath(project)] : []),
+    ...(project.isAstraleDomain && project.manager === 'pnpm' ? [pnpmWorkspacePath(project)] : []),
     ...(project.lockPath ? [project.lockPath] : []),
   ]
   const snapshots = new Map<string, string | undefined>()
@@ -123,6 +270,7 @@ export async function initUi(
       ...manifestDependencies(manifest),
       [UI_PACKAGE]: release.version,
     }
+    await writeDomainRegistryWorkspace(project, manifest)
     await writeJson(project.packageJsonPath, manifest)
 
     const currentCss = (await readOptional(project.cssPath)) ?? ''
@@ -214,6 +362,28 @@ export async function initUi(
   }
 }
 
+async function pinUiDependency(
+  project: UiProject,
+  version: string,
+  runner: UiRunner,
+): Promise<void> {
+  const manifest = JSON.parse(await readFile(project.packageJsonPath, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  if (manifestDependencies(manifest)[UI_PACKAGE] === version) return
+  manifest.dependencies = { ...manifestDependencies(manifest), [UI_PACKAGE]: version }
+  await writeJson(project.packageJsonPath, manifest)
+  const result = await runner(project.manager, ['install'], project.root)
+  if (result.code !== 0) {
+    throw new UiError(
+      'UI_DEPENDENCY_INSTALL_FAILED',
+      project.manager + ' install failed while restoring the locked UI release.',
+      result.stderr.trim() || undefined,
+    )
+  }
+}
+
 export async function listUi(
   query: string | undefined,
   options: { type?: string; limit?: number; version?: string },
@@ -323,6 +493,7 @@ export async function addUi(
           throw new UiError('UI_TOOL_FAILED', 'The pinned shadcn operation omitted an item file.')
         }
       }
+      await pinUiDependency(project, lock.package.version, dependencies.runner ?? defaultUiRunner)
     }
   } catch (error) {
     for (const [target, previous] of snapshots) {

package/src/ui/project.ts

@@ -12,6 +12,7 @@ export type UiProject = {
   cssPath: string
   componentsPath: string
   uiLockPath: string
+  isAstraleDomain: boolean
 }
 
 const MANAGERS: readonly [string, PackageManager][] = [
@@ -173,6 +174,10 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
     cssPath: path.join(root, cssRelative),
     componentsPath,
     uiLockPath: path.join(root, 'astrale-ui.lock.json'),
+    isAstraleDomain:
+      (await exists(path.join(root, 'astrale.config.ts'))) &&
+      (await exists(path.join(root, 'ui/index.ts'))) &&
+      (await exists(path.join(root, 'frontend/package.json'))),
   }
 }
 

package/src/ui/release.ts

@@ -152,7 +152,12 @@ async function resolveRegistryItems(
   fetcher: Fetch,
   visited: Set<string>,
 ): Promise<unknown[]> {
-  const direct = Array.isArray(source.items) ? source.items : []
+  const releaseRoot = RAW + '/' + commit + '/'
+  const sourceRelative = sourceUrl.slice(releaseRoot.length)
+  const sourceDirectory = sourceRelative.slice(0, Math.max(0, sourceRelative.lastIndexOf('/')))
+  const direct = Array.isArray(source.items)
+    ? source.items.map((item) => qualifyRegistryItemPaths(item, sourceDirectory))
+    : []
   const includes = source.include ?? []
   if (!Array.isArray(includes)) {
     throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI registry include must be an array.')
@@ -167,15 +172,21 @@ async function resolveRegistryItems(
     includes.map(async (include) => {
       if (
         typeof include !== 'string' ||
-        include.startsWith('/') ||
+        !isSafeRelative(include) ||
+        !/^[A-Za-z0-9._/-]+$/u.test(include) ||
         !include.endsWith('registry.json') ||
-        include.split('/').includes('..')
+        include === 'registry.json'
       ) {
         throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI registry contains an unsafe include.')
       }
+      const sourceDirectoryUrl = sourceUrl.slice(0, sourceUrl.lastIndexOf('/') + 1)
       const url = new URL(include, sourceUrl).toString()
-      const releaseRoot = RAW + '/' + commit + '/'
-      if (!url.startsWith(releaseRoot) || visited.has(url)) {
+      if (
+        url !== sourceDirectoryUrl + include ||
+        !url.startsWith(releaseRoot) ||
+        !url.startsWith(sourceDirectoryUrl) ||
+        visited.has(url)
+      ) {
         throw new UiError(
           'UI_REGISTRY_UNAVAILABLE',
           'UI registry include escaped or repeated the release snapshot.',
@@ -189,6 +200,40 @@ async function resolveRegistryItems(
   return direct.concat(nested.flat())
 }
 
+function qualifyRegistryItemPaths(item: unknown, sourceDirectory: string): unknown {
+  if (!item || typeof item !== 'object') return item
+  const candidate = item as { files?: unknown }
+  if (!Array.isArray(candidate.files)) return item
+  return {
+    ...candidate,
+    files: candidate.files.map((file) => {
+      if (!file || typeof file !== 'object') return file
+      const candidateFile = file as { path?: unknown }
+      if (typeof candidateFile.path !== 'string') return file
+      if (
+        !isSafeRelative(candidateFile.path) ||
+        (sourceDirectory !== '' &&
+          (candidateFile.path === sourceDirectory ||
+            candidateFile.path.startsWith(sourceDirectory + '/')))
+      ) {
+        throw new UiError(
+          'UI_REGISTRY_UNAVAILABLE',
+          'UI registry contains an invalid installable item path.',
+        )
+      }
+      if (sourceDirectory === '') return file
+      const qualified = sourceDirectory + '/' + candidateFile.path
+      if (!isSafeRelative(qualified)) {
+        throw new UiError(
+          'UI_REGISTRY_UNAVAILABLE',
+          'UI registry contains an invalid installable item path.',
+        )
+      }
+      return { ...candidateFile, path: qualified }
+    }),
+  }
+}
+
 function isInstallableItem(item: unknown): item is UiRegistry['items'][number] {
   if (!item || typeof item !== 'object') return false
   const candidate = item as Partial<UiRegistry['items'][number]>
@@ -256,12 +301,18 @@ export async function readUiRegistryItem(
 }
 
 function isSafeRelative(value: string): boolean {
+  const segments = value.split('/')
   return (
     value.length > 0 &&
     !value.startsWith('/') &&
     !/^[A-Za-z]:[\\/]/u.test(value) &&
     !value.includes('\\') &&
-    !value.split('/').includes('..')
+    !/[?#%]/u.test(value) &&
+    ![...value].some((character) => {
+      const code = character.codePointAt(0) ?? 0
+      return code <= 31 || code === 127
+    }) &&
+    segments.every((segment) => segment.length > 0 && segment !== '.' && segment !== '..')
   )
 }