@livx.cc/appwrap 0.58.4 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.58.4",
+  "version": "0.59.0",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/shell/capabilities.manifest.ts

@@ -326,7 +326,7 @@ export const MODULES: ModuleManifest[] = [
     },
   },
 
-  // NOTE: billing, health, and widget are NOT part of CE — they live in host-provided module packs
+  // NOTE: billing, health, and widget are not built in — they live in host-provided module packs
   // (a consumer opts in via `modulePacks`).
 ];
 

package/runtime/app/shell/custom-webview.android.ts

@@ -4,6 +4,7 @@ import { mimeFor } from './mime';
 import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
+import { showFileChooser } from './file-chooser.android';
 import { hostOf } from './env-switcher';
 
 // `android` + `java` resolve to the real types-android namespaces (no declare needed).
@@ -80,6 +81,17 @@ function getChromeClientClass(): any {
         Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
       );
     },
+
+    // <input type="file"> — NOT optional here: replacing NS's WebChromeClient removed the
+    // platform's default handling, so without this the input is completely inert. All state is
+    // per-invocation closure state inside showFileChooser (the class is shared across webviews).
+    onShowFileChooser(
+      _view: android.webkit.WebView,
+      filePathCallback: android.webkit.ValueCallback<androidNative.Array<android.net.Uri>>,
+      fileChooserParams: android.webkit.WebChromeClient.FileChooserParams
+    ): boolean {
+      return showFileChooser(filePathCallback, fileChooserParams);
+    },
   });
   return chromeClientClass;
 }

package/runtime/app/shell/file-chooser.android.ts

@@ -0,0 +1,187 @@
+import { Utils } from '@nativescript/core';
+import { mimeFor } from './mime';
+import { requestPermissions, startActivityForResult } from './android-helpers';
+
+/**
+ * `<input type="file">` support for the Android WebView.
+ *
+ * WHY THIS FILE EXISTS: we replace NativeScript's WebChromeClient wholesale
+ * (custom-webview.android.ts → setWebChromeClient), so the platform's own file-chooser
+ * handling is gone with it. Without an `onShowFileChooser` override, tapping a file input
+ * does NOTHING — no picker, no callback. (iOS needs none: WKWebView implements the picker itself.)
+ *
+ * THE ONE INVARIANT: `filePathCallback.onReceiveValue` MUST be invoked EXACTLY ONCE on every
+ * path — success, cancel, back, no-activity, thrown exception. Chromium keeps the input in a
+ * "chooser open" state until the callback fires, so a missed call wedges that input PERMANENTLY
+ * for the rest of the page's life (a second tap silently does nothing). Hence the `settled`
+ * latch + the catch-all reject path below; never add an early `return` that skips `deliver`.
+ *
+ * STATE: everything is per-invocation closure state over the callback/params ARGUMENTS. The
+ * WebChromeClient Java proxy is shared across every webview (NS caches the class — see the
+ * header comment in custom-webview.android.ts), so holding per-request state on the client or
+ * in a module-level slot would cross-wire concurrent requests and separate webviews. Don't.
+ */
+export function showFileChooser(
+  filePathCallback: android.webkit.ValueCallback<androidNative.Array<android.net.Uri>>,
+  params: android.webkit.WebChromeClient.FileChooserParams
+): boolean {
+  let settled = false;
+  const deliver = (uris: androidNative.Array<android.net.Uri> | null): void => {
+    if (settled) return;
+    settled = true;
+    Utils.dispatchToMainThread(() => {
+      try {
+        filePathCallback.onReceiveValue(uris);
+      } catch (e) {
+        console.warn('[appwrap] file-chooser callback failed: ' + e);
+      }
+    });
+  };
+
+  try {
+    pick(params).then(deliver, (e) => {
+      console.warn('[appwrap] file-chooser failed: ' + e);
+      deliver(null); // cancel semantics — the input stays usable
+    });
+  } catch (e) {
+    console.warn('[appwrap] file-chooser threw: ' + e);
+    deliver(null);
+  }
+  return true; // we own the request (returning false = "no chooser", input goes inert)
+}
+
+/** accept="" tokens → intent MIME types. `.png` style extensions map through the shared MIME table. */
+function acceptMimes(params: any): string[] {
+  const raw: string[] = Array.from(params?.getAcceptTypes?.() ?? []).map(String);
+  const out = new Set<string>();
+  for (const t of raw) {
+    const token = t.trim();
+    if (!token) continue; // the platform pads getAcceptTypes() with empty strings for accept=""
+    if (token.startsWith('.')) out.add(mimeFor(token.slice(1).toLowerCase()));
+    else if (token.includes('/')) out.add(token);
+  }
+  // application/octet-stream is mimeFor's fallback for an unknown extension — it matches nothing
+  // in the picker, so an unresolvable accept must widen to "any file", not narrow to nothing.
+  if (out.has('application/octet-stream')) return [];
+  return Array.from(out);
+}
+
+async function pick(params: any): Promise<androidNative.Array<android.net.Uri> | null> {
+  const mimes = acceptMimes(params);
+  const FCP = android.webkit.WebChromeClient.FileChooserParams;
+  const multiple = params?.getMode?.() === FCP.MODE_OPEN_MULTIPLE;
+
+  if (params?.isCaptureEnabled?.()) {
+    const captured = await capture(mimes);
+    // Fall through to the normal picker ONLY when the capture path is UNAVAILABLE (no capture
+    // app, CAMERA denied): `capture` is a HINT in the HTML spec, not a hard requirement.
+    // A settled capture ends the request — including a CANCEL (`uris: null`), which must return
+    // the user to the page, not ambush them with a second picker they never asked for.
+    if (captured.settled) return captured.uris;
+  }
+
+  const I = android.content.Intent;
+  const intent = new I(I.ACTION_GET_CONTENT);
+  intent.addCategory(I.CATEGORY_OPENABLE);
+  intent.setType(mimes.length === 1 ? mimes[0] : '*/*');
+  if (mimes.length > 1) {
+    const arr = (Array as any).create(java.lang.String, mimes.length);
+    mimes.forEach((m, i) => (arr[i] = new java.lang.String(m)));
+    intent.putExtra(I.EXTRA_MIME_TYPES, arr);
+  }
+  if (multiple) intent.putExtra(I.EXTRA_ALLOW_MULTIPLE, true);
+
+  const { resultCode, intent: data } = await startActivityForResult(intent);
+  if (resultCode !== android.app.Activity.RESULT_OK || !data) return null;
+  return toUriArray(collect(data));
+}
+
+/** Multi-select arrives as ClipData; single select as the intent's data Uri. */
+function collect(data: android.content.Intent): android.net.Uri[] {
+  const uris: android.net.Uri[] = [];
+  const clip = data.getClipData?.();
+  if (clip) {
+    for (let i = 0; i < clip.getItemCount(); i++) {
+      const u = clip.getItemAt(i).getUri();
+      if (u) uris.push(u);
+    }
+  }
+  const single = data.getData?.();
+  if (!uris.length && single) uris.push(single);
+  return uris;
+}
+
+function toUriArray(uris: android.net.Uri[]): androidNative.Array<android.net.Uri> | null {
+  if (!uris.length) return null;
+  const arr = (Array as any).create(android.net.Uri, uris.length);
+  uris.forEach((u, i) => (arr[i] = u));
+  return arr;
+}
+
+/**
+ * capture="" path: MediaStore capture intents. Image capture writes to a FileProvider-backed
+ * cache file (EXTRA_OUTPUT) so the web layer gets a FULL-SIZE file rather than the ~100px
+ * thumbnail the extras-only path returns.
+ *
+ * `settled:false` means the capture path is UNAVAILABLE (no capture activity / CAMERA denied) —
+ * the ONLY case the caller may fall back to the normal picker. `settled:true` owns the request:
+ * `uris` carries the capture, or is null when the user CANCELLED (back out of the camera). The
+ * two were once both a bare null, which turned one cancel into a second, unrequested picker.
+ */
+type CaptureResult =
+  | { settled: true; uris: androidNative.Array<android.net.Uri> | null }
+  | { settled: false };
+
+async function capture(mimes: string[]): Promise<CaptureResult> {
+  const kind = mimes[0]?.split('/')[0] ?? 'image';
+  const MS = android.provider.MediaStore;
+  const ctx = Utils.android.getApplicationContext();
+  const I = android.content.Intent;
+
+  const action = kind === 'video' ? MS.ACTION_VIDEO_CAPTURE
+    : kind === 'audio' ? MS.Audio.Media.RECORD_SOUND_ACTION
+      : MS.ACTION_IMAGE_CAPTURE;
+  const intent = new I(action);
+  if (!intent.resolveActivity(ctx.getPackageManager())) return { settled: false };
+
+  // CAMERA is only REQUIRED when the app DECLARES it: Android denies a capture intent to an app
+  // that declares the permission without holding it, but asks nothing of an app that doesn't
+  // declare it at all. Requesting an undeclared permission returns denied forever → a dead
+  // capture path in apps that never opted into the camera module.
+  if (action !== MS.Audio.Media.RECORD_SOUND_ACTION && declares('android.permission.CAMERA')) {
+    if (!(await requestPermissions(['android.permission.CAMERA']))) return { settled: false };
+  }
+
+  let output: android.net.Uri | null = null;
+  if (action === MS.ACTION_IMAGE_CAPTURE) {
+    const dir = new java.io.File(ctx.getCacheDir(), 'shared'); // already exposed by file_paths.xml
+    dir.mkdirs();
+    const file = new java.io.File(dir, 'capture-' + java.lang.System.currentTimeMillis() + '.jpg');
+    output = androidx.core.content.FileProvider.getUriForFile(ctx, ctx.getPackageName() + '.fileprovider', file);
+    intent.putExtra(MS.EXTRA_OUTPUT, output);
+    intent.addFlags(I.FLAG_GRANT_WRITE_URI_PERMISSION | I.FLAG_GRANT_READ_URI_PERMISSION);
+  }
+
+  const { resultCode, intent: data } = await startActivityForResult(intent);
+  // Cancelled (BACK out of the camera) — settled, with nothing: the caller delivers null.
+  if (resultCode !== android.app.Activity.RESULT_OK) return { settled: true, uris: null };
+  // EXTRA_OUTPUT captures return no data Uri — the bytes landed in `output`.
+  const uris = data ? collect(data) : [];
+  if (!uris.length && output) uris.push(output);
+  return { settled: true, uris: toUriArray(uris) };
+}
+
+function declares(permission: string): boolean {
+  try {
+    const ctx = Utils.android.getApplicationContext();
+    const info = ctx.getPackageManager().getPackageInfo(
+      ctx.getPackageName(),
+      android.content.pm.PackageManager.GET_PERMISSIONS
+    );
+    return Array.from(info.requestedPermissions ?? []).map(String).includes(permission);
+  } catch (e) {
+    return false;
+  }
+}
+
+declare const androidx: any; // androidx.core.content.FileProvider — not in the android-32 platform typings

package/runtime/app/shell/plugin-host.ts

@@ -1,7 +1,7 @@
 /**
- * Mobile plugin host — the in-process analog of the desktop plugin host (`plugin/host.ts`).
+ * Mobile plugin host — the in-process analog of an out-of-process desktop plugin host.
  *
- * On desktop a plugin's `WindowCtx` ops marshal over a Unix socket to the Rust shell; that host does
+ * On desktop a plugin's `WindowCtx` ops marshal to the native shell over IPC; that host does
  * NOT apply on mobile — there is one WKWebView/WebView and the NS runtime IS the trusted host. So the
  * mobile "host" is trivial: at boot it takes each configured plugin's def and registers its `handlers`
  * directly onto the same {@link bridge} the built-in `handlers*.ts` groups use. A PWA then reaches a

package/scripts/stage-assets.mjs

@@ -8,8 +8,8 @@ import { fileURLToPath } from 'node:url';
 
 const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repoRoot = resolve(pkgDir, '../..');
-// Excludes build artifacts (NativeScript: node_modules/platforms/hooks/app/www; Tauri desktop:
-// src-tauri/target — gigabytes — and src-tauri/gen — regenerated on build) and OS cruft.
+// Excludes build artifacts (NativeScript: node_modules/platforms/hooks/app/www; desktop shells:
+// native build output — gigabytes — and generated dirs) and OS cruft.
 const EXCLUDE = /(?:^|\/)(?:node_modules|platforms|hooks|app\/www|target|gen|\.DS_Store)(?:\/|$)/;
 
 for (const name of ['runtime', 'templates']) {

package/src/cli.ts

@@ -25,8 +25,7 @@ import type { AppwrapConfig } from './config';
 import { encodeShareDirectSync, unknownConfigKeys } from './config';
 import { resolveModulePacks, type ResolvedModule, type SyncContext } from './packs';
 import { createHash } from 'crypto';
-// 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.
+// Icon helpers re-exported via `@livx.cc/appwrap/cli` so a host-provided platform lane can reuse them.
 export { APPLE_ICON_GRID_SCALE, makeDockRuntimeIcon } from './icon';
 import {
   androidScreenOrientation,
@@ -109,21 +108,19 @@ function resolveAssetRoot(rel: string): string {
 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
+ * (a host) layers extra shell files on top of the built-in one 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');
 /** 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. */
+/** Desktop template dir. No desktop template ships here — 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. */
 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. */
+/** The desktop template dir set via `runCli({ desktopTemplateDir })`. Read by the host-provided desktop
+ * lane (composed through the `platforms` seam) so the seam stays authoritative in one place. */
 export function getDesktopTemplateDir(): string {
   return DESKTOP_TEMPLATE_DIR;
 }
@@ -139,7 +136,7 @@ export interface CliOptions {
   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)
+   * 4th arg is the driving command ('dev' | 'build') so a single handler (e.g. a 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
@@ -147,7 +144,7 @@ export interface CliOptions {
   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. */
+  /** Override for the desktop template dir. */
   desktopTemplateDir?: string;
 }
 
@@ -342,7 +339,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
   shareTarget: { file: './handlers-share-target', fn: 'registerShareTargetHandlers' },
-  // billing/health/widget live in host-provided module packs (not part of CE) — a consumer opts in via modulePacks.
+  // billing/health/widget live in host-provided module packs — a consumer opts in via modulePacks.
 };
 
 /** The bare specifier a pack handler uses to import a built-in shell API — rewritten to a relative
@@ -2040,15 +2037,20 @@ export function renderCiWorkflow(src: string, ctx: CiRenderContext): string {
     : true;
   const out: string[] = [];
   let dropBlock = false;
+  let inBlock = false; // block directives DON'T nest — fail loud rather than silently mis-render
   for (const line of src.split('\n')) {
     const t = line.trim();
-    if (t.startsWith('#@if:')) { dropBlock = !holds(t.slice(5)); continue; }
-    if (t === '#@end') { dropBlock = false; continue; }
+    if (t.startsWith('#@if:')) {
+      if (inBlock) throw new Error('renderCiWorkflow: nested #@if: block directives are unsupported');
+      inBlock = true; dropBlock = !holds(t.slice(5)); continue;
+    }
+    if (t === '#@end') { inBlock = false; dropBlock = false; continue; }
     if (dropBlock) continue;
     const m = line.match(/^(.*?)\s*#@if:([a-z]+)$/);
     if (m) { if (holds(m[2])) out.push(m[1]); }
     else out.push(line);
   }
+  if (inBlock) throw new Error('renderCiWorkflow: unterminated #@if: block (missing #@end)');
   return out.join('\n')
     .replaceAll('__DIR__', ctx.subdir ? `${ctx.subdir}/` : '')
     .replaceAll('__APP_DIR__', ctx.subdir)
@@ -2195,7 +2197,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
     console.warn('  ⚠ `shareTarget` is active but `urlScheme` is unset — the iOS share extension cannot forward to the app. Set `urlScheme` in the appwrap config.');
   }
   // 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
+  // consumer template can add or replace shell files without forking the template. 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; }
@@ -4110,7 +4112,7 @@ async function createModule(cwd: string, flags: Record<string, string>, position
 /**
  * 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.
+ * templateRoots, desktopTemplateDir })` to compose extra capability on top without forking it.
  */
 export async function runCli(options: CliOptions = {}): Promise<void> {
   cliOptions = { ...options };

package/src/config.ts

@@ -132,81 +132,10 @@ export interface AppwrapConfig {
    * Set 0 for no extra lift (input flush at the reported height; the strip may show). */
   iosKeyboardExtraLift?: number;
   pwaDist: string;
-  /** Desktop (Tauri chassis) shell — phase-0, macOS-only. When present, `appwrap dev|build desktop`
-   * stamps a generated Tauri wrapper (`native-desktop/`). Identity (`id`/`name`/`version`), `urlScheme`
-   * (internal deep-link loopback) and `pwaDist` (→ Tauri `frontendDist`) come from the top-level config;
-   * this only carries the desktop-window specifics. Absent → the desktop lane is inert (mobile-only app). */
-  desktop?: {
-    /** Window title (default: `name`). */
-    title?: string;
-    /** Initial window inner width in px (default 430 — a phone-ish portrait frame). */
-    width?: number;
-    /** Initial window inner height in px (default 800). */
-    height?: number;
-    /** Bundle identifier for the desktop build (default: `${id}.desktop`). Reverse-DNS. */
-    identifier?: string;
-    /** Remember the window's size + position across launches (tauri-plugin-window-state). Default
-     * `true`. When `false`, the plugin isn't registered so every launch opens at the configured
-     * `width`/`height` (no saved state applied). */
-    restoreWindowState?: boolean;
-    /** Force Google's account chooser in `signInWithPopup` OAuth. The shared WKWebView cookie store
-     * keeps the Google session, so Firebase auto-signs the remembered account; for apps that run
-     * multiple instances against different accounts (e.g. Unclaw) set `true` to append
-     * `prompt=select_account` to the popup's `accounts.google.com` OAuth URL so the user always picks.
-     * Default `false` (remember-me behavior stays). macOS-only. */
-    googleAccountPicker?: boolean;
-    /** Launch the app automatically when the user logs in (tauri-plugin-autostart, macOS LaunchAgent).
-     * Default `false`. The shell registers a login item on first launch when `true`, and explicitly
-     * REMOVES it when `false`, so flipping this off actually clears the login item on the next launch.
-     * NOTE: an adhoc-signed `.app` (the phase-0 desktop build) still autostarts via the LaunchAgent
-     * plist — no Developer ID required. macOS-only. */
-    autostart?: boolean;
-    /** Path (relative to the app root) to a TypeScript file that exports custom native handlers via
-     * `defineHandlers({...})` from `@livx.cc/appwrap/handlers`. When present the desktop shell spawns a
-     * Bun sidecar (`bun <path>`) at launch and routes any method the sidecar advertises to it — so an
-     * app ships app-custom native capabilities (called from the PWA via `kit.invoke('myapp.foo', …)`)
-     * without touching the Rust shell. Absent → the feature is fully inert (no sidecar spawned).
-     * The CLI stamps the ABSOLUTE resolved path into the shell config; handlers run with their CWD at
-     * the app dir, so `build desktop` apps must keep their repo (+ node_modules) around at runtime —
-     * embedding the handler file into the `.app` is out of scope for phase-0. macOS-only. */
-    handlers?: string;
-    /** Local-server mode: boot a command that serves the app locally, then load it LIVE in the window
-     * (instead of the bundled `pwaDist`). The shell shows a bundled splash, spawns `command` (+`args`)
-     * in a background thread, polls `http://localhost:<port><healthPath>` until it answers, then
-     * navigates the window there; on window-close it kills the child so the stack never outlives the
-     * shell. Use for a desktop app that IS a local dev/server stack (e.g. `para-chat`). Absent → the
-     * desktop lane loads the bundled `pwaDist` as usual. The CLI resolves `command` (when a bare name)
-     * and `cwd` to absolute paths at stamp time (a GUI-launched .app inherits the minimal launchd PATH,
-     * so a bare `bun`/PATH lookup would fail). `build desktop` apps must keep the server (+ its repo)
-     * present at runtime — bundling the server INTO the .app is a future phase. macOS-only. */
-    server?: {
-      /** Command to spawn (argv[0]). A bare name is PATH-resolved at stamp time; an absolute path is used as-is. */
-      command: string;
-      /** Extra arguments passed to the command. */
-      args?: string[];
-      /** Working directory to spawn in (default: the app project root). */
-      cwd?: string;
-      /** How the shell learns the URL to load. Provide EXACTLY ONE:
-       *  - `urlMarker` (preferred for servers that print their address, e.g. vite/para-chat): the shell
-       *    pipes the server's stdout and, on the first line CONTAINING this marker, extracts the first
-       *    `http(s)://…` token and loads it. This tracks whatever port the server auto-picked — no
-       *    hardcoded port, no mismatch. e.g. `"Frontend:"` matches `Frontend:  https://localhost:5050`.
-       *  - `port` (+ optional `https`) for a silent server on a KNOWN fixed port: the shell TCP-polls
-       *    `localhost:<port>` and loads `<http|https>://localhost:<port>`. */
-      urlMarker?: string;
-      /** Fixed port the server listens on (used only when `urlMarker` is absent). */
-      port?: number;
-      /** Load over https in fixed-`port` mode (default false = http). Ignored in `urlMarker` mode (the
-       * captured URL carries its own scheme). The server's TLS cert CA must be trusted by the system
-       * keychain and its SANs cover `localhost`/`127.0.0.1`, or the WebView shows a cert error. */
-      https?: boolean;
-      /** Health path polled for readiness (default `/`). Ready = any HTTP response (even 4xx/5xx). */
-      healthPath?: string;
-      /** Max ms to wait for the port before showing an error in the splash (default 120000 — a first-run
-       * production build can be slow). */
-      readyTimeoutMs?: number;
-    };
-  };
+  /** Desktop-shell block, consumed by an external desktop host (a module pack) that registers a
+   * `'desktop'` platform handler via `runCli({ platforms })`. Carried OPAQUE — nothing here reads
+   * it; the key is registered only so `unknownConfigKeys` doesn't warn on configs that declare it. */
+  desktop?: Record<string, unknown>;
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
   /** Android App Links: https hosts whose `https://<host>/...` links open the app directly (the
@@ -357,8 +286,8 @@ export interface AppwrapConfig {
    * build finds MULTIPLE candidate profiles for an id and you pick one interactively — so you're not
    * re-prompted. Usually unset: a single matching profile is selected automatically. */
   signingProfiles?: Record<string, string>;
-  /** Store-lane block (listing metadata, screenshot dirs, submission answers) consumed by an EE host
-   * (`appwrap-ee store bootstrap|push|assets`). CE carries it OPAQUE — nothing in CE reads it; the
+  /** Store-lane block (listing metadata, screenshot dirs, submission answers) consumed by external
+   * store tooling. Carried OPAQUE — nothing here reads it; the
    * key is registered only so `unknownConfigKeys` doesn't warn on configs that declare it. */
   store?: Record<string, unknown>;
   /** Pure-native escape hatch: a directory (relative to the PWA project) whose contents are copied
@@ -367,10 +296,9 @@ export interface AppwrapConfig {
   overrides?: string;
   /** appwrap TS plugins (`@livx.cc/appwrap/plugin`). Each entry is an npm package name or a path to a
    * plugin entrypoint (that `export default definePlugin(...)`); the object form adds a config-level
-   * `attachTo` override (which windows it attaches to). `appwrap dev|build desktop` resolves + bun-builds
-   * each into a single embedded bundle and stamps it into the desktop shell (see `regeneratePlugins`),
-   * where the multiplexed plugin host loads them. A.1 skeleton: desktop-only; manifest/perms merge is
-   * stubbed (full module-manifest reuse lands later). */
+   * `attachTo` override (which windows it attaches to). On mobile the runtime registers a plugin's
+   * `handlers` in-process; a host-provided desktop lane bundles them for its own shell. Manifest/perms
+   * merge is stubbed (full module-manifest reuse lands later). */
   plugins?: (string | { name: string; attachTo?: 'main' | 'all' | string; options?: unknown })[];
   /** Opt-in capability allow-list (built-in modules — see capabilities.manifest.ts). When PRESENT,
    * only the listed capabilities (plus always-on core) are advertised, permissioned, and — for

package/src/icon.ts

@@ -1,11 +1,10 @@
 /**
  * Dependency-free PNG codec + macOS app-icon corner rounding, in pure TS on `node:zlib`.
  *
- * WHY: Tauri embeds `src-tauri/icons/icon.png` via `generate_context!` and sets it as the RUNTIME
- * app icon on macOS — which OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock. The template ships
- * a placeholder square, so every built app shows that square while running. We stamp the app's real
- * icon in instead: downscale (sips, in the CLI) → decode here → round the corners with the macOS
- * app-icon squircle mask → ensure RGBA (Tauri hard-requires alpha) → re-encode.
+ * WHY: a desktop shell can embed an icon PNG and set it as the RUNTIME app icon on macOS — which
+ * OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock. A template placeholder would then show while
+ * the app runs, so we stamp the app's real icon in instead: downscale (sips, in the CLI) → decode here
+ * → round the corners with the macOS app-icon squircle mask → ensure RGBA (alpha is required) → re-encode.
  *
  * Supports 8-bit RGB / RGBA, non-interlaced PNG (what `sips` emits). Errors clearly on anything else.
  */

package/src/packs.ts

@@ -1,5 +1,5 @@
 /**
- * Module-pack resolver — the single public extension seam of appwrap (CE/EE seam A2).
+ * Module-pack resolver — the single public extension seam of appwrap.
  *
  * A "pack" is a directory (local, or an npm package) that contributes capabilities to a wrapper build
  * exactly like the built-in modules do: it exports `ModuleManifest[]` (the same contribution bags the
@@ -15,7 +15,7 @@
  *    own module is not an error).
  *
  * This one mechanism serves three audiences identically: a host layers its private packs, a consumer
- * app vendors its own copy of a module, and the community ships plugins — none of them patch CE.
+ * app vendors its own copy of a module, and the community ships plugins — none of them patch the core.
  *
  * PURE of CLI I/O: filesystem/npm resolution and pack import are injected ports (`resolvePack`/
  * `importPack`), so the merge logic unit-tests against in-memory fakes. The CLI wires the real ports.

package/src/plugin/index.ts

@@ -14,7 +14,7 @@
  *   });
  *
  * Types-first: `definePlugin` is an identity helper that validates + returns the def, which the plugin
- * entrypoint `export default`s. The multiplexed host (`host.ts`) `import()`s the built bundle and reads
+ * entrypoint `export default`s. The multiplexed host `import()`s the built bundle and reads
  * `.default`. Nothing runs at import time (unlike `defineHandlers`, which starts a loop) — the host
  * drives the lifecycle.
  */

package/src/plugin/types.ts

@@ -1,10 +1,10 @@
 /**
  * appwrap plugin contract — the PORT (`@livx.cc/appwrap/plugin`).
  *
- * A TS plugin consumes a CURATED, VERSIONED facade over the native `webview-control` primitives
- * ({@link WindowCtx}) — it never touches objc2 FFI. The plugin runs OUT-OF-WEBVIEW in the trusted
- * multiplexed Bun host (see `host.ts`); the host speaks a bidirectional line-JSON protocol over a
- * Unix domain socket to the Rust shell, which owns the primitives.
+ * A TS plugin consumes a CURATED, VERSIONED facade over the native window primitives
+ * ({@link WindowCtx}) — it never touches native FFI. The plugin runs OUT-OF-WEBVIEW in a trusted
+ * multiplexed Bun host, which speaks a bidirectional line-JSON protocol to the native shell that
+ * owns the primitives.
  *
  * IoC / Hollywood: the CORE calls the plugin — on window-created it fans out to each plugin whose
  * `attachTo` matches, invoking `onWindow(ctx)`. Plugins never reach into core internals.
@@ -37,7 +37,7 @@ export interface WindowIdentity {
 export type Dispose = () => void;
 
 /**
- * Curated, versioned facade over the native `webview-control` primitives, scoped to ONE window.
+ * Curated, versioned facade over the native window primitives, scoped to ONE window.
  * NOT raw FFI — a deliberately small subset (design risk #4: avoid a god-interface). Every method
  * marshals over the host↔shell socket as an `op` envelope and awaits a `result`.
  */
@@ -79,7 +79,7 @@ export interface PluginDef {
   onClose?(win: WindowIdentity): void;
 }
 
-// ── Wire protocol (host ↔ shell, one JSON object per line over a Unix domain socket) ──────────────
+// ── Wire protocol (host ↔ shell, one JSON object per line) ────────────────────────────────────────
 // Envelope: { pluginId?, windowId?, kind, method?, params?, id?, ... }. Route by pluginId × windowId.
 //   host → shell:  { kind:'ready',  plugins:[{ pluginId, methods:[…] }] }   (once, at boot)
 //   host → shell:  { kind:'op',     id, pluginId, windowId, method, params }  (a WindowCtx call)
@@ -101,7 +101,7 @@ export interface StampedPlugin {
   /** Bundle/build id derived from the config source (sanitized filename or package name). This is a
    * pre-bundle-load stamp — the plugin's real def `name` isn't known until the host `import()`s the
    * bundle. It is NOT the routing/diagnostic identifier: routing (matchScope, registry) and all
-   * diagnostics key off the loaded def `name` (see host.ts). Used only for the bundle filename. */
+   * diagnostics key off the loaded def `name`. Used only for the bundle filename. */
   bundleId: string;
   /** Config-level attachTo OVERRIDE (string forms only). Falls back to the def's own `attachTo`. */
   attachTo?: 'main' | 'all' | string;

package/src/testing.ts

@@ -1,5 +1,5 @@
 /**
- * Pack conformance validator — the public `@livx.cc/appwrap/testing` entry (CE/EE seam A8).
+ * Pack conformance validator — the public `@livx.cc/appwrap/testing` entry.
  *
  * A module pack (see packs.ts) is authored out-of-tree and staged into the shell at sync. Because a
  * malformed pack fails LATE (mid-generate, on a device build), this gives pack authors a FAST, offline
@@ -32,7 +32,7 @@ export interface ValidatePackResult {
 const NODE_BUILTIN_SET = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
 
 /** The sanctioned shell-API specifier prefix a pack handler may deep-import (rewritten to relative on
- * staging). Any OTHER `@livx.cc/appwrap/...` deep import reaches into CE internals → rejected. */
+ * staging). Any OTHER `@livx.cc/appwrap/...` deep import reaches into internals → rejected. */
 const SANCTIONED_SHELL_PREFIX = '@livx.cc/appwrap/runtime/app/shell/';
 
 /** Map a handler file extension to the Bun.Transpiler loader for its dialect (mirrors cli.ts). */
@@ -51,7 +51,7 @@ function loaderFor(file: string): 'ts' | 'tsx' | 'js' | 'jsx' {
 function bareImportError(spec: string): string | null {
   // Sanctioned shell API — always fine.
   if (spec === SANCTIONED_SHELL_PREFIX.slice(0, -1) || spec.startsWith(SANCTIONED_SHELL_PREFIX)) return null;
-  // Any OTHER appwrap deep import escapes the sanctioned seam into CE internals.
+  // Any OTHER appwrap deep import escapes the sanctioned seam into internals.
   if (spec === '@livx.cc/appwrap' || spec.startsWith('@livx.cc/appwrap/')) {
     return `imports appwrap internals via "${spec}" — a pack may only deep-import the sanctioned ` +
       `"${SANCTIONED_SHELL_PREFIX}*" shell APIs.`;