@livx.cc/appwrap 0.54.0 → 0.56.0

package/src/cli.ts

@@ -10,10 +10,10 @@
  */
 import { execFileSync, spawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
-import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
-import { basename, delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
+import { basename, dirname, extname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -23,10 +23,11 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
 import { unknownConfigKeys } from './config';
+import { resolveModulePacks, type ResolvedModule, type SyncContext } from './packs';
 import { createHash } from 'crypto';
-import { buildInfoPlist, buildMacEntitlements, deriveDesktopConfig, parseMacProfile, resolveCargoPath, stampTauriConf } from './desktop';
-import type { DesktopShellConfig } from './desktop';
-import { APPLE_ICON_GRID_SCALE, makeDockRuntimeIcon } from './icon';
+// Icon helpers re-exported so the EE desktop lane (which owns the Tauri chassis) can reuse them via
+// `@livx.cc/appwrap/cli` — the CE/EE split (Phase D) moved the desktop lane out but keeps these shared.
+export { APPLE_ICON_GRID_SCALE, makeDockRuntimeIcon } from './icon';
 import {
   androidScreenOrientation,
   applyBuildNumberFlag,
@@ -97,16 +98,61 @@ const ANDROID_PERMISSION_KEYS: Record<string, string[]> = {
 };
 
 /** Resolve a bundled asset dir. A published tarball ships runtime/ + templates/ at the package root
- * (one level above src/); the monorepo resolves them at the repo root (three levels up). */
+ * (one level above src/); the monorepo resolves them at the repo root (three levels up). Returns the
+ * REAL path — a dev checkout may stage the package-root dir as a symlink to the repo-root source (what
+ * prepack does with a copy), and Bun's cpSync refuses a symlink as a copy-source root. */
 function resolveAssetRoot(rel: string): string {
   const local = resolve(import.meta.dir, '..', rel);
-  return existsSync(local) ? local : resolve(import.meta.dir, '../../..', rel);
+  const dir = existsSync(local) ? local : resolve(import.meta.dir, '../../..', rel);
+  try { return realpathSync(dir); } catch { return dir; }
 }
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
+/** Ordered runtime-template roots copied into native/ (later roots overlay earlier — file-level
+ * last-wins), defaulting to the single built-in template. runCli (A5) can extend this so a consumer
+ * (a host) layers extra shell files on top of CE without forking the template. A single root
+ * is byte-identical to the pre-overlay behavior. */
+let TEMPLATE_ROOTS: string[] = [TEMPLATE_DIR];
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
-/** Desktop (Tauri chassis) template — phase-0, macOS-only. Its own generated wrapper (`native-desktop/`)
- * is disposable, like `native/`; the template stays canonical (edit here, regenerate propagates). */
-const DESKTOP_TEMPLATE_DIR = resolveAssetRoot('runtime-desktop');
+/** Scaffold for `appwrap create-module` — a starter module pack (see packs.ts / @livx.cc/appwrap/testing). */
+const MODULE_PACK_TEMPLATE_DIR = resolveAssetRoot('templates/module-pack');
+/** Desktop (Tauri chassis) template dir. CE ships no bundled desktop template — the desktop lane is
+ * host-owned: a consumer points this at its own template via `runCli({ desktopTemplateDir })` (A5).
+ * A `let` so runCli can override it; empty by default so the mobile lanes are unaffected. The desktop
+ * lane itself lives in the EE package (Phase D split) and reads this value via `getDesktopTemplateDir()`
+ * — CE keeps the seam (set by `runCli({ desktopTemplateDir })`) but ships no desktop code. */
+let DESKTOP_TEMPLATE_DIR = '';
+
+/** The desktop (Tauri) template dir set via `runCli({ desktopTemplateDir })`. Read by the EE desktop
+ * lane (hosted on top of CE through the `platforms` seam) so the seam stays authoritative in one place. */
+export function getDesktopTemplateDir(): string {
+  return DESKTOP_TEMPLATE_DIR;
+}
+
+/**
+ * Composition seam for a HOST that wraps this CLI (any consumer). Every field is
+ * optional and no-op by default, so the bare `appwrap` bin behaves exactly as before. A host calls
+ * `runCli({...})` to extend the CLI without forking it.
+ */
+export interface CliOptions {
+  /** Extra or overriding top-level commands, keyed by command name — consulted BEFORE the built-in
+   * switch, so a host can add a command or replace a built-in one. */
+  commands?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[]) => Promise<void> | void>;
+  /** Pluggable platform handlers for `dev`/`build` (keyed by the platform arg, e.g. 'desktop') —
+   * consulted BEFORE the built-in platform routing, so a host can add/replace a platform lane. The
+   * 4th arg is the driving command ('dev' | 'build') so a single handler (e.g. the EE desktop lane)
+   * can branch dev-vs-build — `dev desktop` and `build desktop` route to the SAME handler key. */
+  platforms?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[], command: 'dev' | 'build') => Promise<void> | void>;
+  /** Module packs injected by the host, applied BEFORE the app config's own `modulePacks` (so the app
+   * can still override them, last-wins). */
+  modulePacks?: string[];
+  /** Extra runtime-template overlay roots, appended after the built-in template (later roots win). */
+  templateRoots?: string[];
+  /** Override for the desktop (Tauri) template dir. */
+  desktopTemplateDir?: string;
+}
+
+/** The host composition for THIS run, set once by runCli. Empty by default → bare-bin behavior. */
+let cliOptions: CliOptions = {};
 
 /** This CLI's own published version — used to pin the `bunx @livx.cc/appwrap@^x.y.z` invocations the
  * emitted workflow runs. Pinning to THIS version's floor means CI fails LOUDLY ("version not found")
@@ -116,10 +162,67 @@ const CLI_VERSION: string = (await import(resolve(import.meta.dir, '..', 'packag
 
 // Load the capability manifest VALUES from the resolved runtime (pure data — safe outside NativeScript).
 // Top-level await resolves before any command dispatches at the bottom of this file.
-const { MODULES, OPTIONAL_GROUPS } = (await import(
+const { MODULES, OPTIONAL_GROUPS, LEGACY_BUNDLED_GROUPS, MANIFEST_SCHEMA_VERSION } = (await import(
   resolve(TEMPLATE_DIR, 'app/shell/capabilities.manifest')
 )) as typeof CapManifest;
 
+/** The composed module set for THIS command run: built-ins + the config's `modulePacks`, resolved once
+ * at command entry by `applyModulePacks`. Stays `null` when NO packs are configured — every code path
+ * then reads the built-in `MODULES` directly, so a pack-less build is byte-identical to pre-packs. */
+let RESOLVED_MODULES: ResolvedModule[] | null = null;
+
+/** The active module set the CLI derives from — merged (built-ins + packs) when packs are configured,
+ * else the built-ins verbatim. */
+function moduleList(): CapManifest.ModuleManifest[] {
+  return RESOLVED_MODULES ? RESOLVED_MODULES.map((r) => r.manifest) : MODULES;
+}
+
+/** Pack provenance for a module name (source label + pack dir) — used by the generator to locate a
+ * pack module's handler file + native source. Undefined for a built-in. */
+function packInfo(name: string): { source: string; packDir: string } | undefined {
+  const r = RESOLVED_MODULES?.find((m) => m.manifest.name === name);
+  return r && r.packDir ? { source: r.source, packDir: r.packDir } : undefined;
+}
+
+/** Resolve the config's `modulePacks` (if any) into RESOLVED_MODULES for this run. No-op (leaves the
+ * built-ins untouched → byte-identical) when the config declares no packs. Async because pack manifests
+ * are dynamically imported; callers await it before the sync/regenerate pipeline. */
+async function applyModulePacks(cwd: string, cfg: AppwrapConfig): Promise<void> {
+  // Host-injected packs first (the host's), then the app config's — so the app can override, last-wins.
+  const refs = [...(cliOptions.modulePacks ?? []), ...(cfg.modulePacks ?? [])];
+  if (refs.length === 0) {
+    RESOLVED_MODULES = null;
+  } else {
+    const ctx: SyncContext = {
+      platform: 'both',
+      env: process.env.APPWRAP_ENV || 'default',
+      ci: !!process.env.CI,
+    };
+    const map = await resolveModulePacks({
+      builtins: MODULES,
+      builtinSchemaVersion: MANIFEST_SCHEMA_VERSION,
+      packRefs: refs,
+      ctx,
+      cwd,
+    });
+    RESOLVED_MODULES = [...map.values()];
+  }
+  warnUnknownModules(cfg);
+}
+
+/** Warn (never fail) for any name in `modules` that resolves to neither a built-in nor a pack module —
+ * with the pack model it's easy to list a capability (e.g. 'billing') and forget to add its pack to
+ * `modulePacks`, which would otherwise silently no-op (no handler, no capability). */
+function warnUnknownModules(cfg: AppwrapConfig): void {
+  if (!cfg.modules) return;
+  const known = new Set(moduleList().map((m) => m.name));
+  for (const name of cfg.modules) {
+    if (!known.has(name)) {
+      console.warn(`⚠ module '${name}' is listed in \`modules\` but isn't a built-in or provided by any \`modulePacks\` — did you forget to add its pack? (ignored)`);
+    }
+  }
+}
+
 /** Native requirements composed for a build: the union (deduped) of the active modules' self-contained
  * manifest declarations. Two modes:
  *  - `modules` ABSENT (legacy): every capability active; permissions come ONLY from `permissions{}`
@@ -137,20 +240,25 @@ interface NativeReqs {
   androidGradleDeps: string[];
   androidKotlin: boolean;        // any active module ships Kotlin native source
   androidManifestApp: string[];  // raw XML injected inside AndroidManifest <application>
-  nativeSrc: string[];           // active modules' nativeSrc dir names (under runtime/modules-native/)
-  widgetAppGroup?: string;       // 'group.<appId>' when the `widget` module is active (App Group id
-                                 // shared by the app + its widget extension; templated into both)
+  nativeSrc: string[];           // active BUILT-IN modules' nativeSrc dir names (under runtime/modules-native/)
+  packNativeSrc: Array<{ name: string; srcDir: string }>;  // active PACK modules' native source (absolute src dirs)
+  packHandlers: Array<{ name: string; source: string; packDir: string; file: string; fn: string }>; // active pack modules with a register handler (for the generated barrel + staging)
+  packModules: Array<Pick<CapManifest.ModuleManifest, 'name' | 'core' | 'capabilities' | 'group'>>; // active pack modules' handshake-relevant subset (their capabilities aren't in the runtime's static MODULES)
 }
 
 function nativeReqs(cfg: AppwrapConfig): NativeReqs {
-  const optIn = MODULES.filter((m) => !m.core);
+  const modules = moduleList();
+  const optIn = modules.filter((m) => !m.core);
   // Legacy default (no `modules` key) = every opt-in capability EXCEPT strictly-opt-in own-file
   // modules (OPTIONAL_GROUPS, e.g. health): those carry deps/perms legacy won't stamp, so they must
   // be explicitly requested. Explicit mode = exactly what `modules` lists.
   const active = cfg.modules
     ? new Set(cfg.modules)
-    : new Set(optIn.filter((m) => !OPTIONAL_GROUPS.includes(m.group as (typeof OPTIONAL_GROUPS)[number])).map((m) => m.name));
-  const activeMods = MODULES.filter((m) => m.core || active.has(m.name));
+    : new Set(optIn.filter((m) =>
+        !OPTIONAL_GROUPS.includes(m.group as (typeof OPTIONAL_GROUPS)[number]) ||
+        LEGACY_BUNDLED_GROUPS.includes(m.group as (typeof LEGACY_BUNDLED_GROUPS)[number])
+      ).map((m) => m.name));
+  const activeMods = modules.filter((m) => m.core || active.has(m.name));
 
   const iosPlist: Array<{ key: string; usage: string }> = [];
   const seenKeys = new Set<string>();
@@ -158,6 +266,9 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
   const gradle = new Set<string>();
   const iosEntitlements: Record<string, boolean | string | string[]> = {};
   const nativeSrc: string[] = [];
+  const packNativeSrc: NativeReqs['packNativeSrc'] = [];
+  const packHandlers: NativeReqs['packHandlers'] = [];
+  const packModules: NativeReqs['packModules'] = [];
   const androidManifestApp: string[] = [];
   let androidKotlin = false;
 
@@ -174,7 +285,9 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       Object.assign(iosEntitlements, m.ios?.entitlements ?? {});
       if (m.android?.kotlin) androidKotlin = true;
       if (m.android?.manifestApplication) androidManifestApp.push(m.android.manifestApplication);
-      if (m.nativeSrc) nativeSrc.push(m.nativeSrc);
+      // built-in native source resolves under runtime/modules-native/; pack native source (below)
+      // resolves under the pack's own dir, so it must not be conflated with the built-in dir names.
+      if (m.nativeSrc && !packInfo(m.name)) nativeSrc.push(m.nativeSrc);
     }
   } else {
     // legacy: only what `permissions{}` declares (via the key maps) — no behavior change
@@ -186,6 +299,18 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     }
   }
 
+  // Active PACK modules (from the config's modulePacks) — their native source + register handler
+  // resolve against the pack's own dir. No-op when no packs are configured (packInfo → undefined).
+  for (const m of activeMods) {
+    const info = packInfo(m.name);
+    if (!info) continue;
+    if (m.nativeSrc) packNativeSrc.push({ name: m.name, srcDir: join(info.packDir, 'native-src', m.nativeSrc) });
+    if (m.handler) packHandlers.push({ name: m.name, source: info.source, packDir: info.packDir, file: m.handler.file, fn: m.handler.fn });
+    // The runtime's static MODULES doesn't include pack modules, so their capabilities must be carried
+    // into the generated handshake map explicitly (see generateModuleArtifacts + buildCapabilityMap).
+    packModules.push({ name: m.name, core: m.core, capabilities: m.capabilities, group: m.group });
+  }
+
   return {
     explicit: !!cfg.modules,
     activeOptIn: optIn.filter((m) => active.has(m.name)).map((m) => m.name),
@@ -197,15 +322,14 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     androidKotlin,
     androidManifestApp,
     nativeSrc,
-    // App Group for the widget extension ↔ app shared container. Derived from the app id so the module
-    // stays app-agnostic; templated into app.entitlements + the extension's entitlements/Swift.
-    widgetAppGroup: active.has('widget') ? `group.${cfg.id}` : undefined,
+    packNativeSrc,
+    packHandlers,
+    packModules,
   };
 }
 
 /** Map a strippable optional group → its handler file + register fn (for the generated barrel). */
 const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
-  health: { file: './handlers-health', fn: 'registerHealthHandlers' },
   oauth: { file: './handlers-oauth', fn: 'registerOAuthHandlers' },
   reviews: { file: './handlers-reviews', fn: 'registerReviewsHandlers' },
   scanner: { file: './handlers-scanner', fn: 'registerScannerHandlers' },
@@ -213,22 +337,112 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   tracking: { file: './handlers-tracking', fn: 'registerTrackingHandlers' },
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
-  widget: { file: './handlers-widget', fn: 'registerWidgetHandlers' },
+  // billing/health/widget live in host-provided module packs (not part of CE) — a consumer opts in via modulePacks.
 };
 
+/** The bare specifier a pack handler uses to import a built-in shell API — rewritten to a relative
+ * `./<mod>` when the file is staged next to the shell sources. A pack authored out-of-repo imports
+ * e.g. `@livx.cc/appwrap/runtime/app/shell/bridge` (resolvable, since the npm package ships runtime/),
+ * so it typechecks standalone; staging drops it beside the real shell files, where `./bridge` resolves. */
+const SHELL_API_SPECIFIER = /(['"])@livx\.cc\/appwrap\/runtime\/app\/shell\//g;
+
+/** Rewrite a pack handler's shell-API imports from the package specifier to relative, so the file
+ * resolves once staged beside the real shell sources. Pure (exported for tests). */
+export function rewritePackShellImports(src: string): string {
+  return src.replace(SHELL_API_SPECIFIER, '$1./');
+}
+
+/** Resolve a pack-local relative import specifier to an absolute source file (trying the usual TS/JS
+ * extensions + an index file), or null if it doesn't resolve to a real file. */
+function resolvePackImport(fromDir: string, spec: string): string | null {
+  const base = resolve(fromDir, spec);
+  const cands = [base, `${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.jsx`, join(base, 'index.ts'), join(base, 'index.js')];
+  return cands.find((c) => existsSync(c) && statSync(c).isFile()) ?? null;
+}
+
+/** Replace an exact (quoted) import specifier in source with another — anchored so `./x` never
+ * partial-matches `./x-y`. Pure (exported for tests). */
+export function replaceImportSpecifier(src: string, oldSpec: string, newSpec: string): string {
+  const esc = oldSpec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return src.replace(new RegExp(`(['"])${esc}\\1`, 'g'), `$1${newSpec}$1`);
+}
+
+/** Stage a pack source file into the shell, namespaced `pack-<label>-<name>.ts` (never colliding with a
+ * built-in file — keeps built-in staged filenames stable, preserving the byte-compare gate). Rewrites
+ * (a) shell-API imports → relative `./<x>`, and (b) pack-LOCAL relative imports → their namespaced
+ * staged sibling, staging each RECURSIVELY — so a handler's own helper modules (e.g. billing's
+ * billing-offer.ts) are staged too. `staged` memoizes by abs path (dedup + cycle guard). `entryName`
+ * overrides the staged basename for the handler entry (so the barrel imports it by module identity). */
+function stagePackFile(shell: string, label: string, packDir: string, absFile: string, staged: Map<string, string>, entryName?: string): string {
+  const cached = staged.get(absFile);
+  if (cached) return cached;
+  if (!existsSync(absFile)) {
+    console.error(`✖ module pack "${label}": imported file not found: ${absFile}`);
+    process.exit(1);
+  }
+  const name = entryName ?? basename(absFile).replace(/\.(tsx?|jsx?)$/, '');
+  const destName = `pack-${label}-${name}.ts`;
+  const spec = `./${destName.replace(/\.ts$/, '')}`;
+  staged.set(absFile, spec); // set BEFORE recursing so an import cycle terminates
+
+  let src = rewritePackShellImports(readFileSync(absFile, 'utf8'));
+  const fromDir = dirname(absFile);
+  for (const imp of new Bun.Transpiler({ loader: loaderForEntry(absFile) }).scanImports(src)) {
+    if (!imp.path.startsWith('.')) continue; // only pack-LOCAL relative imports need staging
+    const depAbs = resolvePackImport(fromDir, imp.path);
+    if (!depAbs || !depAbs.startsWith(packDir + '/')) continue; // must stay inside the pack dir
+    const depSpec = stagePackFile(shell, label, packDir, depAbs, staged);
+    src = replaceImportSpecifier(src, imp.path, depSpec);
+  }
+  writeFileSync(join(shell, destName), src);
+  return spec;
+}
+
+/** Stage a pack module's handler (+ its pack-local imports) into the shell. Returns the import
+ * specifier the generated barrel imports the handler by. */
+function stagePackHandler(shell: string, h: NativeReqs['packHandlers'][number]): string {
+  const srcFile = resolve(h.packDir, h.file);
+  if (!existsSync(srcFile)) {
+    console.error(`✖ module pack "${h.source}": handler file not found: ${srcFile}`);
+    process.exit(1);
+  }
+  const label = h.source.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const spec = stagePackFile(shell, label, h.packDir, srcFile, new Map(), h.name);
+  console.log(`  pack ← ${h.source}  (${h.name} handler)`);
+  return spec;
+}
+
 /** Generate the two composition artifacts in the wrapper: the active capability list (drives the
  * handshake map) and the optional-handler barrel (imports only active strippable groups). */
 function generateModuleArtifacts(outDir: string, req: NativeReqs): void {
   const shell = join(outDir, 'app/shell');
+  // Sweep stale pack-staged handlers first so a removed/renamed pack never leaves an orphan behind
+  // (self-pruning, like regenerateMobilePlugins wiping its dir) — the active ones are re-staged below.
+  for (const f of existsSync(shell) ? readdirSync(shell) : []) {
+    if (f.startsWith('pack-') && f.endsWith('.ts')) rmSync(join(shell, f), { force: true });
+  }
   writeFileSync(
     join(shell, 'active-modules.generated.ts'),
-    `/** Generated by \`appwrap\` from the appwrap config \`modules\`. Do not edit. */\n` +
-      `export const ACTIVE_MODULE_NAMES: string[] = ${JSON.stringify(req.activeOptIn)};\n`
+    `/** Generated by \`appwrap\` from the appwrap config \`modules\` + \`modulePacks\`. Do not edit. */\n` +
+      `import type { ModuleManifest } from './capabilities.manifest';\n` +
+      `export const ACTIVE_MODULE_NAMES: string[] = ${JSON.stringify(req.activeOptIn)};\n` +
+      // Pack modules aren't in the runtime's static MODULES, so their handshake capabilities travel here
+      // and buildCapabilityMap merges them (empty for a pack-less build).
+      `export const PACK_MODULES: Array<Pick<ModuleManifest, 'name' | 'core' | 'capabilities' | 'group'>> = ${JSON.stringify(req.packModules)};\n`
   );
 
   const groups = req.activeOptionalGroups.filter((g) => OPTIONAL_GROUP_HANDLERS[g]);
-  const imports = groups.map((g) => `import { ${OPTIONAL_GROUP_HANDLERS[g].fn} } from '${OPTIONAL_GROUP_HANDLERS[g].file}';`).join('\n');
-  const calls = groups.map((g) => `  ${OPTIONAL_GROUP_HANDLERS[g].fn}();`).join('\n');
+  const importLines = groups.map((g) => `import { ${OPTIONAL_GROUP_HANDLERS[g].fn} } from '${OPTIONAL_GROUP_HANDLERS[g].file}';`);
+  const callLines = groups.map((g) => `  ${OPTIONAL_GROUP_HANDLERS[g].fn}();`);
+  // Active PACK modules with a register handler — staged into the shell + APPENDED after the built-in
+  // groups (empty when no packs → byte-identical to the pre-packs barrel).
+  for (const h of req.packHandlers) {
+    const spec = stagePackHandler(shell, h);
+    importLines.push(`import { ${h.fn} } from '${spec}';`);
+    callLines.push(`  ${h.fn}();`);
+  }
+  const imports = importLines.join('\n');
+  const calls = callLines.join('\n');
   writeFileSync(
     join(shell, 'optional-handlers.generated.ts'),
     `/** Generated by \`appwrap\` — only the active strippable modules are imported. Do not edit. */\n` +
@@ -394,9 +608,13 @@ function stampEntitlements(outDir: string, cfg: AppwrapConfig, req: NativeReqs):
   const file = join(iosDir, 'app.entitlements');
   const ent: Record<string, boolean | string | string[]> = { ...req.iosEntitlements, ...cfg.iosEntitlements };
   if (!!cfg.push?.enabled && cfg.push?.ios !== false) ent['aps-environment'] = cfg.push.apsEnvironment ?? 'development';
-  // Widget module → App Group on the MAIN app target (the extension's own entitlements file gets the
-  // same group via token substitution). Derived from the app id so no per-app config is needed.
-  if (req.widgetAppGroup) ent['com.apple.security.application-groups'] = [req.widgetAppGroup];
+  // Resolve build tokens in entitlement values (e.g. a module's `__APP_GROUP__` → group.<appId>) so a
+  // module declaring an app-derived entitlement (widget's App Group) needs no hardcoded stamper case.
+  const tokens = buildTokens(cfg);
+  for (const [k, v] of Object.entries(ent)) {
+    if (typeof v === 'string') ent[k] = substituteBuildTokens(v, tokens);
+    else if (Array.isArray(v)) ent[k] = v.map((x) => substituteBuildTokens(x, tokens));
+  }
   const keys = Object.keys(ent);
   if (keys.length === 0) { rmSync(file, { force: true }); return; }
   const val = (v: boolean | string | string[]): string =>
@@ -426,29 +644,52 @@ function stampPrivacyManifest(outDir: string, cfg: AppwrapConfig, req: NativeReq
   if (active) console.log(`  priv ← NSPrivacyTracking=true${cfg.trackingDomains?.length ? ` (${cfg.trackingDomains.length} domain${cfg.trackingDomains.length > 1 ? 's' : ''})` : ''}`);
 }
 
-/** Copy active modules' native source (runtime/modules-native/<name>/) into native/ — only when the
- * module is active, so module native code stays stripped from builds that don't use it. */
-function copyModuleNativeSrc(outDir: string, req: NativeReqs): void {
-  for (const name of req.nativeSrc) {
-    const src = join(MODULES_NATIVE_DIR, name);
-    if (!existsSync(src)) { console.warn(`⚠ module nativeSrc not found: ${src}`); continue; }
+/** Copy active modules' native source (runtime/modules-native/<name>/ for built-ins, <packDir>/
+ * native-src/<name>/ for packs) into native/ — only when the module is active, so module native code
+ * stays stripped from builds that don't use it. Returns the set of dest paths (relative to outDir) it
+ * copied, so regenerateCore can prune a now-INACTIVE module's native files on re-sync (they mirror the
+ * App_Resources layout and cpSync only overwrites, never deletes). */
+function copyModuleNativeSrc(outDir: string, req: NativeReqs): Set<string> {
+  const copied = new Set<string>();
+  const copyFrom = (src: string, label: string) => {
+    if (!existsSync(src)) { console.warn(`⚠ module nativeSrc not found: ${src}`); return; }
     cpSync(src, outDir, { recursive: true, force: true });
-    console.log(`  natv ← module '${name}' native source`);
-  }
+    for (const rel of collectRelFiles(src)) copied.add(rel);
+    console.log(`  natv ← ${label} native source`);
+  };
+  for (const name of req.nativeSrc) copyFrom(join(MODULES_NATIVE_DIR, name), `module '${name}'`);
+  for (const { name, srcDir } of req.packNativeSrc) copyFrom(srcDir, `pack module '${name}'`);
+  return copied;
 }
 
-/** Substitute build-time tokens in copied module native source (after copyModuleNativeSrc). Currently
- * only `__APP_GROUP__` → the derived App Group id, applied to the widget extension's Swift/entitlements/
- * plist so the module ships app-agnostic and the CLI stamps the app-specific group in. Idempotent (the
- * source is re-copied verbatim each sync, then re-substituted). */
-function substituteModuleTokens(outDir: string, req: NativeReqs): void {
-  if (!req.widgetAppGroup) return;
+/** Build-time tokens a module's native source / entitlements may reference — resolved from the app
+ * config so a module ships app-agnostic and the CLI stamps the app-specific value in. Not module-
+ * specific: any module (built-in or pack) can use these tokens. Currently `__APP_GROUP__` → the App
+ * Group id shared by the app + an extension (e.g. widget); extend here as new app-derived needs arise. */
+function buildTokens(cfg: AppwrapConfig): Record<string, string> {
+  return { __APP_GROUP__: `group.${cfg.id}` };
+}
+
+/** Substitute any {@link buildTokens} in a stamped string (entitlement value or native-source file). */
+function substituteBuildTokens(s: string, tokens: Record<string, string>): string {
+  let out = s;
+  for (const [tok, val] of Object.entries(tokens)) out = out.replaceAll(tok, val);
+  return out;
+}
+
+/** Substitute build-time tokens in copied module native source (after copyModuleNativeSrc) — applied
+ * generically to every iOS extension file, so a module's app-agnostic source (e.g. the widget
+ * extension's Swift/entitlements/plist) gets the app-specific value stamped in. Idempotent (source is
+ * re-copied verbatim each sync, then re-substituted). No-op when no extensions were copied. */
+function substituteModuleTokens(outDir: string, cfg: AppwrapConfig): void {
   const extRoot = join(outDir, 'App_Resources/iOS/extensions');
   if (!existsSync(extRoot)) return;
+  const tokens = buildTokens(cfg);
+  let touched = false;
   const subst = (file: string) => {
     const s = readFileSync(file, 'utf8');
-    if (!s.includes('__APP_GROUP__')) return;
-    writeFileSync(file, s.replaceAll('__APP_GROUP__', req.widgetAppGroup!));
+    const next = substituteBuildTokens(s, tokens);
+    if (next !== s) { writeFileSync(file, next); touched = true; }
   };
   const walk = (dir: string) => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -458,7 +699,7 @@ function substituteModuleTokens(outDir: string, req: NativeReqs): void {
     }
   };
   walk(extRoot);
-  console.log(`  tokn ← __APP_GROUP__ = ${req.widgetAppGroup} (widget extension)`);
+  if (touched) console.log(`  tokn ← __APP_GROUP__ = ${tokens.__APP_GROUP__} (extension source)`);
 }
 
 /** Hosts to register as Android App Links (autoVerify https intent-filters). Explicit
@@ -555,7 +796,7 @@ function resolveConfigPath(cwd: string, flags: Record<string, string>): string {
     : (CONFIG_CANDIDATES.map((f) => resolve(cwd, f)).find(existsSync) ?? resolve(cwd, CONFIG_CANDIDATES[0]));
 }
 
-async function loadConfig(cwd: string, flags: Record<string, string>): Promise<AppwrapConfig> {
+export async function loadConfig(cwd: string, flags: Record<string, string>): Promise<AppwrapConfig> {
   const configPath = resolveConfigPath(cwd, flags);
   if (!existsSync(configPath)) {
     console.error(`✖ Config not found — looked for ${CONFIG_CANDIDATES.join(' / ')} in ${cwd}`);
@@ -584,7 +825,7 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   }
 
   // loader:'server' bakes serverUrl into the shell and loads it via NSURL/WKWebView. A scheme-less
-  // value (e.g. "agf.circlesup.com") produces an unusable URL — the app silently fails to load (or
+  // value (e.g. "app.example.com") produces an unusable URL — the app silently fails to load (or
   // shows a stale page) with no error. Normalize to https:// when no scheme is present, and fail loud
   // on a genuinely malformed URL rather than shipping a broken build.
   if (cfg.serverUrl) {
@@ -603,7 +844,7 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   return cfg;
 }
 
-function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
+export function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
   // Resolve the env-switcher block. Absent block OR `enabled:false` → the whole feature is inert
   // (the shell reads `envSwitcher.enabled`). `allowPattern`/`envs` default to empty (default-deny).
   const es = cfg.envSwitcher;
@@ -628,6 +869,7 @@ export const SHELL_CONFIG = {
   loader: ${JSON.stringify(cfg.loader ?? 'app')} as 'app' | 'file' | 'server',
   serverUrl: ${JSON.stringify(cfg.serverUrl ?? '')},
   backendOrigin: ${JSON.stringify(cfg.backendOrigin ?? '')},
+  urlScheme: ${JSON.stringify(cfg.urlScheme ?? '')},
   debug: ${JSON.stringify(cfg.debug ?? false)},
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
   devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
@@ -1391,7 +1633,7 @@ function stampAndroidVersion(outDir: string, cfg: AppwrapConfig): void {
 }
 
 /** Locate the icon source: explicit cfg.icon, else the largest icon in the PWA manifest. */
-function findIconSource(cwd: string, cfg: AppwrapConfig): string | null {
+export function findIconSource(cwd: string, cfg: AppwrapConfig): string | null {
   if (cfg.icon) {
     const p = resolve(cwd, cfg.icon);
     if (existsSync(p)) return p;
@@ -1626,17 +1868,23 @@ export function applyOverrides(cwd: string, outDir: string, cfg: AppwrapConfig):
   const dir = resolve(cwd, cfg.overrides ?? 'appwrap.overrides');
   // Files the template still provides must survive an override removal (regenerateCore ran first and
   // re-copied them) → protect them from the override prune.
-  const templateFiles = existsSync(TEMPLATE_DIR) ? collectRelFiles(TEMPLATE_DIR, templateCopyFilter) : new Set<string>();
+  const templateFiles = allTemplateFiles();
   // ACTIVE modules' native source needs the SAME protection: copyModuleNativeSrc re-copied it into
   // these exact relative paths, but it lives under runtime/modules-native/<name>/, which
   // templateCopyFilter deliberately excludes — so it is absent from templateFiles above. Without this,
   // dropping a consumer override that happened to shadow a module file prunes the MODULE's own copy
   // too (the prune only sees "was in the overrides manifest, isn't in overrides now"), silently
   // deleting e.g. res/xml/appwrap_widget_info.xml and failing the build at AAPT.
-  for (const name of nativeReqs(cfg).nativeSrc) {
+  const reqs = nativeReqs(cfg);
+  for (const name of reqs.nativeSrc) {
     const modDir = join(MODULES_NATIVE_DIR, name);
     if (existsSync(modDir)) for (const rel of collectRelFiles(modDir)) templateFiles.add(rel);
   }
+  // Same protection for active PACK modules' native source (lives under the pack dir, absent from the
+  // template file set) — so an override removal never prunes a pack module's own copied files.
+  for (const { srcDir } of reqs.packNativeSrc) {
+    if (existsSync(srcDir)) for (const rel of collectRelFiles(srcDir)) templateFiles.add(rel);
+  }
   if (!existsSync(dir)) {
     // No overrides now: prune anything a PRIOR overrides run left behind (renamed/removed override files).
     pruneStale(outDir, OVERRIDES_MANIFEST, new Set(), templateFiles);
@@ -1795,12 +2043,27 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
 // so without this a relocated source lingers in native/ and gets re-bundled.
 const TEMPLATE_MANIFEST = '.appwrap-template-manifest.json';
 const OVERRIDES_MANIFEST = '.appwrap-overrides-manifest.json';
+/** Tracks module-owned native source copied into native/ (built-in + pack), so a module DEACTIVATED
+ * since the last sync has its App_Resources files pruned rather than lingering (cpSync never deletes). */
+const MODULE_NATIVE_MANIFEST = '.appwrap-module-native-manifest.json';
 
 /** Files under TEMPLATE_DIR to skip when copying/walking it (deps, build output, PWA staging, per-module
  * native — those are handled selectively elsewhere). Shared by the cpSync filter and the prune walk so
  * the copied set and the pruned set are defined identically. */
-const templateCopyFilter = (src: string): boolean =>
-  !/(?:^|\/)(node_modules|platforms|hooks|app\/www|modules-native)(\/|$)/.test(src.slice(TEMPLATE_DIR.length));
+const templateCopyFilterFor = (root: string) => (src: string): boolean =>
+  !/(?:^|\/)(node_modules|platforms|hooks|app\/www|modules-native)(\/|$)/.test(src.slice(root.length));
+/** Single-root filter for the built-in template (the common path). */
+const templateCopyFilter = templateCopyFilterFor(TEMPLATE_DIR);
+/** Every file the active template roots contribute, relative to each root (deduped across roots) —
+ * the union prune set + override-protection set for the overlay chain. */
+function allTemplateFiles(): Set<string> {
+  const out = new Set<string>();
+  for (const root of TEMPLATE_ROOTS) {
+    if (!existsSync(root)) continue;
+    for (const rel of collectRelFiles(root, templateCopyFilterFor(root))) out.add(rel);
+  }
+  return out;
+}
 
 /** File (not dir) paths under `root`, relative to it, skipping entries `accept` rejects. */
 function collectRelFiles(root: string, accept: (abs: string) => boolean = () => true): Set<string> {
@@ -1851,16 +2114,23 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   if (opts.firstRun && !req.explicit) {
     console.log('  ℹ no `modules` in the appwrap config → all capabilities active. Declare `modules` to shrink the store build (strip unused handlers/perms).');
   }
-  cpSync(TEMPLATE_DIR, outDir, {
-    recursive: true,
-    force: true, // explicit: Bun's cpSync does not overwrite existing files by default
-    // modules-native/ is copied selectively per active module (copyModuleNativeSrc), not wholesale.
-    // Match RELATIVE to TEMPLATE_DIR — when installed from npm, TEMPLATE_DIR itself sits under
-    // node_modules/, so testing the absolute path would wrongly exclude the entire template.
-    filter: templateCopyFilter,
-  });
-  // Delete template files removed/renamed since the last regenerate (cpSync only overwrites, never deletes).
-  pruneStale(outDir, TEMPLATE_MANIFEST, collectRelFiles(TEMPLATE_DIR, templateCopyFilter));
+  // Copy each template root in order — later roots OVERLAY earlier (file-level last-wins), so a
+  // consumer template can add or replace shell files without forking CE. Single root (default) is
+  // exactly the pre-overlay copy.
+  for (const root of TEMPLATE_ROOTS) {
+    if (!existsSync(root)) { console.warn(`⚠ template root not found: ${root}`); continue; }
+    cpSync(root, outDir, {
+      recursive: true,
+      force: true, // explicit: Bun's cpSync does not overwrite existing files by default
+      // modules-native/ is copied selectively per active module (copyModuleNativeSrc), not wholesale.
+      // Match RELATIVE to the root — when installed from npm, a root itself sits under node_modules/,
+      // so testing the absolute path would wrongly exclude the entire template.
+      filter: templateCopyFilterFor(root),
+    });
+  }
+  // Delete template files removed/renamed since the last regenerate (cpSync only overwrites, never
+  // deletes) — pruned against the UNION of all roots' files so an overlay-provided file isn't culled.
+  pruneStale(outDir, TEMPLATE_MANIFEST, allTemplateFiles());
   stampShellConfig(outDir, cfg);
   stampNativeScriptConfig(outDir, cfg);
   stampIOSDisplayName(outDir, cfg, req);
@@ -1872,8 +2142,12 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   stampKotlin(outDir, req.androidKotlin);
   generateModuleArtifacts(outDir, req);
   regenerateMobilePlugins(cwd, cfg, outDir); // config-gated TS plugins → bridge handlers (in-process)
-  copyModuleNativeSrc(outDir, req); // module-owned native source (e.g. health's Kotlin shim)
-  substituteModuleTokens(outDir, req); // stamp __APP_GROUP__ etc. into the copied extension source
+  const moduleNativeFiles = copyModuleNativeSrc(outDir, req); // module-owned native source (e.g. health's Kotlin shim)
+  // Prune a now-inactive module's native files (in the prior manifest, not re-copied this sync). Protect
+  // base-template files so a module that overrode a template App_Resources file, once removed, reverts to
+  // the template copy instead of being deleted outright.
+  pruneStale(outDir, MODULE_NATIVE_MANIFEST, moduleNativeFiles, allTemplateFiles());
+  substituteModuleTokens(outDir, cfg); // stamp __APP_GROUP__ etc. into the copied extension source
   stampLaunchScreen(outDir, cfg);
   stampStoreKit(cwd, outDir, cfg);
   stampPush(cwd, outDir, cfg);
@@ -1908,6 +2182,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
 
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
+  await applyModulePacks(cwd, cfg); // resolve config `modulePacks` (no-op when none) before deriving
   regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
   copyCiTemplates(cwd, outDir, cfg, 'force' in flags, 'ci' in flags); // GH workflows: opt-in (--ci), first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
@@ -1928,6 +2203,7 @@ async function sync(cwd: string, flags: Record<string, string>, cfgOverride?: Ap
     console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first`);
     process.exit(1);
   }
+  await applyModulePacks(cwd, cfg); // resolve config `modulePacks` (no-op when none) before deriving
   regenerateCore(cwd, outDir, cfg, { flags });
   applyOverrides(cwd, outDir, cfg); // overrides win last
   stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
@@ -2002,11 +2278,11 @@ function openInspector(cfg: AppwrapConfig, flags: Record<string, string>, platfo
  */
 async function dev(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
-  if (platform === 'desktop') return devDesktop(cwd, flags);
+  if (platform && cliOptions.platforms?.[platform]) return void await cliOptions.platforms[platform](cwd, flags, positionals, 'dev');
   const sim = 'sim' in flags || positionals[1] === 'sim';
   const wantDebug = 'debug' in flags;
   if (platform !== 'ios' && platform !== 'android') {
-    console.error('Usage: appwrap dev <ios|android|desktop> [--sim] [--detached] [--debug] [--wifi] [--device <id|ip[:port]>] [--url <devserver>|--port <p>]');
+    console.error('Usage: appwrap dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--device <id|ip[:port]>] [--url <devserver>|--port <p>]');
     process.exit(1);
   }
   const cfg = await loadConfig(cwd, flags);
@@ -2040,6 +2316,7 @@ async function dev(cwd: string, flags: Record<string, string>, positionals: stri
       : stamped?.loader === 'server'
         ? { ...cfg, loader: 'server', serverUrl: stamped.serverUrl, debug: stamped.debug }
         : cfg;
+    await applyModulePacks(cwd, simCfg); // resolve config `modulePacks` (no-op when none) before deriving
     regenerateCore(cwd, outDir, simCfg, { flags });
     applyOverrides(cwd, outDir, simCfg); // overrides win last — same order as sync
     stampIOSExtensionVersions(outDir, simCfg); // AFTER overrides: keep extension version matching the app's (Xcode warns on mismatch)
@@ -2378,552 +2655,12 @@ async function watchAndSync(cwd: string, flags: Record<string, string>, outDir:
  * Android signing comes from env (APPWRAP_ANDROID_KEYSTORE[_PASSWORD|_ALIAS|_ALIAS_PASSWORD]) — secrets
  * never live in the appwrap config. iOS distribution signing/upload is the fastlane release lane's job (the
  * cicd templates); `--release` here just builds the Release config for the device. */
-// ─────────────────────────────── desktop (Tauri chassis) lane ────────────────────────────────
-// Phase-0, macOS-only. Mirrors the managed-CNG model of the mobile lanes but far leaner: copy the
-// `runtime-desktop/` template into the app's disposable `native-desktop/`, stamp the app's identity +
-// window shape (shell_config.json, embedded into the Rust binary) and Tauri config (tauri.conf.json),
-// stage the built web dist, then `cargo run`/`build`. The template is canonical; `native-desktop/` is
-// gitignored + regenerated each run (framework edits propagate — same contract as `native/`).
-
-/** Fail clearly on non-macOS — the desktop chassis is macOS-only for phase-0 (osascript dialogs/
- * notifications, `open`, the app-data path are all macOS). */
-function ensureDesktopMacOS(): void {
-  if (process.platform !== 'darwin') {
-    console.error(`✖ appwrap desktop is macOS-only for now (phase-0). Detected platform: ${process.platform}.`);
-    process.exit(1);
-  }
-}
-
-/** Skip the heavy/generated dirs when copying the desktop template (Rust build output + Tauri codegen +
- * deps): they regenerate, and `target/` alone is GBs. Matches RELATIVE to the template root. */
-function desktopCopyFilter(src: string): boolean {
-  const rel = src.slice(DESKTOP_TEMPLATE_DIR.length);
-  return !/(^|\/)(target|gen|node_modules)(\/|$)/.test(rel);
-}
-
-/** Resolve a `desktop.server.command` to an absolute path: an absolute/relative path is resolved
- * against the app root; a bare name is looked up on `path` (build-time PATH). Falls back to the bare
- * name (the Rust shell will surface the spawn ENOENT) when it's nowhere. */
-function resolveServerCommand(command: string, cwd: string, path: string): string {
-  if (command.includes('/')) return resolve(cwd, command);
-  for (const dir of path.split(pathDelimiter).filter(Boolean)) {
-    const abs = join(dir, command);
-    if (existsSync(abs)) return abs;
-  }
-  return command;
-}
-
-/** The bundled splash shown while a local-server app boots (before the shell navigates to the live
- * server). A dependency-free, theme-neutral holding page. */
-function desktopSplashHtml(name: string): string {
-  const safe = name.replace(/</g, '&lt;').replace(/&/g, '&amp;');
-  return `<!doctype html><html><head><meta charset="utf-8"><title>${safe}</title>
-<style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;
-flex-direction:column;gap:20px;background:#0b0b0f;color:#e5e5e5;font:14px -apple-system,system-ui,sans-serif}
-.s{width:34px;height:34px;border:3px solid #333;border-top-color:#888;border-radius:50%;animation:r .8s linear infinite}
-@keyframes r{to{transform:rotate(360deg)}}#e{color:#f87171;max-width:70%;text-align:center;line-height:1.5}</style>
-</head><body><div class="s" id="spin"></div><div id="m">Starting ${safe}…</div><div id="e"></div></body></html>`;
-}
-
-/** Copy the desktop template into `native-desktop/` and stamp it from the config: the Rust-read
- * `shell_config.json` (identity + window), `tauri.conf.json` (productName/version/identifier +
- * frontendDist), and the staged web dist (`native-desktop/dist`, referenced as `../dist`). */
-/**
- * Make `cfg.plugins` LIVE (A.1 loader): resolve each entry (path OR npm package), bun-build its
- * entrypoint to a single embedded file under `native-desktop/plugins/`, bun-build the multiplexed
- * plugin-host once, and stamp `{ pluginHost, plugins:[{bundleId, attachTo, bundlePath}] }` into the
- * shell config. The Rust shell (plugin_host.rs) spawns the host with the stamped plugins at boot.
- *
- * A.1 scope: manifest/perms/native-deps merge is STUBBED (noted) — full `capabilities.manifest.ts`
- * reuse (perms/entitlements union) lands later. `bundleId` here is the file/package basename (a
- * pre-load build id for the bundle filename only); the authoritative routing/diagnostic identifier is
- * the plugin def's `name`, which the host reads from the bundle after `import()`.
- */
-export function regeneratePlugins(cwd: string, cfg: AppwrapConfig, outDir: string, shell: DesktopShellConfig): void {
-  const entries = cfg.plugins ?? [];
-  if (entries.length === 0) return;
-  const outPlugins = join(outDir, 'plugins');
-  mkdirSync(outPlugins, { recursive: true });
-  const bun = process.execPath; // the CLI runs under bun → the exact runtime to build/spawn with
-
-  const bunBuild = (entrypoint: string, outfile: string): boolean => {
-    try {
-      execFileSync(bun, ['build', entrypoint, '--target=bun', '--outfile', outfile], { stdio: 'pipe' });
-      return true;
-    } catch (e: unknown) {
-      console.warn(`⚠ plugin bun-build failed (${entrypoint}): ${e instanceof Error ? e.message : String(e)}`);
-      return false;
-    }
-  };
-
-  // Build the host bundle once (from THIS package's src/plugin/host.ts).
-  const hostSrc = resolve(import.meta.dir, 'plugin', 'host.ts');
-  const hostOut = join(outPlugins, 'host.js');
-  if (!bunBuild(hostSrc, hostOut)) {
-    console.warn('⚠ plugin host failed to build — plugins disabled for this build.');
-    return;
-  }
-
-  const stamped: DesktopShellConfig['plugins'] = [];
-  for (const raw of entries) {
-    const name = typeof raw === 'string' ? raw : raw.name;
-    const attachTo = typeof raw === 'string' ? undefined : raw.attachTo;
-    // Resolve: an existing path (relative to the app root) wins; else treat as an npm package name.
-    let entrypoint = resolve(cwd, name);
-    if (!existsSync(entrypoint)) {
-      try {
-        entrypoint = (Bun as unknown as { resolveSync(id: string, parent: string): string }).resolveSync(name, cwd);
-      } catch {
-        console.warn(`⚠ plugin "${name}" not found (no such path, not resolvable as an npm package) — skipping.`);
-        continue;
-      }
-    }
-    const bundleId = name.replace(/[^a-zA-Z0-9_-]/g, '_');
-    const bundlePath = join(outPlugins, `${bundleId}.js`);
-    if (!bunBuild(entrypoint, bundlePath)) continue;
-    stamped.push({ bundleId, attachTo, bundlePath });
-    console.log(`  plugin ← ${name}  (attachTo: ${attachTo ?? 'def-declared'})`);
-  }
-
-  if (stamped.length > 0) {
-    shell.pluginHost = hostOut;
-    shell.plugins = stamped;
-    // TODO(A.x): read each plugin's `manifest` and merge perms/entitlements/native-deps via
-    // generateModuleArtifacts + capabilities.manifest.ts (plugins are manifest-compatible with modules).
-  }
-}
-
-function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, pushSigned = false): void {
-  if (!existsSync(DESKTOP_TEMPLATE_DIR)) {
-    console.error(`✖ Desktop template not found at ${DESKTOP_TEMPLATE_DIR}`);
-    process.exit(1);
-  }
-  const srcTauri = join(outDir, 'src-tauri');
-  mkdirSync(outDir, { recursive: true });
-  cpSync(DESKTOP_TEMPLATE_DIR, outDir, { recursive: true, force: true, filter: desktopCopyFilter });
-  // `native-desktop/` is generated + disposable (regenerated from the template on every build) — mark
-  // the whole tree git-invisible so a consuming repo never commits generated native code (incl. the
-  // copied `crates/` + `src-tauri/`). A self-ignoring `*` .gitignore works regardless of the app's root
-  // .gitignore; mirrors the mobile lane's disposable-`native/` convention. Written AFTER cpSync so it wins.
-  writeFileSync(join(outDir, '.gitignore'), '*\n');
-
-  const shell = deriveDesktopConfig(cfg);
-  shell.pushSigned = pushSigned;
-
-  // Stage the frontendDist INTO the wrapper (mirrors mobile copyPwa) so it's a stable relative path
-  // independent of where the app project sits. Local-server apps (`desktop.server`) have no meaningful
-  // web dist — the window loads the live server — so we stage a tiny bundled SPLASH instead (shown
-  // while the server boots, then the shell navigates away from it).
-  const stagedDist = join(outDir, 'dist');
-  rmSync(stagedDist, { recursive: true, force: true });
-  if (shell.server) {
-    mkdirSync(stagedDist, { recursive: true });
-    writeFileSync(join(stagedDist, 'index.html'), desktopSplashHtml(shell.name));
-  } else {
-    const dist = resolve(cwd, cfg.pwaDist);
-    if (!existsSync(dist)) {
-      console.error(`✖ Web dist not found at ${dist} — build the PWA first (or check pwaDist).`);
-      process.exit(1);
-    }
-    cpSync(dist, stagedDist, { recursive: true, force: true });
-  }
-
-  // Stage the app-owned browser sub-window chrome (‹ › ⟳ + address bar + profile▾) INTO the dist so
-  // `WebviewUrl::App("appwrap-browser-chrome.html")` resolves it (browser_tab::browser_subwindow_open).
-  const chromeSrc = join(DESKTOP_TEMPLATE_DIR, 'chrome', 'appwrap-browser-chrome.html');
-  if (existsSync(chromeSrc)) {
-    copyFileSync(chromeSrc, join(stagedDist, 'appwrap-browser-chrome.html'));
-  } else {
-    console.warn(`⚠ browser chrome not found at ${chromeSrc} — sub-window chrome will 404.`);
-  }
-
-  // Local-server mode: resolve `command` (bare name → PATH lookup) and `cwd` to ABSOLUTE, and stamp
-  // the build-time PATH — a GUI-launched .app inherits the minimal launchd PATH (no ~/.bun/bin), so
-  // a bare-name spawn (or a child that itself shells out to `bun`/`node`) would fail there.
-  if (shell.server) {
-    const s = shell.server;
-    s.cwd = s.cwd ? resolve(cwd, s.cwd) : cwd;
-    s.command = resolveServerCommand(s.command, cwd, process.env.PATH ?? '');
-    s.path = process.env.PATH ?? '';
-    if (!existsSync(s.command)) {
-      console.warn(`⚠ desktop.server.command not found (${s.command}) — the server will fail to spawn at launch.`);
-    }
-  }
-  // Resolve the handlers path to ABSOLUTE (against the app root): the shell binary runs from a
-  // different cwd, and for `build desktop` the .app runs from wherever it's installed — an absolute
-  // path is the only one that stays valid. The handler file is NOT copied into the wrapper/.app; the
-  // app dir (with its node_modules) must remain present at runtime (documented in the config type).
-  if (shell.handlers) {
-    const abs = resolve(cwd, shell.handlers);
-    if (!existsSync(abs)) {
-      console.warn(`⚠ desktop.handlers points to a missing file (${abs}) — the sidecar will not spawn.`);
-    }
-    shell.handlers = abs;
-    // Stamp the ABSOLUTE Bun binary the sidecar must be spawned with: the CLI itself runs under bun,
-    // so process.execPath IS the exact runtime the app was built with. A GUI-launched .app inherits
-    // the launchd PATH (no ~/.bun/bin), so the Rust shell can't rely on a bare `bun` lookup.
-    shell.handlersRuntime = process.execPath;
-  }
-  // Resolve + bun-build the configured plugins (make `cfg.plugins` LIVE). Runs BEFORE writing
-  // shell_config (and before applyOverrides, which happens after regenerateDesktop returns) so the
-  // stamped plugin bundles + host are embedded and the .app is self-contained.
-  regeneratePlugins(cwd, cfg, outDir, shell);
-  writeFileSync(join(srcTauri, 'shell_config.json'), JSON.stringify(shell, null, 2) + '\n');
-
-  const tauriConfPath = join(srcTauri, 'tauri.conf.json');
-  const template = JSON.parse(readFileSync(tauriConfPath, 'utf8')) as Record<string, unknown>;
-  const stamped = stampTauriConf(template, shell, '../dist'); // relative to src-tauri/
-  writeFileSync(tauriConfPath, JSON.stringify(stamped, null, 2) + '\n');
-
-  stampDesktopRuntimeIcon(cwd, cfg, join(srcTauri, 'icons', 'icon.png'));
-}
-
-/** Stamp the Tauri RUNTIME icon (`src-tauri/icons/icon.png`, embedded via `generate_context!`) from
- * the app's real icon — else it OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock with the template
- * placeholder square. Downscale to 512 via sips → round the macOS app-icon corners + ensure RGBA (our
- * dependency-free codec) → write. On any failure, keep the template placeholder (Tauri needs *some*
- * RGBA icon.png to compile) and warn — never fail the build over an icon. */
-function stampDesktopRuntimeIcon(cwd: string, cfg: AppwrapConfig, destPng: string): void {
-  const source = findIconSource(cwd, cfg);
-  if (!source) return; // no cfg.icon / manifest icon → keep template placeholder
-  const tmpPng = join(tmpdir(), `appwrap-desktop-icon-${Date.now()}.png`);
-  try {
-    // Artwork at Apple's icon-grid fraction of the canvas, then pad — full-bleed runtime icons
-    // render visibly larger than bundle-masked Dock neighbors (no OS-applied margin/mask).
-    const art = Math.round(512 * APPLE_ICON_GRID_SCALE);
-    execFileSync('sips', ['-s', 'format', 'png', '-z', String(art), String(art), source, '--out', tmpPng], { stdio: 'ignore' });
-    writeFileSync(destPng, makeDockRuntimeIcon(readFileSync(tmpPng), 512));
-    console.log(`  desktop runtime icon ← ${source} (${art}² rounded on 512² canvas)`);
-  } catch (e: unknown) {
-    console.warn(`⚠ desktop runtime icon stamp failed (${e instanceof Error ? e.message : String(e)}) — keeping placeholder`);
-  } finally {
-    rmSync(tmpPng, { force: true });
-  }
-}
-
-/** Shared target dir for the desktop crate — reuse the template's warm `target/` so a stamped copy
- * builds incrementally (~seconds) instead of a ~4-min cold compile of the Tauri dep tree. */
-/** Resolve a spawnable `cargo` (bin + PATH-augmented env) for the desktop lane. rustup installs into
- * `~/.cargo/bin`, which a GUI/login shell often lacks on PATH → a bare spawn throws a raw ENOENT. We
- * append it when the binary lives there, else fail with an actionable install/source message. */
-function desktopCargo(): { bin: string; env: NodeJS.ProcessEnv } {
-  const home = process.env.HOME ?? '';
-  const res = resolveCargoPath({
-    path: process.env.PATH ?? '',
-    home,
-    delimiter: pathDelimiter,
-    hasCargo: (dir) => existsSync(join(dir, 'cargo')),
-  });
-  if (!res.found) {
-    console.error(
-      `✖ cargo not found on PATH${home ? ` (and no ${home}/.cargo/bin/cargo)` : ''}.\n` +
-        `  Install the Rust toolchain via rustup:  https://rustup.rs\n` +
-        `  If it's already installed, add it to this shell:  source "$HOME/.cargo/env"`
-    );
-    process.exit(1);
-  }
-  if (res.augmented) console.log(`  cargo ← ${home}/.cargo/bin (appended to PATH; not in your shell's PATH)`);
-  return {
-    bin: res.bin,
-    env: { ...process.env, PATH: res.path, CARGO_TARGET_DIR: join(DESKTOP_TEMPLATE_DIR, 'src-tauri/target') },
-  };
-}
-
-/** `appwrap dev desktop` — stamp the wrapper + `cargo run` (launches the window; blocks until closed). */
-async function devDesktop(cwd: string, flags: Record<string, string>): Promise<void> {
-  ensureDesktopMacOS();
-  const cfg = await loadConfig(cwd, flags);
-  const outDir = resolve(cwd, flags.out ?? 'native-desktop');
-  buildWebIfBundled(cwd, cfg, flags);
-  regenerateDesktop(cwd, cfg, outDir);
-  const { bin, env } = desktopCargo();
-  console.log(`▶ cargo run  (appwrap desktop shell — ${cfg.name})`);
-  execFileSync(bin, ['run'], { cwd: join(outDir, 'src-tauri'), stdio: 'inherit', env });
-}
-
-/** Generate `AppIcon.icns` from the app's icon PNG via `sips` + `iconutil` (macOS-only, like the whole
- * desktop lane). Returns the icns basename, or null when no icon source / tooling — skip gracefully. */
-function generateMacIcns(cwd: string, cfg: AppwrapConfig, resourcesDir: string): string | null {
-  const source = findIconSource(cwd, cfg);
-  if (!source) return null;
-  const iconset = join(tmpdir(), `appwrap-icns-${Date.now()}.iconset`);
-  mkdirSync(iconset, { recursive: true });
-  try {
-    for (const px of [16, 32, 128, 256, 512]) {
-      execFileSync('sips', ['-z', String(px), String(px), source, '--out', join(iconset, `icon_${px}x${px}.png`)], { stdio: 'ignore' });
-      execFileSync('sips', ['-z', String(px * 2), String(px * 2), source, '--out', join(iconset, `icon_${px}x${px}@2x.png`)], { stdio: 'ignore' });
-    }
-    execFileSync('iconutil', ['-c', 'icns', iconset, '-o', join(resourcesDir, 'AppIcon.icns')], { stdio: 'ignore' });
-    return 'AppIcon.icns';
-  } catch (e: unknown) {
-    console.warn(`⚠ icns generation failed (${e instanceof Error ? e.message : String(e)}) — .app ships without an icon`);
-    return null;
-  } finally {
-    rmSync(iconset, { recursive: true, force: true });
-  }
-}
-
-/** Compile a Tahoe-native `Assets.car` (+ its own `AppIcon.icns`) from the app's icon via `actool`,
- * into `resourcesDir`. macOS 26 (Tahoe) resolves a bundle's Finder/Dock icon through
- * `CFBundleIconName` + `Assets.car`, NOT the legacy top-level `.icns`. Returns the asset icon name
- * (`AppIcon`) on success, or null when there's no icon / `xcrun`/`actool` is unavailable or fails —
- * caller then keeps the iconutil `.icns` path (fine pre-26; Tahoe Finder icon may look generic). */
-function compileMacAssetsCar(cwd: string, cfg: AppwrapConfig, resourcesDir: string): string | null {
-  const source = findIconSource(cwd, cfg);
-  if (!source) return null;
-  const work = join(tmpdir(), `appwrap-actool-${Date.now()}`);
-  const xcassets = join(work, 'Assets.xcassets');
-  const iconset = join(xcassets, 'AppIcon.appiconset');
-  try {
-    mkdirSync(iconset, { recursive: true });
-    // 10 macOS reps: 16/32/128/256/512 pt at @1x and @2x.
-    const reps = [16, 32, 128, 256, 512].flatMap((pt) => [
-      { pt, scale: 1, px: pt },
-      { pt, scale: 2, px: pt * 2 },
-    ]);
-    const images = reps.map(({ pt, scale, px }) => {
-      const filename = `icon_${pt}x${pt}@${scale}x.png`;
-      execFileSync('sips', ['-s', 'format', 'png', '-z', String(px), String(px), source, '--out', join(iconset, filename)], { stdio: 'ignore' });
-      return { idiom: 'mac', size: `${pt}x${pt}`, scale: `${scale}x`, filename };
-    });
-    writeFileSync(join(iconset, 'Contents.json'), JSON.stringify({ images, info: { version: 1, author: 'appwrap' } }, null, 2));
-    writeFileSync(join(xcassets, 'Contents.json'), JSON.stringify({ info: { version: 1, author: 'appwrap' } }, null, 2));
-
-    const partialPlist = join(work, 'partial.plist');
-    execFileSync('xcrun', ['actool', xcassets,
-      '--compile', resourcesDir,
-      '--platform', 'macosx',
-      '--target-device', 'mac',
-      '--minimum-deployment-target', '11.0',
-      '--app-icon', 'AppIcon',
-      '--output-partial-info-plist', partialPlist,
-    ], { stdio: 'ignore' });
-
-    if (!existsSync(join(resourcesDir, 'Assets.car'))) throw new Error('actool produced no Assets.car');
-    return 'AppIcon';
-  } catch (e: unknown) {
-    console.warn(`⚠ actool Assets.car compile skipped (${e instanceof Error ? e.message : String(e)}) — Tahoe Finder icon may look generic; legacy .icns kept`);
-    return null;
-  } finally {
-    rmSync(work, { recursive: true, force: true });
-  }
-}
-
-/** Resolved macOS signing lane. `identity` is the cert SHA-1 hash (fed to codesign — unambiguous,
- * unlike a CN which can collide); `cn` is kept for logging; `kind` records the cert class. The
- * aps-environment is NOT derived from `kind` — it comes from the provisioning profile itself. */
-interface MacSigning { identity: string; cn: string; kind: 'developer-id' | 'development'; teamId: string }
-
-/** A matched macOS profile + its own aps-environment entitlement. */
-interface MacProfileMatch { path: string; apsEnvironment?: string }
-
-/** Resolve a real code-signing identity for the desktop lane. Team precedence mirrors stampTeamId:
- * non-placeholder cfg.teamId → $APPWRAP_TEAM_ID → none (adhoc). Identity preference within the team:
- * "Developer ID Application" (direct distribution) → "Apple Development" (local/dev). The CN of a
- * dev cert does NOT carry the team id — match via the certificate's OU field. Returns null (→ adhoc
- * fallback) when no team is set or no identity of either class belongs to it. */
-function resolveMacSigning(cfg: AppwrapConfig): MacSigning | null {
-  const teamId = (!cfg.teamId || /YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId))
-    ? process.env.APPWRAP_TEAM_ID?.trim() || null
-    : cfg.teamId;
-  if (!teamId) return null;
-  let listing = '';
-  try {
-    listing = execFileSync('security', ['find-identity', '-v', '-p', 'codesigning'], { encoding: 'utf8' });
-  } catch { return null; }
-  // find-identity -v lines: `  1) <40-hex-SHA1> "<CN>"`. Capture BOTH — codesign is fed the hash.
-  const entries = [...listing.matchAll(/\b([0-9A-F]{40})\s+"([^"]+)"/g)].map((m) => ({ hash: m[1], cn: m[2] }));
-  const teamOf = (cn: string): string | null => {
-    try {
-      const pem = execFileSync('security', ['find-certificate', '-c', cn, '-p'], { encoding: 'utf8' });
-      const subject = execFileSync('openssl', ['x509', '-noout', '-subject'], { input: pem, encoding: 'utf8' });
-      return subject.match(/OU\s*=\s*([A-Z0-9]{10})/)?.[1] ?? null;
-    } catch { return null; }
-  };
-  for (const prefix of ['Developer ID Application', 'Apple Development'] as const) {
-    const match = entries.find((e) => e.cn.startsWith(prefix) && teamOf(e.cn) === teamId);
-    if (match) return { identity: match.hash, cn: match.cn, kind: prefix === 'Developer ID Application' ? 'developer-id' : 'development', teamId };
-  }
-  return null;
-}
-
-/** Find an installed, unexpired macOS provisioning profile for `<teamId>.<bundleId>`. macOS profiles
- * are `.provisionprofile` (same CMS envelope as iOS `.mobileprovision`; findProvisioningProfiles only
- * scans the latter, so this is the mac twin). Returns the file path, or null (→ sign without the
- * restricted push entitlement — a restricted entitlement with no embedded profile kills the app at
- * launch, which is strictly worse than a signed app without push). */
-function findMacProvisionProfile(teamId: string, bundleId: string, signingCertHash?: string): MacProfileMatch | null {
-  const dirs = [
-    join(process.env.HOME ?? '', 'Library/MobileDevice/Provisioning Profiles'),
-    join(process.env.HOME ?? '', 'Library/Developer/Xcode/UserData/Provisioning Profiles'),
-  ];
-  const wanted = signingCertHash?.toUpperCase();
-  for (const dir of dirs) {
-    if (!existsSync(dir)) continue;
-    let files: string[] = [];
-    try { files = readdirSync(dir).filter((f) => f.endsWith('.provisionprofile')); } catch { continue; }
-    for (const f of files) {
-      try {
-        const raw = execFileSync('security', ['cms', '-D', '-i', join(dir, f)],
-          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-        const info = parseMacProfile(raw);
-        const { teamId: team, appId, expiration } = info;
-        if (team !== teamId || !appId) continue;
-        if (expiration && Date.parse(expiration) < Date.now()) continue;
-        const profBundle = appId.startsWith(team + '.') ? appId.slice(team.length + 1) : appId;
-        if (profBundle !== bundleId && profBundle !== '*') continue;
-        // The chosen signing cert MUST be one the profile authorizes (DER SHA-1 == find-identity hash),
-        // else codesign succeeds but the app launch is rejected. Mismatch → warn + keep scanning.
-        if (wanted) {
-          const authorized = info.certificates.some(
-            (b64) => createHash('sha1').update(Buffer.from(b64, 'base64')).digest('hex').toUpperCase() === wanted,
-          );
-          if (!authorized) {
-            console.log(`  ⚠ profile ${f} does not authorize the chosen signing certificate — skipping`);
-            continue;
-          }
-        }
-        return { path: join(dir, f), apsEnvironment: info.apsEnvironment };
-      } catch { /* skip unreadable profile */ }
-    }
-  }
-  return null;
-}
-
-/** Assemble a double-clickable `<Name>.app` around the built shell binary. The Info.plist's
- * CFBundleURLTypes is what registers `urlScheme` with LaunchServices — a bare binary can't receive
- * `<scheme>://…` opens (tauri-plugin-deep-link needs the bundle). Signed with a real identity +
- * entitlements + embedded profile when teamId resolves (resolveMacSigning); ad-hoc otherwise. */
-function assembleMacApp(cwd: string, cfg: AppwrapConfig, shell: DesktopShellConfig, outDir: string, binary: string,
-  lane?: { signing: MacSigning | null; profile: MacProfileMatch | null }): string {
-  const appDir = join(outDir, 'dist-app', `${shell.name}.app`);
-  const macosDir = join(appDir, 'Contents/MacOS');
-  const resourcesDir = join(appDir, 'Contents/Resources');
-  rmSync(appDir, { recursive: true, force: true });
-  mkdirSync(macosDir, { recursive: true });
-  mkdirSync(resourcesDir, { recursive: true });
-  cpSync(binary, join(macosDir, shell.name));
-  const iconFile = generateMacIcns(cwd, cfg, resourcesDir) ?? undefined;
-  // Also compile a Tahoe-native Assets.car (macOS 26 reads CFBundleIconName/Assets.car, not the .icns).
-  // actool emits its own AppIcon.icns alongside — let it replace the iconutil one when present.
-  const iconName = compileMacAssetsCar(cwd, cfg, resourcesDir) ?? undefined;
-  writeFileSync(join(appDir, 'Contents/Info.plist'), buildInfoPlist(shell, shell.name, iconFile, iconName));
-  const signing = lane ? lane.signing : resolveMacSigning(cfg);
-  if (signing) {
-    // Signed lane: real identity; when an installed macOS profile matches, embed it and claim the
-    // push entitlement (restricted → only launches profile-backed). Developer ID gets the hardened
-    // runtime (notarization prerequisite; harmless otherwise).
-    const profile = lane ? lane.profile : findMacProvisionProfile(signing.teamId, shell.identifier, signing.identity);
-    if (profile) cpSync(profile.path, join(appDir, 'Contents/embedded.provisionprofile'));
-    else console.log(`  ⓘ no macOS provisioning profile installed for ${signing.teamId}.${shell.identifier} — signing without entitlements (cert only)`);
-    // aps-environment comes from the PROFILE's own entitlement, not the cert kind — a Developer ID cert
-    // paired with a development profile must claim `development`, or the app is killed at launch.
-    const aps = profile?.apsEnvironment;
-    if (profile && aps !== 'development' && aps !== 'production') {
-      console.log(`  ⓘ profile has no aps-environment entitlement — signing without push`);
-    }
-    const args = ['--force', '--deep', '-s', signing.identity];
-    // Entitlements ONLY when a profile backs them: application-identifier/team-identifier are
-    // RESTRICTED — claiming them without an embedded profile makes macOS refuse to launch the app
-    // ("can't be opened"). No profile → plain cert signature (launches fine, no push).
-    if (profile) {
-      const entitlements = buildMacEntitlements({
-        teamId: signing.teamId,
-        bundleId: shell.identifier,
-        apsEnvironment: aps === 'development' || aps === 'production' ? aps : undefined,
-      });
-      const entFile = join(outDir, 'dist-app', `${shell.name}.entitlements`);
-      writeFileSync(entFile, entitlements);
-      args.push('--entitlements', entFile);
-    }
-    if (signing.kind === 'developer-id') args.push('--options', 'runtime', '--timestamp');
-    console.log(`▶ codesign (${signing.cn} [${signing.identity}]${profile ? ', profile embedded' : ''})`);
-    execFileSync('codesign', [...args, appDir], { stdio: 'inherit' });
-  } else {
-    // Ad-hoc sign so Gatekeeper/LaunchServices treat the bundle as intact on this machine.
-    // Only flag a skip when a REAL team was requested (placeholder teamId = signing never asked for).
-    const requested = process.env.APPWRAP_TEAM_ID?.trim() || (cfg.teamId && !/YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId) ? cfg.teamId : '');
-    if (requested) console.log(`  ⓘ signed lane skipped — no Developer ID / Apple Development identity for team ${requested}; ad-hoc signing`);
-    execFileSync('codesign', ['--force', '--deep', '-s', '-', appDir], { stdio: 'inherit' });
-  }
-  return appDir;
-}
-
-/** Opt-in notarization (env `APPWRAP_NOTARIZE=1`, off by default). Requires the Developer ID signed
- * lane — assembleMacApp already signs it with `--options runtime --timestamp` (hardened runtime +
- * secure timestamp, both notarization prerequisites; no get-task-allow is ever claimed). Credentials:
- * `APPWRAP_NOTARY_KEYCHAIN_PROFILE` (a `notarytool store-credentials` profile) or an ASC API key —
- * `APPWRAP_NOTARY_KEY_ID` + `APPWRAP_NOTARY_ISSUER` (+ optional `APPWRAP_NOTARY_KEY` p8 path,
- * default ~/.appstoreconnect/private_keys/AuthKey_<id>.p8). */
-function notarizeMacApp(appDir: string, signing: MacSigning | null): void {
-  if (process.env.APPWRAP_NOTARIZE !== '1') return;
-  if (!signing || signing.kind !== 'developer-id') {
-    console.error(`✖ APPWRAP_NOTARIZE=1 needs a Developer ID signed .app (current lane: ${signing ? signing.kind : 'ad-hoc'}) — install a "Developer ID Application" identity for the team and rebuild`);
-    process.exit(1);
-  }
-  const kcProfile = process.env.APPWRAP_NOTARY_KEYCHAIN_PROFILE?.trim();
-  const keyId = process.env.APPWRAP_NOTARY_KEY_ID?.trim();
-  const issuer = process.env.APPWRAP_NOTARY_ISSUER?.trim();
-  const keyPath = process.env.APPWRAP_NOTARY_KEY?.trim()
-    || (keyId ? join(process.env.HOME ?? '', `.appstoreconnect/private_keys/AuthKey_${keyId}.p8`) : '');
-  let auth: string[];
-  if (kcProfile) auth = ['--keychain-profile', kcProfile];
-  else if (keyId && issuer) {
-    if (!existsSync(keyPath)) {
-      console.error(`✖ notarization: ASC API key file not found at ${keyPath} (set APPWRAP_NOTARY_KEY to the .p8 path)`);
-      process.exit(1);
-    }
-    auth = ['--key', keyPath, '--key-id', keyId, '--issuer', issuer];
-  } else {
-    console.error('✖ APPWRAP_NOTARIZE=1 but no credentials — set APPWRAP_NOTARY_KEY_ID + APPWRAP_NOTARY_ISSUER (ASC API key) or APPWRAP_NOTARY_KEYCHAIN_PROFILE (notarytool store-credentials)');
-    process.exit(1);
-  }
-  const zip = `${appDir}.notarize.zip`;
-  rmSync(zip, { force: true });
-  execFileSync('ditto', ['-c', '-k', '--keepParent', appDir, zip], { stdio: 'inherit' });
-  console.log('▶ notarytool submit --wait  (Apple-side processing — can take several minutes)');
-  try {
-    execFileSync('xcrun', ['notarytool', 'submit', zip, ...auth, '--wait'], { stdio: 'inherit' });
-    execFileSync('xcrun', ['stapler', 'staple', appDir], { stdio: 'inherit' });
-  } finally {
-    rmSync(zip, { force: true });
-  }
-  console.log(`✓ Notarized + stapled: ${appDir}`);
-}
-
-/** `appwrap build desktop` — stamp the wrapper, `cargo build --release`, then assemble the `.app`. */
-async function buildDesktop(cwd: string, flags: Record<string, string>): Promise<void> {
-  ensureDesktopMacOS();
-  const cfg = await loadConfig(cwd, flags);
-  const outDir = resolve(cwd, flags.out ?? 'native-desktop');
-  // Local-server apps load the live server, not a bundled web build — skip it (regenerateDesktop
-  // stages a boot splash for them). Otherwise build/stage the PWA as usual.
-  if (!cfg.desktop?.server) buildWebIfBundled(cwd, cfg, flags);
-  // Resolve the signing lane BEFORE regeneration: shell_config.json is embedded at compile time,
-  // and the Rust shell's push capability must only claim 'native' when the .app really ships the
-  // profile-backed aps-environment entitlement (signed lane + installed macOS profile).
-  const signing = resolveMacSigning(cfg);
-  const shellCfg = deriveDesktopConfig(cfg);
-  const profile = signing ? findMacProvisionProfile(signing.teamId, shellCfg.identifier, signing.identity) : null;
-  // Only let the Rust shell claim NATIVE push when the app will actually ship a profile-backed
-  // aps-environment entitlement (profile matched AND it carries the entitlement).
-  const nativePush = !!(signing && profile && (profile.apsEnvironment === 'development' || profile.apsEnvironment === 'production'));
-  regenerateDesktop(cwd, cfg, outDir, nativePush);
-  const { bin, env } = desktopCargo();
-  console.log(`▶ cargo build --release  (appwrap desktop shell — ${cfg.name})`);
-  execFileSync(bin, ['build', '--release'], { cwd: join(outDir, 'src-tauri'), stdio: 'inherit', env });
-  const binary = join(DESKTOP_TEMPLATE_DIR, 'src-tauri/target/release/appwrap-desktop-shell');
-  console.log(`✓ Desktop binary: ${binary}`);
-  const appDir = assembleMacApp(cwd, cfg, shellCfg, outDir, binary, { signing, profile });
-  console.log(`✓ App bundle: ${appDir}`);
-  notarizeMacApp(appDir, signing);
-}
 
 async function build(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
-  if (platform === 'desktop') return buildDesktop(cwd, flags);
+  if (platform && cliOptions.platforms?.[platform]) return void await cliOptions.platforms[platform](cwd, flags, positionals, 'build');
   if (platform !== 'ios' && platform !== 'android') {
-    console.error('Usage: appwrap build <ios|android|desktop> [--release] [--aab] [--config <path>] [--out native]');
+    console.error('Usage: appwrap build <ios|android> [--release] [--aab] [--config <path>] [--out native]');
     process.exit(1);
   }
   const outDir = resolve(cwd, flags.out ?? 'native');
@@ -3277,8 +3014,8 @@ function pinTeamIdToConfig(configPath: string, teamId: string): void {
  * `app/www` (PWA staging) is build OUTPUT and `node_modules`/`platforms`/`hooks` are generated, so all four
  * would make the hash unstable across runs. Matched RELATIVE to TEMPLATE_DIR: when installed from npm
  * TEMPLATE_DIR itself lives under node_modules/, and testing the absolute path would exclude everything. */
-const templateFingerprintFilter = (src: string): boolean =>
-  !/(?:^|\/)(node_modules|platforms|hooks|app\/www)(\/|$)/.test(src.slice(TEMPLATE_DIR.length));
+const templateFingerprintFilterFor = (root: string) => (src: string): boolean =>
+  !/(?:^|\/)(node_modules|platforms|hooks|app\/www)(\/|$)/.test(src.slice(root.length));
 
 /** Cheap fingerprint of SOURCE build inputs: mtime sum of the PWA dist/ + appwrap config + the appwrap
  * `runtime/` template tree + this CLI's version.
@@ -3317,12 +3054,16 @@ function buildInputStats(cwd: string, cfg: { pwaDist?: string; overrides?: strin
   const distDir = cfg.pwaDist ? resolve(cwd, cfg.pwaDist) : join(cwd, 'dist');
   const overridesDir = resolve(cwd, cfg.overrides ?? 'appwrap.overrides');
   const stats = [mtimeStats(distDir), mtimeStats(overridesDir), mtimeStats(resolveConfigPath(cwd, flags))];
-  // The appwrap runtime template — bundled into bundle.js, so it is a first-class build input.
+  // The appwrap runtime template(s) — bundled into bundle.js, so a first-class build input. Every
+  // overlay root counts, so editing a host-provided template file busts the cache.
   let runtime = 0, runtimeNewest = 0;
-  for (const rel of collectRelFiles(TEMPLATE_DIR, templateFingerprintFilter)) {
-    const s = mtimeStats(join(TEMPLATE_DIR, rel));
+  for (const root of TEMPLATE_ROOTS) {
+   if (!existsSync(root)) continue;
+   for (const rel of collectRelFiles(root, templateFingerprintFilterFor(root))) {
+    const s = mtimeStats(join(root, rel));
     runtime += s.sum;
     if (s.newest > runtimeNewest) runtimeNewest = s.newest;
+   }
   }
   stats.push({ sum: runtime, newest: runtimeNewest });
   return { parts: stats.map((s) => s.sum), newest: Math.max(...stats.map((s) => s.newest)) };
@@ -3540,7 +3281,7 @@ function detectWebBuildCmd(cwd: string, cfg: AppwrapConfig): string[] | null {
  * app loads the live serverUrl, so its dist is unused (building it would be wasteful + misleading).
  * Prints exactly what it's doing either way. `--no-web-build` skips it (ship the current dist as-is,
  * e.g. to hit the native build-skip fast-path when only the wrapper changed). */
-function buildWebIfBundled(cwd: string, cfg: AppwrapConfig, flags: Record<string, string>): void {
+export function buildWebIfBundled(cwd: string, cfg: AppwrapConfig, flags: Record<string, string>): void {
   if ((cfg.loader ?? 'app') === 'server') {
     console.log('ℹ loader:server — NOT building the web (the app loads serverUrl live; the bundle is unused).');
     return;
@@ -4240,10 +3981,69 @@ async function publish(cwd: string, flags: Record<string, string>, positionals:
   console.log(`✓ Uploaded to Play ${track} track.`);
 }
 
-async function main(): Promise<void> {
+/** Scaffold a new module pack from the built-in template — the community entry point for authoring an
+ * extension. `appwrap create-module <name> [--dir <parent>]` writes <parent>/<name>/ with a manifest +
+ * handler + native-src stub, substituting the module name (and its PascalCase form) into the tokens,
+ * then validates the result so a fresh scaffold is guaranteed pack-conformant. */
+async function createModule(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
+  const name = positionals[0];
+  if (!name || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+    console.error('Usage: appwrap create-module <name> [--dir <parent>]\n  <name> must be a camelCase capability id (letters/digits, leading letter), e.g. `confetti`.');
+    process.exit(1);
+  }
+  if (!existsSync(MODULE_PACK_TEMPLATE_DIR)) {
+    console.error(`✖ module-pack template not found at ${MODULE_PACK_TEMPLATE_DIR}`);
+    process.exit(1);
+  }
+  const pascal = name.replace(/(^|[-_])(\w)/g, (_m, _s, c: string) => c.toUpperCase());
+  const dest = resolve(cwd, flags.dir ?? '.', name);
+  if (existsSync(dest)) {
+    console.error(`✖ ${dest} already exists — choose a different name or --dir.`);
+    process.exit(1);
+  }
+  // Copy the scaffold, then substitute the name tokens in every text file + rename the token'd native-src dir.
+  cpSync(MODULE_PACK_TEMPLATE_DIR, dest, { recursive: true });
+  const rename = (from: string, to: string) => { if (existsSync(from)) renameSync(from, to); };
+  rename(join(dest, 'native-src/__MODULE_NAME__'), join(dest, 'native-src', name));
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.(ts|md|json|swift|kt|xml)$/.test(e.name)) {
+        writeFileSync(p, readFileSync(p, 'utf8').replaceAll('__MODULE_NAME__', name).replaceAll('__MODULE_PASCAL__', pascal));
+      }
+    }
+  };
+  walk(dest);
+  const { validatePack } = await import('./testing');
+  const res = await validatePack(dest);
+  if (!res.ok) {
+    console.error(`✖ scaffolded pack failed validation (this is a bug in the template):\n  ${res.errors.join('\n  ')}`);
+    process.exit(1);
+  }
+  console.log(`✓ Created module pack '${name}' → ${dest}`);
+  console.log(`  Reference it from your appwrap.config.ts:`);
+  console.log(`    modulePacks: ['${flags.dir ? join(flags.dir, name) : `./${name}`}'],`);
+  console.log(`    modules: ['${name}', ...],`);
+}
+
+/**
+ * The CLI entry point — the bare `appwrap` bin calls `runCli()` with no options (identical to the
+ * historical `main`). A host calls `runCli({ commands, platforms, modulePacks,
+ * templateRoots, desktopTemplateDir })` to compose extra capability on top of CE without forking it.
+ */
+export async function runCli(options: CliOptions = {}): Promise<void> {
+  cliOptions = { ...options };
+  if (options.desktopTemplateDir) DESKTOP_TEMPLATE_DIR = options.desktopTemplateDir;
+  // Host template overlays land AFTER the built-in runtime template → they win (file-level last-wins).
+  if (options.templateRoots?.length) TEMPLATE_ROOTS = [...TEMPLATE_ROOTS, ...options.templateRoots];
+
   const { command, flags, positionals } = parseArgs(process.argv.slice(2));
   const cwd = process.cwd();
 
+  // Host-provided commands are consulted first — they can add a new command or override a built-in.
+  if (command && cliOptions.commands?.[command]) { await cliOptions.commands[command](cwd, flags, positionals); return; }
+
   switch (command) {
     case 'init':
       await init(cwd, flags);
@@ -4251,6 +4051,9 @@ async function main(): Promise<void> {
     case 'sync':
       await sync(cwd, flags);
       break;
+    case 'create-module':
+      await createModule(cwd, flags, positionals);
+      break;
     case 'clean':
       await clean(cwd, flags);
       break;
@@ -4288,21 +4091,21 @@ async function main(): Promise<void> {
         '  Android wireless: --wifi flips a USB device to wireless adb (unplug + keep going); thereafter the\n' +
         '       device is auto-discovered via mDNS — plain `dev android` finds it with NO flag (iOS parity).\n' +
         '       --device <ip[:port]> `adb connect`s an already-paired one.\n\n' +
-        '  dev <ios|android|desktop> [--sim] [--detached] [--debug] [--wifi] [--url <devserver>|--port <p>]\n' +
+        '  dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--url <devserver>|--port <p>]\n' +
         '       live-dev: ANDROID device → ns run livesync (true on-device HMR) + re-stage on save;\n' +
         '       iOS device → deploy + rebuild/reinstall on save. --sim = ns run/HMR on emulator;\n' +
         '       --url/--port = web HMR from a dev server inside the WebView; --detached = install & exit.\n' +
-        '       desktop → macOS Tauri shell (cargo run) speaking appwrap protocol v1 (phase-0, macOS-only).\n' +
         '  deploy <ios|android> [--no-launch] [--no-web-build] [-f]   (clean ship-once: build → install → launch → exit)\n' +
         '  publish <ios|android> [prod]              (beta: TestFlight / Play internal. prod: App Store / Play production)\n' +
         '  build <ios|android> [--release] [--aab]   (store artifact only — no install/upload)\n' +
         '  logs <ios|android> [--once] [--native]    (stream WebView console; --native = full OS log)\n' +
         '  clean                                     (ns clean: wipe generated platforms/hooks/node_modules, restore deps — fixes stale/corrupt Podfile after a repo move)\n' +
+        '  create-module <name> [--dir <parent>]     (scaffold a new module pack — a swappable/extensible capability; see modulePacks)\n' +
         '  aliases: `release ios` = `publish ios`; `submit ios` = `publish ios prod`.');
       process.exit(command ? 1 : 0);
   }
 }
 
 if (import.meta.main) {
-  main();
+  runCli();
 }