@arcote.tech/arc-cli 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,12 +12,12 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.6.1",
-    "@arcote.tech/arc-ds": "^0.6.1",
-    "@arcote.tech/arc-react": "^0.6.1",
-    "@arcote.tech/arc-host": "^0.6.1",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.6.1",
-    "@arcote.tech/platform": "^0.6.1",
+    "@arcote.tech/arc": "^0.7.0",
+    "@arcote.tech/arc-ds": "^0.7.0",
+    "@arcote.tech/arc-react": "^0.7.0",
+    "@arcote.tech/arc-host": "^0.7.0",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.0",
+    "@arcote.tech/platform": "^0.7.0",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/access-extractor.ts

@@ -1,21 +1,49 @@
 import { spawn } from "bun";
-import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
-import { basename, join } from "path";
-import type { WorkspacePackage } from "./module-builder";
-import { isContextPackage } from "./module-builder";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { isContextPackage, type WorkspacePackage } from "./module-builder";
+
+// Locate platform's server entry by walking up from the CLI bundle location.
+// `import.meta.url` at runtime points to the bundled `dist/index.js` (the CLI
+// is shipped as a single Bun.build artifact), so the path is:
+//   <arcRoot>/packages/cli/dist/index.js
+// Four `dirname` applications reach <arcRoot>. This works regardless of how
+// the user invoked the CLI — symlink, npm install, or direct path — as long
+// as the CLI binary lives at packages/cli/dist/ inside the arc workspace.
+function locatePlatformServerEntry(): string {
+  const here = fileURLToPath(import.meta.url);
+  const arcRoot = realpathSync(dirname(dirname(dirname(dirname(here)))));
+  return join(arcRoot, "packages", "platform", "src", "index.server.ts");
+}
 
 // ---------------------------------------------------------------------------
-// access-extractor — runs platform module-access discovery in an ISOLATED
-// subprocess so the global registry (singleton in @arcote.tech/platform) is
-// not polluted between builds. The subprocess imports each context bundle,
-// calls getAllModuleAccess(), and serializes a plain-JSON view to
-// `<arcDir>/access.json`.
+// access-extractor — discovers per-module access rules (`protectedBy(...)`)
+// from already-built server bundles, in an ISOLATED subprocess.
+//
+// Why subprocess: the global module registry in @arcote.tech/platform is a
+// singleton. Importing user packages from the main CLI process would pollute
+// the registry across builds.
+//
+// Why server bundles (not source): user package source files may import
+// browser-only code at top level (React, JSX runtime, DOM globals). The
+// subprocess is target=bun — those imports crash. Server bundles are built
+// with ONLY_SERVER=true defines that tree-shake the browser branches, so
+// they're safe to load in a bare Bun process.
+//
+// Constraint: only CONTEXT packages can have `protectedBy(...)` rules —
+// non-context (pure-browser) packages are skipped. This is sensible: access
+// checks logically belong with server state, not display components.
 //
-// The `check` callback per rule is NOT serialized — it's a function reference
-// kept inside the server bundle. We only record `{ token: { name }, hasCheck }`.
-// Runtime resolves the actual check via the loaded server bundle at request
-// time.
+// Order requirement: buildContextPackages MUST run before extractAccessMap
+// — server bundles at `packages/<pkg>/dist/server/main/index.js` must exist.
 // ---------------------------------------------------------------------------
 
 export interface SerializedAccessRule {
@@ -30,37 +58,40 @@ export interface SerializedModuleAccess {
 export type SerializedAccessMap = Record<string, SerializedModuleAccess>;
 
 export async function extractAccessMap(
-  arcDir: string,
-  packages: WorkspacePackage[],
+  rootDir: string,
+  packages: readonly WorkspacePackage[],
 ): Promise<SerializedAccessMap> {
-  // Prefer the v0.6 per-module location; fall back to the legacy per-package
-  // dist path used while the build pipeline migration is in progress. The
-  // fallback goes away once module-builder always emits server bundles
-  // under <arcDir>/modules/<safeName>/server.js.
+  // Each entry: a context-package server bundle path that the worker will
+  // dynamically import. Bun resolves the bundle's internal external imports
+  // (`@arcote.tech/platform` etc.) via node_modules walking from the bundle
+  // location — workspace symlinks point back to source, conditional exports
+  // pick the server entry.
   const serverBundles = packages
     .filter((p) => isContextPackage(p.packageJson))
-    .map((p) => {
-      const v06Path = join(arcDir, "modules", basename(p.path), "server.js");
-      const legacyPath = join(p.path, "dist", "server", "main", "index.js");
-      return { name: p.name, path: v06Path, fallback: legacyPath };
-    });
-
-  // Output target — subprocess writes here, we read back.
-  const outPath = join(arcDir, "access.json");
-  mkdirSync(arcDir, { recursive: true });
-
-  // Worker script as a tempfile so we can `bun run <path>` (Bun has no -e flag
-  // for TypeScript). Cleanup in finally.
-  const workerPath = join(tmpdir(), `arc-access-extractor-${Date.now()}.mjs`);
+    .map((p) => ({
+      name: p.name,
+      path: join(p.path, "dist", "server", "main", "index.js"),
+    }))
+    .filter((b) => existsSync(b.path));
+
+  // Worker must live INSIDE the workspace tree so Bun's module resolver can
+  // walk up to <rootDir>/node_modules and find @arcote.tech/platform/server.
+  // A tmpfile in /tmp/ would fail bare-specifier resolution.
+  const workerDir = join(rootDir, ".arc", ".tmp");
+  mkdirSync(workerDir, { recursive: true });
+  const workerPath = join(workerDir, `access-extractor-${Date.now()}.mjs`);
+  const outPath = join(workerDir, `access-${Date.now()}.json`);
   writeFileSync(workerPath, WORKER_SOURCE);
 
   try {
     const proc = spawn({
       cmd: ["bun", "run", workerPath],
+      cwd: rootDir,
       env: {
         ...process.env,
         ARC_ACCESS_BUNDLES: JSON.stringify(serverBundles),
         ARC_ACCESS_OUT: outPath,
+        ARC_PLATFORM_ENTRY: locatePlatformServerEntry(),
       },
       stdout: "pipe",
       stderr: "inherit",
@@ -76,17 +107,22 @@ export async function extractAccessMap(
     } catch {
       // best effort
     }
+    try {
+      unlinkSync(outPath);
+    } catch {
+      // best effort
+    }
   }
 }
 
 // ---------------------------------------------------------------------------
-// Worker source (inlined — runs in fresh Bun process)
+// Worker source (inlined — runs in fresh Bun process at user workspace cwd)
 // ---------------------------------------------------------------------------
 
 const WORKER_SOURCE = `
-import { existsSync } from "node:fs";
-
 globalThis.ONLY_SERVER = true;
+globalThis.ONLY_BROWSER = false;
+globalThis.ONLY_CLIENT = false;
 
 const bundles = JSON.parse(process.env.ARC_ACCESS_BUNDLES || "[]");
 const out = process.env.ARC_ACCESS_OUT;
@@ -95,20 +131,16 @@ if (!out) {
   process.exit(2);
 }
 
-const platform = await import("@arcote.tech/platform");
+// Direct file-path import — bypasses node_modules resolution entirely.
+// Avoids quirks with bun-link snapshots holding stale package.json exports.
+const platform = await import(process.env.ARC_PLATFORM_ENTRY);
 
-for (const { name, path, fallback } of bundles) {
-  const target = existsSync(path) ? path : fallback;
-  if (!target || !existsSync(target)) {
-    // No server bundle on either path — module has no protected access rules
-    // to discover. Skip silently rather than logging a misleading error.
-    continue;
-  }
+for (const { name, path } of bundles) {
   try {
-    await import(target);
+    await import(path);
   } catch (e) {
-    console.error("[access-extractor-worker] failed to import", name, "from", target, e);
-    // Continue — partial access map is better than total failure.
+    console.error("[access-extractor-worker] failed to import", name, ":", e.message);
+    // Partial map is better than total failure.
   }
 }
 

package/src/builder/build-cache.ts

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
-const CACHE_VERSION = 1;
+// v2: switched from `modules-bundle` (one unit) to `modules-chunk:<name>`
+// (one unit per chunk group). Old v1 entries are irrelevant.
+const CACHE_VERSION = 2;
 const CACHE_FILE = ".build-cache.json";
 
 export interface CacheEntry {

package/src/builder/chunk-planner.ts

@@ -0,0 +1,107 @@
+import { basename } from "path";
+import type { SerializedAccessMap } from "./access-extractor";
+import type { WorkspacePackage } from "./module-builder";
+
+// ---------------------------------------------------------------------------
+// chunk-planner — decides which chunk group each workspace package belongs to,
+// based on its `protectedBy(...)` declarations.
+//
+// Rules:
+//   - 0 access rules                      → "public"
+//   - 1 rule                              → rule.token.name
+//   - N rules, all same token.name        → that token name
+//   - N rules, mixed token.names          → throw (multi-token modules are not
+//                                            supported; user must split or use
+//                                            a single token type)
+//
+// Output: a per-chunk grouping consumed by buildModulesByChunks() to emit
+// independent Bun.build per chunk group. Chunks NEVER share code across
+// groups (a public chunk file can be served unauthenticated; a per-token
+// chunk file is signed and requires the matching token).
+// ---------------------------------------------------------------------------
+
+export const PUBLIC_CHUNK = "public" as const;
+
+export interface PackageChunk {
+  /** Workspace package being assigned. */
+  readonly pkg: WorkspacePackage;
+  /** Chunk group: "public" or a token.name from `protectedBy(...)`. */
+  readonly chunk: string;
+  /** Module name as it appears in the runtime registry (last path segment of pkg.name). */
+  readonly moduleName: string;
+  /** Filesystem-safe directory name within `<arcDir>/modules/<chunk>/`. */
+  readonly safeName: string;
+}
+
+export interface ChunkPlan {
+  /** Module-name → assignment, one entry per workspace package. */
+  readonly assignments: ReadonlyMap<string, PackageChunk>;
+  /** Chunk group → packages in that group, used by builder to spawn N parallel Bun.build. */
+  readonly groups: ReadonlyMap<string, readonly PackageChunk[]>;
+  /** Sorted chunk names (always starts with "public" if present). */
+  readonly chunks: readonly string[];
+}
+
+export function planChunks(
+  packages: readonly WorkspacePackage[],
+  accessMap: SerializedAccessMap,
+): ChunkPlan {
+  const assignments = new Map<string, PackageChunk>();
+  const groups = new Map<string, PackageChunk[]>();
+
+  for (const pkg of packages) {
+    const moduleName = moduleNameOf(pkg.name);
+    const access = accessMap[moduleName];
+    const chunk = resolveChunk(moduleName, access);
+
+    const entry: PackageChunk = {
+      pkg,
+      chunk,
+      moduleName,
+      safeName: basename(pkg.path),
+    };
+    assignments.set(moduleName, entry);
+
+    const bucket = groups.get(chunk);
+    if (bucket) {
+      bucket.push(entry);
+    } else {
+      groups.set(chunk, [entry]);
+    }
+  }
+
+  const chunks = [...groups.keys()].sort((a, b) => {
+    if (a === PUBLIC_CHUNK) return -1;
+    if (b === PUBLIC_CHUNK) return 1;
+    return a.localeCompare(b);
+  });
+
+  return { assignments, groups, chunks };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Match arc.ts: scoped pkg "@my-app/auth" → module name "auth". */
+function moduleNameOf(pkgName: string): string {
+  return pkgName.includes("/") ? pkgName.split("/").pop()! : pkgName;
+}
+
+function resolveChunk(
+  moduleName: string,
+  access: SerializedAccessMap[string] | undefined,
+): string {
+  if (!access || access.rules.length === 0) return PUBLIC_CHUNK;
+
+  const tokenNames = new Set(access.rules.map((r) => r.token.name));
+  if (tokenNames.size === 1) {
+    return [...tokenNames][0];
+  }
+
+  const list = [...tokenNames].sort().join(", ");
+  throw new Error(
+    `Module "${moduleName}" has access rules for multiple tokens [${list}]. ` +
+      `Multi-token modules are not supported — split the module or unify on a single token type.`,
+  );
+}

package/src/builder/dependency-collector.ts

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, join } from "path";
+import { FRAMEWORK_PEERS, FRAMEWORK_PEER_SET } from "./framework-peers";
 import type { WorkspacePackage } from "./module-builder";
 
+export { FRAMEWORK_PEERS };
+
 // ---------------------------------------------------------------------------
 // dependency-collector — generates per-module + global framework dep manifests
 // that the runtime container uses to `bun install`.
@@ -15,20 +18,6 @@ import type { WorkspacePackage } from "./module-builder";
 // into the module's own node_modules at deploy time.
 // ---------------------------------------------------------------------------
 
-/**
- * Packages that MUST be singleton across all modules — they define classes
- * checked with `instanceof` cross-module. Container resolves these from the
- * platform-level `node_modules/`, not per-module.
- */
-export const FRAMEWORK_PEERS = [
-  "@arcote.tech/arc",
-  "@arcote.tech/arc-ds",
-  "@arcote.tech/arc-react",
-  "@arcote.tech/platform",
-  "react",
-  "react-dom",
-] as const;
-
 export type FrameworkPeer = (typeof FRAMEWORK_PEERS)[number];
 
 export interface CollectedDeps {
@@ -46,10 +35,17 @@ export function collectFrameworkDeps(
   arcDir: string,
   rootDir: string,
   packages: WorkspacePackage[],
+  sharedDeps: ReadonlyArray<{ name: string; version: string }> = [],
 ): CollectedDeps {
   mkdirSync(arcDir, { recursive: true });
 
   const versions = resolveFrameworkVersions(rootDir, packages);
+  // Shared deps (discovered across ≥ 2 workspace packages) join the framework
+  // in the global manifest — installed once into <arcDir>/node_modules/ and
+  // served via the shell so each module's browser bundle leaves them external.
+  for (const { name, version } of sharedDeps) {
+    versions[name] = version;
+  }
   const manifest = {
     name: "arc-platform-framework",
     private: true,
@@ -59,20 +55,18 @@ export function collectFrameworkDeps(
   const manifestPath = join(arcDir, "package.json");
   writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
 
-  // Copy workspace bun.lock so the container can use --frozen-lockfile for
-  // deterministic framework installs. Per-module installs run without it (no
-  // per-module lockfile in MVP).
-  const rootLock = join(rootDir, "bun.lock");
-  const targetLock = join(arcDir, "bun.lock");
-  if (existsSync(rootLock)) {
-    copyFileSync(rootLock, targetLock);
-  }
-
-  const hash = sha256OfFiles([manifestPath, targetLock]);
+  // Hash over package.json bytes alone. No lockfile in the hash: newer bun
+  // rejects empty `{}` lockfiles, and the framework dep set is small enough
+  // to let bun generate its own lockfile during install in the image build.
+  const hash = sha256Hex(readFileSync(manifestPath));
   writeFileSync(join(arcDir, ".deps-hash"), hash + "\n");
   return { hash, manifestPath };
 }
 
+function sha256Hex(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
 // ---------------------------------------------------------------------------
 // Per-module deps
 // ---------------------------------------------------------------------------
@@ -80,19 +74,37 @@ export function collectFrameworkDeps(
 export function collectModuleDeps(
   arcDir: string,
   pkg: WorkspacePackage,
+  sharedDepNames: ReadonlySet<string> = new Set(),
 ): CollectedDeps {
   const safeName = basename(pkg.path);
   const moduleDir = join(arcDir, "modules", safeName);
   mkdirSync(moduleDir, { recursive: true });
 
   const pkgDeps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
+  const peerDeps = (pkg.packageJson.peerDependencies ?? {}) as Record<
+    string,
+    string
+  >;
   const filtered: Record<string, string> = {};
-  const frameworkSet = new Set<string>(FRAMEWORK_PEERS);
+
+  // Regular deps, excluding:
+  //  - framework peers   (global install via collectFrameworkDeps)
+  //  - shared deps       (also global — promoted to shell across ≥ 2 modules)
+  //  - workspace links   (bundled inline by buildModules; not on npm)
   for (const [name, spec] of Object.entries(pkgDeps)) {
-    if (frameworkSet.has(name)) continue;
+    if (FRAMEWORK_PEER_SET.has(name)) continue;
+    if (sharedDepNames.has(name)) continue;
     if (spec.startsWith("workspace:")) continue;
     filtered[name] = spec;
   }
+  // Peer deps minus framework peers + shared deps — e.g. `@arcote.tech/arc-auth`
+  // is declared peer of `@ndt/auth` and lives in framework peers; user peers
+  // not in either set go per-module.
+  for (const [name, spec] of Object.entries(peerDeps)) {
+    if (FRAMEWORK_PEER_SET.has(name)) continue;
+    if (sharedDepNames.has(name)) continue;
+    filtered[name] = spec;
+  }
 
   const manifest = {
     name: `arc-module-${safeName}`,
@@ -116,22 +128,51 @@ function resolveFrameworkVersions(
   rootDir: string,
   packages: WorkspacePackage[],
 ): Record<string, string> {
-  // Workspace root deps win — that's where the user pins versions. Fall back
-  // to whatever a workspace package declared, then `*` as last resort.
+  // The framework manifest installs into /app/node_modules in the deploy
+  // image. It needs to cover:
+  //   1. Static framework peers (FRAMEWORK_PEERS) — always present
+  //   2. User-extension @arcote.tech/* peers (e.g. arc-ai-openai) declared
+  //      as peerDeps on user context packages
+  //   3. npm runtime deps that server bundles leave external (non-workspace
+  //      deps not yet bundled inline)
+  // Resolution order for each: root package.json wins, then any workspace
+  // package's deps/peerDeps, then "*" as last resort.
   const rootPkg = JSON.parse(
     readFileSync(join(rootDir, "package.json"), "utf-8"),
   );
   const rootDeps = (rootPkg.dependencies ?? {}) as Record<string, string>;
+  const rootDevDeps = (rootPkg.devDependencies ?? {}) as Record<string, string>;
+
+  // Build the full required name set.
+  const required = new Set<string>(FRAMEWORK_PEERS);
+  for (const pkg of packages) {
+    const peers = pkg.packageJson.peerDependencies ?? {};
+    const deps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
+    // Any @arcote.tech/* peer beyond the static list (e.g. arc-ai adapters).
+    for (const name of Object.keys(peers)) {
+      if (name.startsWith("@arcote.tech/")) required.add(name);
+    }
+    // npm deps (non-workspace) — server bundles leave them external, so the
+    // image needs them in /app/node_modules.
+    for (const [name, spec] of Object.entries(deps)) {
+      if (spec.startsWith("workspace:")) continue;
+      if (name.startsWith("@arcote.tech/") || !isFrameworkExternal(name)) continue;
+      required.add(name);
+    }
+  }
+
   const out: Record<string, string> = {};
-  for (const name of FRAMEWORK_PEERS) {
-    const rootSpec = rootDeps[name];
+  for (const name of required) {
+    const rootSpec = rootDeps[name] ?? rootDevDeps[name];
     if (rootSpec) {
       out[name] = rootSpec;
       continue;
     }
     let found: string | undefined;
     for (const pkg of packages) {
-      const spec = (pkg.packageJson.dependencies ?? {})[name];
+      const spec =
+        (pkg.packageJson.dependencies ?? {})[name] ??
+        (pkg.packageJson.peerDependencies ?? {})[name];
       if (spec) {
         found = spec;
         break;
@@ -142,6 +183,19 @@ function resolveFrameworkVersions(
   return out;
 }
 
+/**
+ * True if a non-arc npm dep is one the image must install globally for
+ * runtime resolution. Today we include everything that user context packages
+ * declare as deps but isn't `workspace:` — server bundles leave them external
+ * so they MUST be present in /app/node_modules.
+ *
+ * Future optimization: bundle these inline into the server bundle to avoid
+ * the install layer entirely. Left as a follow-up.
+ */
+function isFrameworkExternal(_name: string): boolean {
+  return true;
+}
+
 function sha256OfFiles(paths: string[]): string {
   const hash = createHash("sha256");
   for (const p of paths.sort()) {

package/src/builder/framework-peers.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// framework-peers — single source of truth for packages that MUST be
+// singleton across all modules. Used by:
+//
+//   - dependency-collector.ts  (decides which deps go to the global
+//                               framework manifest vs per-module install)
+//   - module-builder.ts        (decides which imports stay external in
+//                               browser bundles, mapped via importmap to
+//                               /shell/<short>.js)
+//   - shared.ts                (collectArcPeerDeps — runtime shell entry
+//                               discovery, importmap generation)
+//   - commands/build-shell.ts  (runtime shell builder, fallback for user-
+//                               extension @arcote.tech/* packages)
+//
+// Two reasons a package needs to be singleton:
+//
+//  1. Core framework — `instanceof` checks for ArcAggregate / ArcCommand /
+//     ArcFunction base classes require a single class identity across module
+//     boundaries.
+//  2. Browser-side React Context — AuthProvider / WorkspaceProvider /
+//     ChatProvider etc.; duplicate Context objects across modules cause
+//     `useAuth must be used within AuthProvider` even when the provider IS
+//     mounted (just from a different module's React.Context instance).
+//
+// The runtime container installs these into <arcDir>/node_modules/ (global)
+// and the shell builder emits /shell/<short>.js per peer.
+// ---------------------------------------------------------------------------
+
+/** Core framework packages — `instanceof` consumers. */
+export const CORE_PEERS = [
+  "@arcote.tech/arc",
+  "@arcote.tech/arc-ds",
+  "@arcote.tech/arc-react",
+  "@arcote.tech/platform",
+] as const;
+
+/** Browser-side fragments with React Context — singleton identity required. */
+export const BROWSER_FRAGMENT_PEERS = [
+  "@arcote.tech/arc-auth",
+  "@arcote.tech/arc-workspace",
+  "@arcote.tech/arc-utils",
+  "@arcote.tech/arc-chat",
+] as const;
+
+/** All @arcote.tech/* packages that must be singleton. */
+export const ARC_PEERS = [...CORE_PEERS, ...BROWSER_FRAGMENT_PEERS] as const;
+
+/** React + ReactDOM — separate from arc peers but treated identically. */
+export const REACT_PEERS = ["react", "react-dom"] as const;
+
+/**
+ * Full set of npm packages that the runtime container installs globally
+ * (one copy in <arcDir>/node_modules/, shared across all per-module bundles).
+ * Filter applied by dependency-collector to keep them out of per-module deps.
+ */
+export const FRAMEWORK_PEERS = [...ARC_PEERS, ...REACT_PEERS] as const;
+
+/**
+ * Bare specifiers that browser bundles leave external — resolved via the
+ * importmap in the shell HTML. Superset of FRAMEWORK_PEERS because React's
+ * automatic JSX transform emits `react/jsx-runtime` and `react/jsx-dev-runtime`
+ * sub-path imports that also need to point at the shared shell bundle.
+ */
+export const SHELL_EXTERNALS = [
+  ...FRAMEWORK_PEERS,
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+] as const;
+
+export const FRAMEWORK_PEER_SET = new Set<string>(FRAMEWORK_PEERS);
+export const SHELL_EXTERNAL_SET = new Set<string>(SHELL_EXTERNALS);
+
+/** Short identifier used as the shell bundle filename (`/shell/<short>.js`). */
+export function shortNameOf(pkg: string): string {
+  // `@arcote.tech/platform` is special-cased historically to `platform`
+  // (rather than `@arcote.tech/platform`) — keep that mapping stable so
+  // existing consumers don't break.
+  if (pkg === "@arcote.tech/platform") return "platform";
+  if (pkg.startsWith("@arcote.tech/")) return pkg.slice("@arcote.tech/".length);
+  return pkg;
+}