@habemus-papadum/aiui 0.3.0 → 0.6.0

package/dist/util/managed-browser.d.ts

@@ -0,0 +1,109 @@
+import { Browser } from "@puppeteer/browsers";
+import { type ManagedFlavor, type ManageMode } from "./config";
+/** Re-resolve the latest build id at most this often. */
+export declare const CHECK_TTL_MS: number;
+/** The per-flavor facts that differ between the two managed builds. */
+export interface ManagedFlavorSpec {
+    flavor: ManagedFlavor;
+    /** The `@puppeteer/browsers` browser this flavor installs. */
+    browser: Browser;
+    /**
+     * The tag `resolveBuildId` accepts for "newest": Chrome for Testing tracks
+     * the "stable" release channel; Chromium only supports "latest" (a snapshot
+     * revision).
+     */
+    latestTag: string;
+    /** Human name for prompts and status. */
+    displayName: string;
+    /** Cache subdirectory under `~/.cache/aiui/` (also the on-disk browser name). */
+    cacheSubdir: string;
+    /** Rough download size, for the install prompt. */
+    approxSizeMb: number;
+}
+export declare const MANAGED_FLAVOR_SPECS: Record<ManagedFlavor, ManagedFlavorSpec>;
+export declare function flavorSpec(flavor: ManagedFlavor): ManagedFlavorSpec;
+/** One managed install. */
+export interface ManagedInstall {
+    flavor: ManagedFlavor;
+    buildId: string;
+    executablePath: string;
+}
+/** Prompt/check bookkeeping, persisted in each flavor's cache dir. */
+export interface ManagedState {
+    /** Epoch ms of the last successful latest-build lookup. */
+    checkedAt?: number;
+    /** The latest build id as of `checkedAt`. */
+    latestBuildId?: string;
+    /** Update prompt answered "skip" for this build id — don't re-ask for it. */
+    skippedBuildId?: string;
+    /** Epoch ms when an install offer was declined — snooze re-asking for a day. */
+    installDeclinedAt?: number;
+}
+/** Where a flavor's managed builds (and its state file) live. */
+export declare function managedCacheDir(flavor: ManagedFlavor, create?: boolean): string;
+/** Every flavor's cache dir — what `aiui clean` sweeps. */
+export declare function allManagedCacheDirs(create?: boolean): string[];
+export declare function readManagedState(flavor: ManagedFlavor): ManagedState;
+export declare function writeManagedState(flavor: ManagedFlavor, patch: Partial<ManagedState>): void;
+/**
+ * Numeric, segment-wise build id comparison. Handles both shapes: Chrome for
+ * Testing's dotted "138.0.7204.94" and Chromium's single-integer snapshot
+ * revision "1358901" (one segment → plain numeric compare).
+ */
+export declare function compareBuildIds(a: string, b: string): number;
+/** The newest managed install for a flavor, if any. Never touches the network. */
+export declare function installedManaged(flavor: ManagedFlavor): Promise<ManagedInstall | undefined>;
+/**
+ * The latest build id for a flavor, freshness-limited and offline-tolerant.
+ *
+ * Consults the network at most once per `maxAgeMs` (persisted in the state
+ * file) with a short timeout; on failure it falls back to the last known
+ * value, or undefined — callers treat undefined as "can't tell, don't nag".
+ */
+export declare function latestManaged(flavor: ManagedFlavor, opts?: {
+    maxAgeMs?: number;
+    timeoutMs?: number;
+    now?: number;
+}): Promise<string | undefined>;
+/**
+ * Install the given build into the flavor's managed cache and drop superseded
+ * builds (they're ~150-160 MB each; the whole point of the managed dir is that
+ * there's exactly one, current, browser in it).
+ */
+export declare function installManaged(flavor: ManagedFlavor, buildId: string): Promise<ManagedInstall>;
+/**
+ * Bring a flavor's managed install to latest (the `aiui chrome install` /
+ * `update` implementation). Unlike the launch path this resolves with no
+ * timeout — an explicit command is allowed to wait on the network — and
+ * reports what it did.
+ */
+export declare function ensureLatestManaged(flavor: ManagedFlavor, report: (line: string) => void): Promise<ManagedInstall & {
+    outcome: "current" | "installed" | "updated";
+}>;
+/**
+ * The launch-path managed-browser sync: decide which browser this session
+ * should use, and (interactively, when allowed) offer to install or update the
+ * managed build for `flavor`.
+ *
+ * Returns the executable path to prefer, or undefined to fall back to the
+ * system Chrome. Callers only invoke this when config names no browser
+ * explicitly (no `chrome.executablePath` / `chrome.channel`).
+ *
+ * The mode ladder (`chrome.manage`, default "prompt"):
+ *  - "off"    — never check, never prompt; an already-installed managed build is
+ *               still used (install one deliberately with `aiui chrome install`).
+ *  - "auto"   — install/update to latest without asking.
+ *  - "prompt" — offer to install when missing, offer to update when stale;
+ *               answers can rewrite the mode in the user config.
+ *
+ * Nothing here ever blocks a non-interactive session: without a TTY (or under
+ * CI, or in print mode) this degrades to "use whatever is already installed".
+ * Downloads are likewise interactive-only — even "auto" won't pull ~150 MB
+ * into a headless one-shot.
+ */
+export declare function syncManagedBrowser(opts: {
+    flavor: ManagedFlavor;
+    mode: ManageMode;
+    interactive: boolean;
+    now?: number;
+}): Promise<string | undefined>;

package/dist/util/openai-preflight.d.ts

@@ -14,7 +14,7 @@
  * blocks the launch; the modality still mounts, but transcription/correction are
  * unavailable until the key is set (the widget says so — `mock` is the explicit
  * offline choice, not a silent fallback). The most valuable case this catches is the one that
- * bit the bench twice (see workbench field-notes, "Keys & config"): a **stale
+ * bit the bench twice (archive/workbench/field-notes.md, "Keys & config"): a **stale
  * shell export** shadowing the real key, which surfaces as a confusing 401 deep
  * in the pipeline rather than a clear message up front.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@habemus-papadum/aiui",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "ai ui frontends",
   "type": "module",
   "license": "MIT",
@@ -25,8 +25,7 @@
     "aiui": "./dist/cli.js"
   },
   "files": [
-    "dist",
-    "templates"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
@@ -38,12 +37,13 @@
     "commander": "^15.0.0",
     "execa": "^9.6.1",
     "vite": "^6.4.3",
-    "@habemus-papadum/aiui-claude-plugin": "^0.3.0",
-    "@habemus-papadum/aiui-devtools-extension": "^0.3.0",
-    "@habemus-papadum/aiui-dev-overlay": "^0.3.0",
-    "@habemus-papadum/aiui-paint": "^0.3.0",
-    "@habemus-papadum/aiui-claude-channel": "^0.3.0",
-    "@habemus-papadum/aiui-util": "^0.3.0"
+    "@habemus-papadum/aiui-claude-plugin": "^0.6.0",
+    "@habemus-papadum/aiui-claude-channel": "^0.6.0",
+    "@habemus-papadum/aiui-trace-ui": "^0.6.0",
+    "@habemus-papadum/aiui-util": "^0.6.0"
+  },
+  "devDependencies": {
+    "@habemus-papadum/aiui-lowering-pipeline": "^0.6.0"
   },
   "scripts": {
     "build": "tsc --emitDeclarationOnly -p tsconfig.json && vite build",

package/dist/commands/demo.d.ts

@@ -1,28 +0,0 @@
-export interface DemoOptions {
-    /** Scaffold only — skip `npm install` (used by the packaging test/CI). */
-    skipInstall?: boolean;
-}
-/** What `aiui demo` finds at the target path. */
-export type DemoTargetState = "new" | "existing-demo" | "occupied";
-export declare function runDemo(dir: string | undefined, opts?: DemoOptions): Promise<void>;
-/**
- * Decide what to do with the target: `new` (missing or empty), an
- * `existing-demo` (package.json carries the scaffold marker — continue), or
- * `occupied` (anything else — refuse; never clobber unknown content).
- */
-export declare function classifyDemoTarget(target: string): DemoTargetState;
-/**
- * The dependency range the scaffold pins aiui packages to: this build's exact
- * release line when it has one, `latest` from a dev build (whose `0.0.0+dev`
- * doesn't exist on the registry).
- */
-export declare function demoDependencyRange(version: string): string;
-/** Copy the template, restore dot-paths npm strips, and pin dependency ranges. */
-export declare function scaffoldDemo(template: string, target: string): void;
-/**
- * The template directory shipped with this install. Probed upward from this
- * module because the relative depth differs between layouts: `dist/cli.js`
- * (bundled, installed) sits one level below the package root; the tsx-run
- * `src/commands/demo.ts` sits two below.
- */
-export declare function templateRoot(): string | undefined;

package/dist/commands/paint.d.ts

@@ -1,3 +0,0 @@
-export declare function runPaintUrl(opts?: {
-    json?: boolean;
-}): Promise<void>;

package/dist/sidecars-BKlhUA0V.js

@@ -1,48 +0,0 @@
-import { createRequire as c } from "node:module";
-const l = c(import.meta.url), n = [
-  {
-    // The iPad paint stream. Always on: it rides the channel's own port (no
-    // process, no extra listener), so hosting it costs nothing. Whether an
-    // iPad can actually REACH it is the channel bind's decision (`channel.bind`
-    // / `--aiui-bind`, asked at first run) — the security posture lives there,
-    // not here. `--aiui-no-sidecar paint` / `sidecars.paint: false` turn it off.
-    name: "paint",
-    autoEnable: () => !0,
-    descriptor: (a, o) => ({
-      name: "paint",
-      module: o("@habemus-papadum/aiui-paint/sidecar"),
-      export: "paintSidecar",
-      options: { root: a }
-    })
-  }
-];
-function u(a, o, i = {}) {
-  const d = i.resolveModule ?? ((e) => l.resolve(e)), s = i.log ?? ((e) => process.stderr.write(`[aiui] warning: ${e}
-`)), t = /* @__PURE__ */ new Set();
-  for (const e of n)
-    try {
-      e.autoEnable(a) && t.add(e.name);
-    } catch (r) {
-      s(
-        `sidecar "${e.name}" auto-detect failed: ${r instanceof Error ? r.message : String(r)}`
-      );
-    }
-  for (const e of o.enable)
-    n.some((r) => r.name === e) && t.add(e);
-  for (const e of o.disable)
-    t.delete(e);
-  return n.filter((e) => t.has(e.name)).map((e) => {
-    try {
-      return e.descriptor(a, d);
-    } catch (r) {
-      s(
-        `sidecar "${e.name}" disabled — its module failed to resolve: ${r instanceof Error ? r.message : String(r)}`
-      );
-      return;
-    }
-  }).filter((e) => e !== void 0);
-}
-export {
-  u as r
-};
-//# sourceMappingURL=sidecars-BKlhUA0V.js.map

package/dist/sidecars-BKlhUA0V.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sidecars-BKlhUA0V.js","sources":["../src/util/sidecars.ts"],"sourcesContent":["/**\n * Deciding which **session sidecars** the channel should host for a launch.\n *\n * A sidecar is an extra backend the channel mounts alongside the intent\n * pipeline — the concrete one today is the iPad paint stream. The channel takes\n * no dependency on any sidecar: `aiui claude` hands it a JSON array of\n * {@link SidecarDescriptor}s on `--sidecars`, and the channel dynamic-imports\n * each `module`, calls `mod[export ?? \"default\"](options)`, and mounts the\n * result (a bad descriptor is logged + skipped there).\n *\n * This module is the CLI's half: a small registry of the sidecars the launcher\n * knows how to construct, plus a pure resolver that decides which are on for a\n * given project root and set of `--aiui-sidecar` / `--aiui-no-sidecar` flags.\n */\n\nimport { createRequire } from \"node:module\";\n\nconst nodeRequire = createRequire(import.meta.url);\n\n/**\n * The contract the channel's `--sidecars` argument expects, mirrored here so\n * the CLI can emit it. The channel imports `module`, calls its `export` (or\n * `default`) with `options`, and mounts the returned sidecar.\n */\nexport interface SidecarDescriptor {\n  /** Stable identifier, used for `--aiui-sidecar`/`--aiui-no-sidecar` and logs. */\n  name: string;\n  /** Importable specifier the channel `import()`s (e.g. a package subpath). */\n  module: string;\n  /** Named export to call as the factory. Defaults to `\"default\"`. */\n  export?: string;\n  /** Passed opaquely to the factory (e.g. `{ root: \"/proj\" }`). */\n  options?: unknown;\n}\n\n/** Resolves a package specifier to an absolute path the channel can `import()`. */\ntype ResolveModule = (specifier: string) => string;\n\n/** Injectable seams, so the resolver is unit-testable without on-disk state. */\nexport interface ResolveSidecarsDeps {\n  /**\n   * Resolves a sidecar's package specifier to an ABSOLUTE path. Defaults to\n   * `createRequire(import.meta.url).resolve`. This matters: the channel\n   * dynamic-imports the descriptor's `module`, but it does NOT depend on any\n   * sidecar package — so a bare specifier resolves from the channel's own\n   * node_modules and fails (pnpm's isolated layout). Resolving here (from the\n   * `aiui` CLI, which DOES depend on the sidecar package) to an absolute path\n   * makes the import work in both the source-first workspace and an install.\n   */\n  resolveModule?: ResolveModule;\n  /** Warning sink for a sidecar that had to be dropped (defaults to stderr). */\n  log?: (message: string) => void;\n}\n\n/** A sidecar the CLI knows how to enable and construct, keyed by name. */\ninterface KnownSidecar {\n  name: string;\n  /** Whether this sidecar auto-enables for the given project root. */\n  autoEnable: (root: string) => boolean;\n  /** Build the descriptor the channel will mount for this root. */\n  descriptor: (root: string, resolveModule: ResolveModule) => SidecarDescriptor;\n}\n\n/**\n * The registry of sidecars the launcher can enable. Emit order follows this\n * list, so the resolver's output is stable regardless of flag order. The paint\n * stream is always on — see its entry.\n */\nconst KNOWN_SIDECARS: KnownSidecar[] = [\n  {\n    // The iPad paint stream. Always on: it rides the channel's own port (no\n    // process, no extra listener), so hosting it costs nothing. Whether an\n    // iPad can actually REACH it is the channel bind's decision (`channel.bind`\n    // / `--aiui-bind`, asked at first run) — the security posture lives there,\n    // not here. `--aiui-no-sidecar paint` / `sidecars.paint: false` turn it off.\n    name: \"paint\",\n    autoEnable: () => true,\n    descriptor: (root, resolveModule) => ({\n      name: \"paint\",\n      module: resolveModule(\"@habemus-papadum/aiui-paint/sidecar\"),\n      export: \"paintSidecar\",\n      options: { root },\n    }),\n  },\n];\n\n/**\n * Decide which session sidecars to host for `root`.\n *\n * Starts from the auto-detected set (each known sidecar whose `autoEnable`\n * predicate is truthy for this root), then applies the flags: `opts.enable`\n * force-adds a known sidecar by name even when it wouldn't auto-detect, and\n * `opts.disable` removes one. Disable wins over enable. Enable names the CLI\n * doesn't know how to construct are ignored (the launcher can only build the\n * sidecars in {@link KNOWN_SIDECARS}). Descriptors come back in the registry's\n * stable order.\n */\nexport function resolveSidecars(\n  root: string,\n  opts: { enable: string[]; disable: string[] },\n  deps: ResolveSidecarsDeps = {},\n): SidecarDescriptor[] {\n  const resolveModule =\n    deps.resolveModule ?? ((specifier: string) => nodeRequire.resolve(specifier));\n  const log =\n    deps.log ?? ((message: string) => process.stderr.write(`[aiui] warning: ${message}\\n`));\n  const enabled = new Set<string>();\n\n  // Auto-detected sidecars. A throwing detector must not kill the launch —\n  // warn and treat as not detected.\n  for (const known of KNOWN_SIDECARS) {\n    try {\n      if (known.autoEnable(root)) {\n        enabled.add(known.name);\n      }\n    } catch (err) {\n      log(\n        `sidecar \"${known.name}\" auto-detect failed: ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      );\n    }\n  }\n  // Force-enable, but only sidecars the CLI knows how to construct.\n  for (const name of opts.enable) {\n    if (KNOWN_SIDECARS.some((k) => k.name === name)) {\n      enabled.add(name);\n    }\n  }\n  // Disable wins over enable.\n  for (const name of opts.disable) {\n    enabled.delete(name);\n  }\n\n  return KNOWN_SIDECARS.filter((k) => enabled.has(k.name))\n    .map((k) => {\n      try {\n        return k.descriptor(root, resolveModule);\n      } catch (err) {\n        // The sidecar's package isn't resolvable (e.g. not installed) — skip it\n        // rather than failing the whole launch, but say so: silently dropping it\n        // would surface as \"the sidecar is mysteriously absent\".\n        log(\n          `sidecar \"${k.name}\" disabled — its module failed to resolve: ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        );\n        return undefined;\n      }\n    })\n    .filter((d): d is SidecarDescriptor => d !== undefined);\n}\n"],"names":["nodeRequire","createRequire","KNOWN_SIDECARS","root","resolveModule","resolveSidecars","opts","deps","specifier","log","message","enabled","known","err","name","k","d"],"mappings":";AAiBA,MAAMA,IAAcC,EAAc,YAAY,GAAG,GAmD3CC,IAAiC;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAME,MAAM;AAAA,IACN,YAAY,MAAM;AAAA,IAClB,YAAY,CAACC,GAAMC,OAAmB;AAAA,MACpC,MAAM;AAAA,MACN,QAAQA,EAAc,qCAAqC;AAAA,MAC3D,QAAQ;AAAA,MACR,SAAS,EAAE,MAAAD,EAAA;AAAA,IAAK;AAAA,EAClB;AAEJ;AAaO,SAASE,EACdF,GACAG,GACAC,IAA4B,CAAA,GACP;AACrB,QAAMH,IACJG,EAAK,kBAAkB,CAACC,MAAsBR,EAAY,QAAQQ,CAAS,IACvEC,IACJF,EAAK,QAAQ,CAACG,MAAoB,QAAQ,OAAO,MAAM,mBAAmBA,CAAO;AAAA,CAAI,IACjFC,wBAAc,IAAA;AAIpB,aAAWC,KAASV;AAClB,QAAI;AACF,MAAIU,EAAM,WAAWT,CAAI,KACvBQ,EAAQ,IAAIC,EAAM,IAAI;AAAA,IAE1B,SAASC,GAAK;AACZ,MAAAJ;AAAA,QACE,YAAYG,EAAM,IAAI,yBACpBC,aAAe,QAAQA,EAAI,UAAU,OAAOA,CAAG,CACjD;AAAA,MAAA;AAAA,IAEJ;AAGF,aAAWC,KAAQR,EAAK;AACtB,IAAIJ,EAAe,KAAK,CAACa,MAAMA,EAAE,SAASD,CAAI,KAC5CH,EAAQ,IAAIG,CAAI;AAIpB,aAAWA,KAAQR,EAAK;AACtB,IAAAK,EAAQ,OAAOG,CAAI;AAGrB,SAAOZ,EAAe,OAAO,CAACa,MAAMJ,EAAQ,IAAII,EAAE,IAAI,CAAC,EACpD,IAAI,CAACA,MAAM;AACV,QAAI;AACF,aAAOA,EAAE,WAAWZ,GAAMC,CAAa;AAAA,IACzC,SAASS,GAAK;AAIZ,MAAAJ;AAAA,QACE,YAAYM,EAAE,IAAI,8CAChBF,aAAe,QAAQA,EAAI,UAAU,OAAOA,CAAG,CACjD;AAAA,MAAA;AAEF;AAAA,IACF;AAAA,EACF,CAAC,EACA,OAAO,CAACG,MAA8BA,MAAM,MAAS;AAC1D;"}

package/dist/util/cft.d.ts

@@ -1,79 +0,0 @@
-import { type ForTestingMode } from "./config";
-/** Re-resolve the latest stable build id at most this often. */
-export declare const CHECK_TTL_MS: number;
-/** One managed CfT install. */
-export interface CftInstall {
-    buildId: string;
-    executablePath: string;
-}
-/** Prompt/check bookkeeping, persisted in the CfT cache dir. */
-export interface CftState {
-    /** Epoch ms of the last successful latest-stable lookup. */
-    checkedAt?: number;
-    /** The latest stable build id as of `checkedAt`. */
-    latestBuildId?: string;
-    /** Update prompt answered "skip" for this build id — don't re-ask for it. */
-    skippedBuildId?: string;
-    /** Epoch ms when an install offer was declined — snooze re-asking for a day. */
-    installDeclinedAt?: number;
-}
-/** Where managed CfT builds (and the state file) live. */
-export declare function cftCacheDir(create?: boolean): string;
-export declare function readCftState(): CftState;
-export declare function writeCftState(patch: Partial<CftState>): void;
-/** Numeric, segment-wise build id comparison ("138.0.7204.94"-style). */
-export declare function compareBuildIds(a: string, b: string): number;
-/** The newest managed CfT install, if any. Never touches the network. */
-export declare function installedCft(): Promise<CftInstall | undefined>;
-/**
- * The latest stable CfT build id, freshness-limited and offline-tolerant.
- *
- * Consults the network at most once per `maxAgeMs` (persisted in the state
- * file) with a short timeout; on failure it falls back to the last known
- * value, or undefined — callers treat undefined as "can't tell, don't nag".
- */
-export declare function latestStableCft(opts?: {
-    maxAgeMs?: number;
-    timeoutMs?: number;
-    now?: number;
-}): Promise<string | undefined>;
-/**
- * Install the given CfT build into the managed cache and drop superseded
- * builds (they're ~160 MB each; the whole point of the managed dir is that
- * there's exactly one, current, browser in it).
- */
-export declare function installCft(buildId: string): Promise<CftInstall>;
-/**
- * Bring the managed CfT to the latest stable (the `aiui chrome install` /
- * `update` implementation). Unlike the launch path this resolves with no
- * timeout — an explicit command is allowed to wait on the network — and
- * reports what it did.
- */
-export declare function ensureLatestCft(report: (line: string) => void): Promise<CftInstall & {
-    outcome: "current" | "installed" | "updated";
-}>;
-/**
- * The launch-path CfT sync: decide which browser this session should use, and
- * (interactively, when allowed) offer to install or update the managed CfT.
- *
- * Returns the CfT executable path to prefer, or undefined to fall back to the
- * system Chrome. Callers only invoke this when config names no browser
- * explicitly (no `chrome.executablePath` / `chrome.channel`).
- *
- * The mode ladder (`chrome.forTesting`, default "prompt"):
- *  - "off"    — never check, never prompt; an already-installed managed CfT is
- *               still used (install one deliberately with `aiui chrome install`).
- *  - "auto"   — install/update to latest stable without asking.
- *  - "prompt" — offer to install when missing, offer to update when stale;
- *               answers can rewrite the mode in the user config.
- *
- * Nothing here ever blocks a non-interactive session: without a TTY (or under
- * CI, or in print mode) this degrades to "use whatever is already installed".
- * Downloads are likewise interactive-only — even "auto" won't pull ~160 MB
- * into a headless one-shot.
- */
-export declare function syncChromeForTesting(opts: {
-    mode: ForTestingMode;
-    interactive: boolean;
-    now?: number;
-}): Promise<string | undefined>;

package/dist/util/sidecars.d.ts

@@ -1,62 +0,0 @@
-/**
- * Deciding which **session sidecars** the channel should host for a launch.
- *
- * A sidecar is an extra backend the channel mounts alongside the intent
- * pipeline — the concrete one today is the iPad paint stream. The channel takes
- * no dependency on any sidecar: `aiui claude` hands it a JSON array of
- * {@link SidecarDescriptor}s on `--sidecars`, and the channel dynamic-imports
- * each `module`, calls `mod[export ?? "default"](options)`, and mounts the
- * result (a bad descriptor is logged + skipped there).
- *
- * This module is the CLI's half: a small registry of the sidecars the launcher
- * knows how to construct, plus a pure resolver that decides which are on for a
- * given project root and set of `--aiui-sidecar` / `--aiui-no-sidecar` flags.
- */
-/**
- * The contract the channel's `--sidecars` argument expects, mirrored here so
- * the CLI can emit it. The channel imports `module`, calls its `export` (or
- * `default`) with `options`, and mounts the returned sidecar.
- */
-export interface SidecarDescriptor {
-    /** Stable identifier, used for `--aiui-sidecar`/`--aiui-no-sidecar` and logs. */
-    name: string;
-    /** Importable specifier the channel `import()`s (e.g. a package subpath). */
-    module: string;
-    /** Named export to call as the factory. Defaults to `"default"`. */
-    export?: string;
-    /** Passed opaquely to the factory (e.g. `{ root: "/proj" }`). */
-    options?: unknown;
-}
-/** Resolves a package specifier to an absolute path the channel can `import()`. */
-type ResolveModule = (specifier: string) => string;
-/** Injectable seams, so the resolver is unit-testable without on-disk state. */
-export interface ResolveSidecarsDeps {
-    /**
-     * Resolves a sidecar's package specifier to an ABSOLUTE path. Defaults to
-     * `createRequire(import.meta.url).resolve`. This matters: the channel
-     * dynamic-imports the descriptor's `module`, but it does NOT depend on any
-     * sidecar package — so a bare specifier resolves from the channel's own
-     * node_modules and fails (pnpm's isolated layout). Resolving here (from the
-     * `aiui` CLI, which DOES depend on the sidecar package) to an absolute path
-     * makes the import work in both the source-first workspace and an install.
-     */
-    resolveModule?: ResolveModule;
-    /** Warning sink for a sidecar that had to be dropped (defaults to stderr). */
-    log?: (message: string) => void;
-}
-/**
- * Decide which session sidecars to host for `root`.
- *
- * Starts from the auto-detected set (each known sidecar whose `autoEnable`
- * predicate is truthy for this root), then applies the flags: `opts.enable`
- * force-adds a known sidecar by name even when it wouldn't auto-detect, and
- * `opts.disable` removes one. Disable wins over enable. Enable names the CLI
- * doesn't know how to construct are ignored (the launcher can only build the
- * sidecars in {@link KNOWN_SIDECARS}). Descriptors come back in the registry's
- * stable order.
- */
-export declare function resolveSidecars(root: string, opts: {
-    enable: string[];
-    disable: string[];
-}, deps?: ResolveSidecarsDeps): SidecarDescriptor[];
-export {};

package/templates/demo/CLAUDE.md

@@ -1,16 +0,0 @@
-# aiui demo playground
-
-This directory is a scaffolded, disposable aiui demo — a sandbox the user is exploring the aiui
-workflow in. Ground rules for working here:
-
-- **The app is scenery.** `src/main.ts` renders a fake "spectra" viewer purely so there's
-  something to point at and modify. Redesign it, extend it, replace it — that's the point of the
-  demo. Prefer small, visible changes the user can watch land.
-- **Don't remove the integration.** The `aiuiDevOverlay()` plugin in `vite.config.ts` is what
-  mounts the intent tool and connects it to this session's channel. The demo stops working
-  without it.
-- The dev server runs via `npm run dev` (which is `aiui vite dev` — it injects the channel port
-  as `VITE_AIUI_PORT`). Plain `vite` also serves the app, but the intent tool won't find the
-  channel.
-- This is a standalone git repo scaffolded by `aiui demo`; commit freely — history here belongs
-  to the user's sandbox and goes nowhere else.

package/templates/demo/README.md

@@ -1,36 +0,0 @@
-# aiui demo playground
-
-A disposable sandbox for trying [aiui](https://habemus-papadum.github.io/pdum_aiui/): a Claude
-Code session with a custom channel, a shared agent+human browser, and a web intent tool floating
-over a demo app. It's a local git repo of its own — let the agent redesign, break, and rebuild
-the app; nothing flows back anywhere.
-
-> ⚠️ First read *Read before running* in the aiui docs: `aiui claude` can skip permissions and
-> gives the agent a browser. This sandbox assumes you've decided to trust it.
-
-## Run it
-
-```sh
-npm run claude   # terminal 1 — Claude Code with the aiui channel + session browser
-npm run dev      # terminal 2 — the demo app (Vite + the intent tool overlay)
-```
-
-Then open the app **in the session browser** (the window you share with the agent):
-
-```sh
-npx aiui open http://localhost:5173
-```
-
-Click the floating **✳ aiui** button, type an intent — *"make the baseline curve red"* — and
-watch it land in the Claude session as a prompt. The 🔍 button shows how your input was lowered
-into that prompt.
-
-## What's what
-
-- `vite.config.ts` — the **entire** aiui integration: one `aiuiDevOverlay()` plugin. This is the
-  part you'd copy into your own app.
-- `src/main.ts` — throwaway scenery (a fake spectrum viewer). No aiui code in it.
-- Re-running the scaffold command in this directory just picks up where you left off — it never
-  overwrites your (or the agent's) changes.
-
-Docs: <https://habemus-papadum.github.io/pdum_aiui/guide/getting-started>

package/templates/demo/gitignore

@@ -1,4 +0,0 @@
-node_modules/
-dist/
-.aiui-cache/
-*.log

package/templates/demo/index.html

@@ -1,11 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>spectra — aiui demo playground</title>
-  </head>
-  <body>
-    <script type="module" src="/src/main.ts"></script>
-  </body>
-</html>

package/templates/demo/package.json

@@ -1,23 +0,0 @@
-{
-  "name": "aiui-demo-playground",
-  "private": true,
-  "type": "module",
-  "aiui": {
-    "demo": true
-  },
-  "scripts": {
-    "claude": "aiui claude",
-    "dev": "aiui vite dev",
-    "open": "aiui open"
-  },
-  "dependencies": {
-    "@habemus-papadum/aiui-dev-overlay": "__AIUI_VERSION_RANGE__"
-  },
-  "devDependencies": {
-    "@babel/core": "^7.29.7",
-    "@habemus-papadum/aiui": "__AIUI_VERSION_RANGE__",
-    "typescript": "^5.6.0",
-    "typescript-language-server": "^5.3.0",
-    "vite": "^6.4.1"
-  }
-}

package/templates/demo/src/main.ts

@@ -1,51 +0,0 @@
-/**
- * The demo app: a fake "scientific UI" the intent tool mounts over.
- *
- * The app itself is throwaway scenery (an SVG spectrum plot) — note there is
- * **no aiui code in here at all**. The whole integration is the
- * `aiuiDevOverlay()` plugin in vite.config.ts, which injects and mounts the
- * widget into every served page. Run it the intended way:
- *
- *   terminal 1:  npm run claude    (Claude Code with the aiui channel + browser)
- *   terminal 2:  npm run dev       (this app, via `aiui vite`)
- *
- * then open the printed URL in the session browser
- * (`npx aiui open http://localhost:5173`), click the ✳ aiui button, type
- * something — "make the baseline curve red", say — and watch it arrive in the
- * session. The 🔍 button opens the lowering-trace debugger.
- *
- * This playground is yours: let the agent redesign it, break it, rebuild it.
- * Nothing here flows back upstream.
- */
-
-document.body.innerHTML = `
-  <style>
-    body { margin: 0; background: #0f1117; color: #e8e8ea; font: 14px/1.5 ui-sans-serif, system-ui; }
-    header { padding: 18px 28px 6px; }
-    h1 { font-size: 17px; margin: 0; } h1 span { color: #8ab4f8; }
-    .sub { color: #9aa0aa; font-size: 12px; }
-    main { padding: 10px 28px; }
-    .card { background: #171b25; border: 1px solid #262c3a; border-radius: 12px; padding: 16px 18px; max-width: 720px; }
-    .legend { display: flex; gap: 14px; font-size: 11px; color: #9aa0aa; margin-top: 8px; }
-    .legend i { display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 4px; vertical-align: -1px; }
-  </style>
-  <header>
-    <h1><span>spectra</span> · absorption viewer</h1>
-    <div class="sub">demo app for the aiui web intent tool — the widget in the corner is the tool</div>
-  </header>
-  <main>
-    <div class="card">
-      <svg viewBox="0 0 640 220" width="100%" role="img" aria-label="demo spectrum plot">
-        <g stroke="#262c3a"><line x1="40" y1="10" x2="40" y2="190"/><line x1="40" y1="190" x2="620" y2="190"/>
-        <line x1="40" y1="55" x2="620" y2="55" stroke-dasharray="3 5"/><line x1="40" y1="100" x2="620" y2="100" stroke-dasharray="3 5"/>
-        <line x1="40" y1="145" x2="620" y2="145" stroke-dasharray="3 5"/></g>
-        <polyline fill="none" stroke="#8ab4f8" stroke-width="2"
-          points="40,180 90,176 130,168 165,120 185,60 205,38 225,64 260,150 310,170 355,162 390,132 420,90 445,74 470,96 510,158 560,174 620,178"/>
-        <polyline fill="none" stroke="#7ee0a3" stroke-width="2" stroke-dasharray="5 4"
-          points="40,185 100,182 150,176 200,150 250,120 300,104 350,110 400,128 450,148 500,164 560,175 620,180"/>
-        <g fill="#9aa0aa" font-size="10"><text x="30" y="200" text-anchor="end">400</text><text x="330" y="205" text-anchor="middle">wavelength (nm)</text><text x="620" y="200" text-anchor="end">700</text></g>
-      </svg>
-      <div class="legend"><span><i style="background:#8ab4f8"></i>sample A-113</span><span><i style="background:#7ee0a3"></i>baseline</span></div>
-    </div>
-  </main>
-`;

package/templates/demo/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "types": ["vite/client"]
-  },
-  "include": ["src", "vite.config.ts"]
-}

package/templates/demo/vite.config.ts

@@ -1,17 +0,0 @@
-import aiuiDevOverlay from "@habemus-papadum/aiui-dev-overlay/vite";
-import { defineConfig } from "vite";
-
-// This one plugin is the entire aiui integration — the part to copy into your
-// own app. It mounts the intent tool into every served page, declares the
-// message format the tool speaks, and bridges the channel port from
-// `aiui vite` (VITE_AIUI_PORT in this dev server's env) plus this app's source
-// root into the browser.
-//
-// `locator` turns on compile-time source stamping: every host JSX element gets
-// data-source-loc = "src/…:line:col", and `cell()` call sites get their
-// `{ name, loc }` identity injected — so anything you build here is legible to
-// an agent (the `locate` tool) out of the box. It needs @babel/core (an
-// optional peer, provided as a devDependency of this sandbox).
-export default defineConfig({
-  plugins: [aiuiDevOverlay({ format: "text-concat", locator: { cellFactories: ["cell"] } })],
-});