@habemus-papadum/aiui 0.2.0 → 0.3.0

package/dist/util/config.d.ts

@@ -1,82 +1,48 @@
+import { type ChannelBind, type ChromeChannel, type ChromeMode, type ForTestingMode } from "./config-schema";
+export { CHANNEL_BINDS, CHROME_CHANNELS, CHROME_MODES, type ChannelBind, type ChromeChannel, type ChromeMode, FOR_TESTING_MODES, type ForTestingMode, } from "./config-schema";
 export declare const CONFIG_FILENAME = "config.json";
-export declare const CHROME_CHANNELS: readonly ["stable", "beta", "dev", "canary"];
-export type ChromeChannel = (typeof CHROME_CHANNELS)[number];
-export declare const FOR_TESTING_MODES: readonly ["prompt", "auto", "off"];
-export type ForTestingMode = (typeof FOR_TESTING_MODES)[number];
-export declare const CHROME_MODES: readonly ["attach", "launch"];
-export type ChromeMode = (typeof CHROME_MODES)[number];
+/**
+ * The typed shape of a config file. Must mirror `CONFIG_SECTIONS` in
+ * config-schema.ts — the schema rows carry the full per-key documentation and
+ * defaults; the comments here are just orientation.
+ */
 export interface AiuiConfig {
     claude?: {
-        /**
-         * Launch Claude Code with `--dangerously-skip-permissions`. A personal
-         * preference with real consequences (see docs/guide/warning) — the first
-         * interactive launch asks and persists the answer here; when unset in a
-         * non-interactive session it defaults to true.
-         */
+        /** Launch Claude Code with `--dangerously-skip-permissions`. */
         skipPermissions?: boolean;
-        /**
-         * Auto-dismiss Claude Code's development-channel acknowledgement prompt
-         * by injecting an Enter keypress into the terminal at startup (see
-         * util/enter-nudge.ts). Chosen on first interactive run; defaults to true
-         * when unset.
-         */
+        /** Auto-dismiss Claude Code's development-channel prompt (util/enter-nudge.ts). */
         enterNudge?: boolean;
     };
+    channel?: {
+        /** Which interface the channel web server binds: loopback (default) or host (LAN). */
+        bind?: ChannelBind;
+    };
+    sidecars?: {
+        /** Host the iPad paint sidecar on the channel's port (default: true). */
+        paint?: boolean;
+    };
     chrome?: {
-        /**
-         * Attach the Chrome DevTools MCP (default: true). `false` turns it off
-         * everywhere; `true` does not override the CI default-off — only the
-         * `--aiui-chrome` flag forces it on under CI.
-         */
+        /** Attach the Chrome DevTools MCP (default: true). */
         enabled?: boolean;
-        /**
-         * How the MCP reaches a browser (default: "attach"). `"attach"` shares a
-         * user-visible session browser: an already-running one is discovered by
-         * profile, or an interactive launch starts one eagerly. `"launch"` is the
-         * hands-off mode: chrome-devtools-mcp launches its own private browser
-         * lazily, on the agent's first browser tool call.
-         */
+        /** How the MCP reaches a browser: shared session browser, or its own. */
         mode?: ChromeMode;
-        /**
-         * Attach to this Chrome DevTools endpoint (e.g. "http://127.0.0.1:9222")
-         * instead of managing a browser at all — the remote-development key: the
-         * browser runs on another machine (started there with `aiui browser`) and
-         * its port is tunneled over. Setting it implies `mode: "attach"` and makes
-         * every local-browser setting (profile, executablePath, channel,
-         * forTesting…) irrelevant.
-         */
+        /** Attach to this DevTools endpoint instead of managing a browser at all. */
         browserUrl?: string;
-        /**
-         * Fixed DevTools debug port for session browsers aiui launches
-         * (default: 0 — an OS-assigned free port). Pin it (e.g. 9222) when
-         * something else must find the port, like an ssh tunnel.
-         */
+        /** Fixed DevTools debug port for session browsers aiui launches (0 = OS-assigned). */
         debugPort?: number;
         /** Named profile under `.aiui-cache/chrome/` (default: "default"). */
         profile?: string;
         /** Explicit Chrome user data dir; takes precedence over `profile`. */
         dataDir?: string;
-        /**
-         * Chrome binary to launch — e.g. a Chrome for Testing install, which
-         * still honors `--load-extension`. Mutually exclusive with `channel`.
-         */
+        /** Chrome binary to launch. Mutually exclusive with `channel`. */
         executablePath?: string;
-        /** Installed Chrome release channel to launch (default: stable). */
+        /** Installed Chrome release channel to launch. */
         channel?: ChromeChannel;
-        /**
-         * How `aiui claude` manages Chrome for Testing, the recommended browser
-         * (default: "prompt"). `"prompt"` asks before installing or updating it —
-         * interactive sessions only, never under CI; `"auto"` installs/updates
-         * without asking; `"off"` never checks. Skipped entirely when
-         * `executablePath` or `channel` picks a browser explicitly.
-         */
+        /** How `aiui claude` manages the Chrome for Testing install. */
         forTesting?: ForTestingMode;
         /** Launch Chrome headless (default: false). */
         headless?: boolean;
-        /**
-         * In a dev checkout, rebuild the aiui-devtools-extension package (~0.3s of tsc)
-         * on every launch so the auto-loaded panel is never stale (default: true).
-         */
+        /** Rebuild the aiui-devtools-extension on every launch in a dev checkout. */
         buildExtension?: boolean;
     };
 }
@@ -102,3 +68,9 @@ export declare function readConfigFile(file: string): AiuiConfig | undefined;
  * in the project file, which may be shared/committed by a team.
  */
 export declare function updateUserConfig(mutate: (config: AiuiConfig) => void): string;
+/**
+ * Persist a change to a specific config file — the general form behind
+ * {@link updateUserConfig}, and how `aiui config set --project` writes the
+ * project level deliberately.
+ */
+export declare function updateConfigFile(file: string, mutate: (config: AiuiConfig) => void): string;

package/dist/util/first-run.d.ts

@@ -2,15 +2,18 @@
  * First-run choices: settings that deserve a deliberate answer, not a silent
  * default.
  *
- * Two of `aiui claude`'s behaviors are pure personal preference with real
- * consequences: whether to launch with `--dangerously-skip-permissions`, and
+ * Three of `aiui claude`'s behaviors are pure personal preference with real
+ * consequences: whether to launch with `--dangerously-skip-permissions`,
  * whether to auto-dismiss the development-channel acknowledgement prompt by
- * typing into the user's terminal. Neither should be something the user
- * "tagged along" with because a default existed — so the first interactive
- * launch asks (definitively: the prompts have no Enter-through default), and
- * the answers persist to the **user-level** config, after which nothing asks
- * again. Non-interactive sessions never prompt; unset values fall back to the
- * documented defaults (skip: true, nudge: true).
+ * typing into the user's terminal, and whether the channel's web server binds
+ * loopback-only or the host interface (the trusted-LAN posture that makes the
+ * whole unauthenticated surface — iPad paint page included — reachable from
+ * the network). None should be something the user "tagged along" with because
+ * a default existed — so the first interactive launch asks (definitively: the
+ * prompts have no Enter-through default), and the answers persist to the
+ * **user-level** config, after which nothing asks again. Non-interactive
+ * sessions never prompt; unset values fall back to the documented defaults
+ * (skip: true, nudge: true, bind: loopback).
  */
 import { type AiuiConfig } from "./config";
 import { type Choice } from "./prompt";

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

@@ -11,8 +11,9 @@
  *
  * So the launcher's whole job is to *preflight* that env var and tell the user
  * what it found — degradation, not refusal. A missing or rejected key never
- * blocks the launch; the modality still mounts and transcription/correction
- * fall back to mock/off. The most valuable case this catches is the one that
+ * 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
  * shell export** shadowing the real key, which surfaces as a confusing 401 deep
  * in the pipeline rather than a clear message up front.

package/dist/util/resolve-cli.d.ts

@@ -1,14 +1,4 @@
-/**
- * Absolute root directory of an installed (or workspace-linked) dependency.
- *
- * Rather than resolve the package *through* the module system — which would hit
- * its `exports` map (forcing a built `dist/`, and normally blocking access to
- * `package.json`) — we ask Node for the `node_modules` dirs it would search and
- * read `package.json` straight off disk. This needs nothing special from the
- * target package (no `exports` entry) and works even when it has not been
- * built, so dev iteration requires no compile step.
- */
-export declare function packageRoot(packageName: string): string;
+export { packageRoot } from "@habemus-papadum/aiui-util";
 /** How to spawn a CLI: a program plus the args that precede any subcommand. */
 export interface CliInvocation {
     command: string;

package/dist/util/sidecars.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@habemus-papadum/aiui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ai ui frontends",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -31,15 +32,18 @@
     "access": "public"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
     "@puppeteer/browsers": "^2.10.5",
     "chalk": "^5.3.0",
     "commander": "^15.0.0",
     "execa": "^9.6.1",
     "vite": "^6.4.3",
-    "@habemus-papadum/aiui-claude-plugin": "^0.2.0",
-    "@habemus-papadum/aiui-util": "^0.2.0",
-    "@habemus-papadum/aiui-claude-channel": "^0.2.0",
-    "@habemus-papadum/aiui-devtools-extension": "^0.2.0"
+    "@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"
   },
   "scripts": {
     "build": "tsc --emitDeclarationOnly -p tsconfig.json && vite build",

package/templates/demo/package.json

@@ -16,6 +16,8 @@
   "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/dist/util/browser.d.ts

@@ -1,44 +0,0 @@
-import type { ChromeChannel } from "./config";
-export interface SessionBrowser {
-    /** The DevTools endpoint chrome-devtools-mcp attaches to. */
-    browserUrl: string;
-    port: number;
-}
-/**
- * A live session browser for this profile, if one is running.
- * Never launches anything; safe to call from non-interactive paths.
- */
-export declare function discoverSessionBrowser(userDataDir: string): Promise<SessionBrowser | undefined>;
-/**
- * Which binary a session-browser launch should run: an explicit
- * executablePath (usually the managed Chrome for Testing) wins; otherwise the
- * system install of the requested channel (default stable). Throws when no
- * such browser is installed.
- */
-export declare function sessionBrowserBinary(settings: {
-    executablePath?: string;
-    channel?: ChromeChannel;
-}): string;
-/**
- * Launch the session browser detached (it deliberately outlives the aiui
- * process — it's the user's window too) and wait for its debug endpoint.
- *
- * `debugPort` 0 lets the OS pick a free port; Chrome reports the choice via
- * `DevToolsActivePort`, which is removed first so a stale file from a previous
- * run can't win the poll. Fails fast if the process exits early — the classic
- * cause being an already-running Chrome on the same profile *without* a debug
- * port, which swallows the new invocation as a URL-handoff and exits.
- */
-export declare function launchSessionBrowser(opts: {
-    binary: string;
-    userDataDir: string;
-    debugPort?: number;
-    extensionDir?: string;
-    headless?: boolean;
-    startUrl?: string;
-}): Promise<SessionBrowser>;
-/**
- * Open a URL as a new tab in a session browser, via the DevTools HTTP API
- * (`PUT /json/new` — PUT is required by current Chrome).
- */
-export declare function openInSessionBrowser(browserUrl: string, url: string): Promise<void>;