appduct 0.14.0 → 0.15.1

package/dist/daemon/listener.d.ts

@@ -1,5 +1,6 @@
 /**
- * The pinned-TLS WebSocket listener (ARCHITECTURE.md §7). A thin frame-level gate in front of
+ * The pinned-TLS WebSocket listener and the plain-HTTP web listener (ARCHITECTURE.md §7). Both put
+ * the same thin frame-level gate in front of
  * `SessionManager`: JSON/binary/size hygiene, the pre-claim timeout, and post-claim
  * type/session-id routing. All state-machine decisions (claim/resume/registry/close-code choice)
  * live in sessions.ts — this module never inspects session state itself.
@@ -14,7 +15,13 @@ import { type SessionManager } from "./sessions.js";
 import type { TlsManager, TlsMaterial } from "./tls.js";
 import { type TimerFns } from "./timers.js";
 export type ListenerOptions = {
+    /** `0` asks the OS for a free port. */
     port: number;
+    /** Also bind `127.0.0.1` on the same port (issue #249). macOS lets another program bind
+     * `127.0.0.1:<port>` under a wildcard listener and then routes loopback clients to it; holding
+     * that address ourselves stops it. Linux refuses that bind for everyone, us included, because
+     * the wildcard listener already covers loopback there. */
+    bindLoopback: boolean;
     tls: TlsManager;
     sessionManager: SessionManager;
     preClaimTimeoutMs?: number;
@@ -31,3 +38,23 @@ export type DaemonListener = {
     close: () => Promise<void>;
 };
 export declare const startListener: (options: ListenerOptions) => Promise<DaemonListener>;
+export type WebListenerOptions = {
+    sessionManager: SessionManager;
+    /** Origins allowed in addition to localhost, `127.0.0.1` and `[::1]` on any port. Compared
+     * as exact strings against the `Origin` header (`config.json`'s `webOrigins`). */
+    origins: readonly string[];
+    preClaimTimeoutMs?: number;
+    timers?: TimerFns;
+};
+export type WebListener = {
+    port: () => number | undefined;
+    close: () => Promise<void>;
+};
+/**
+ * The plain-HTTP listener web pages connect to, bound to `127.0.0.1` on an OS-assigned port. A
+ * browser cannot pin the daemon's self-signed certificate, so it cannot use the TLS listener.
+ * Instead every upgrade is checked against its `Origin` header and refused with 403 unless that
+ * is a loopback origin or listed in `origins`. A request with no `Origin` is let through: only a
+ * local non-browser process sends none, and it could connect to the daemon anyway.
+ */
+export declare const startWebListener: (options: WebListenerOptions) => Promise<WebListener>;

package/dist/daemon/rpc-errors.d.ts

@@ -17,3 +17,6 @@ export declare class RpcApplicationError extends Error {
 /** The `session_suspended` message for an app that closed its socket because it went to the
  * background: says why and how to recover. */
 export declare const appBackgroundedMessage: (alias: string) => string;
+/** The `session_suspended` message for a call that was pending when the app reconnected on a new
+ * socket: the app dropped the call with the old socket, so its result is lost. */
+export declare const appReconnectedMessage: (alias: string) => string;

package/dist/daemon/sessions.d.ts

@@ -10,7 +10,7 @@
  * §6: "terminal states free the alias" — there is no persisted history, matching §3/§13's "no
  * per-session files, all state in-daemon-memory").
  */
-import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type SessionSummary, type SessionSuspendReason, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
+import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type LinkTransport, type SessionSummary, type SessionSuspendReason, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
 import type { WebSocket } from "ws";
 import type { Clock } from "../cli/types.js";
 import type { EventBus } from "./event-bus.js";
@@ -26,7 +26,7 @@ export type SessionManagerOptions = {
     graceSeconds: number;
     keepaliveIntervalSeconds: number;
     linkTtlSeconds: number;
-    getEndpoint: () => CreatedLink["endpoint"];
+    getEndpoint: (transport: LinkTransport) => CreatedLink["endpoint"];
     eventBus: EventBus;
     clock?: Clock;
     timers?: TimerFns;
@@ -48,11 +48,15 @@ export type SessionManager = {
      * 07's emulator/simulator fast path); see `links.ts`'s `PendingLinkRegistry.create`. Omits
      * `LinkCreateResult.pin` — the session manager has no `TlsManager` handle, so the RPC handler
      * (`daemon.ts`) attaches the current SPKI pin itself before returning to the caller. */
-    createLink: (ttlSeconds?: number, addressOverride?: string) => Omit<LinkCreateResult, "pin">;
-    /** First message on a fresh socket. Returns the claimed sessionId, or `null` after closing the socket. */
-    handleClaim: (socket: WebSocket, message: SessionClaimMessage) => string | null;
-    /** First message on a resume socket. Returns the resumed sessionId, or `null` after closing the socket. */
-    handleResume: (socket: WebSocket, message: SessionResumeMessage) => string | null;
+    createLink: (ttlSeconds?: number, addressOverride?: string, transport?: LinkTransport) => Omit<LinkCreateResult, "pin">;
+    /** First message on a fresh socket accepted on `transport`'s listener. Returns the claimed
+     * sessionId, or `null` after closing the socket. A link minted for the other transport is
+     * refused with `wrong_transport` and stays claimable on its own listener. */
+    handleClaim: (socket: WebSocket, message: SessionClaimMessage, transport: LinkTransport) => string | null;
+    /** First message on a resume socket accepted on `transport`'s listener. Returns the resumed
+     * sessionId, or `null` after closing the socket. A session claimed on the other listener is
+     * refused with `wrong_transport` before its token is checked, so its token is not rotated. */
+    handleResume: (socket: WebSocket, message: SessionResumeMessage, transport: LinkTransport) => string | null;
     /** Dispatches an already-type-checked post-claim message; closes the socket on invalid content. */
     handlePostClaimMessage: (sessionId: string, socket: WebSocket, message: Record<string, unknown>) => void;
     list: () => SessionSummary[];

package/dist/daemon/tls.d.ts

@@ -23,9 +23,6 @@ export declare class HostKeyError extends Error {
  * Deliberately the same shape as `ConfigWarnFn` (`config.ts`) so callers can pass the same
  * function through without an adapter. */
 export type TlsWarnFn = (message: string) => void;
-/** Refuses a key file that is group/world-readable. Missing files are handled by the caller
- * (`loadOrGenerateHostKeyPem`), which auto-generates instead of throwing. */
-export declare const loadHostKeyPem: (keyPath: string) => Promise<string>;
 /**
  * Loads the host key at `keyPath`, generating one in its place if none exists yet (dev-mode
  * zero-config bootstrap). Only the ENOENT case auto-generates: any other `stat`/`readFile` failure

package/dist/devtools-relay/attach-tab.d.ts

@@ -0,0 +1,33 @@
+import { type RelayLink } from "./relay.js";
+import type { DevtoolsBrowser, DevtoolsPage, OpenDaemonSocket } from "./ports.js";
+export type AttachBrowserTabOptions = {
+    browser: DevtoolsBrowser;
+    /**
+     * The page relayed for each target id. Attaching a tab closes the page already relayed for it, so a
+     * tab has one relay however its browser was reached; the new page is recorded here as soon as it is open.
+     */
+    relayedTabs: Map<string, DevtoolsPage>;
+    /** The tab's address, or the start of it. */
+    url: string;
+    /** Picks the tab directly, for when several tabs match `url`. */
+    targetId?: string;
+    /** Mints the web link for the page. Called once a tab is picked, so a failed pick strands no link. */
+    mintLink: () => Promise<RelayLink & {
+        sessionId: string;
+        expiresAt: number;
+    }>;
+    openDaemonSocket: OpenDaemonSocket;
+};
+/** `url` is the tab's own address, without the link's payload. */
+export type AttachedTab = {
+    sessionId: string;
+    url: string;
+    targetId: string;
+    expiresAt: number;
+};
+/**
+ * Picks a tab of a debugging-port browser, relays its page to the daemon and connects it over the
+ * binding, so the session outlives this call. The page must already load `@appduct/web`. Reloading
+ * resumes the session; a popup or a navigation that creates a new target is not relayed.
+ */
+export declare const attachBrowserTab: (options: AttachBrowserTabOptions) => Promise<AttachedTab>;

package/dist/devtools-relay/index.d.ts

@@ -0,0 +1,8 @@
+export { createMemoryDaemonSockets, type MemoryDaemonSocket, type MemoryDaemonSockets } from "./memory-daemon-sockets.js";
+export { attachBrowserTab, type AttachBrowserTabOptions, type AttachedTab } from "./attach-tab.js";
+export { createMemoryDevtoolsBrowser, type MemoryDevtoolsBrowser } from "./memory-devtools-browser.js";
+export { createMemoryPageChannel, type MemoryPageChannel } from "./memory-page-channel.js";
+export { connectNodeDevtoolsBrowser } from "./node-devtools-browser.js";
+export { openNodeDaemonSocket } from "./node-daemon-socket.js";
+export type { ConnectDevtoolsBrowser, DaemonSocket, DaemonSocketEvents, DevtoolsBrowser, DevtoolsPage, DevtoolsTarget, OpenDaemonSocket, PageChannel } from "./ports.js";
+export { linkPayload, parseLink, relayPage, type RelayLink } from "./relay.js";

package/dist/devtools-relay/memory-daemon-sockets.d.ts

@@ -0,0 +1,20 @@
+import type { OpenDaemonSocket } from "./ports.js";
+/** One daemon socket the relay opened, driven by the test. */
+export type MemoryDaemonSocket = {
+    readonly url: string;
+    /** Text frames the relay sent, in order. */
+    readonly sent: string[];
+    /** How the relay closed the socket, once it did. */
+    readonly closedByRelay: {
+        code: number;
+        reason: string;
+    } | undefined;
+    open(): void;
+    receive(text: string): void;
+    closeFromDaemon(code: number, reason: string): void;
+};
+export type MemoryDaemonSockets = {
+    open: OpenDaemonSocket;
+    readonly sockets: MemoryDaemonSocket[];
+};
+export declare const createMemoryDaemonSockets: () => MemoryDaemonSockets;

package/dist/devtools-relay/memory-devtools-browser.d.ts

@@ -0,0 +1,10 @@
+import type { DevtoolsBrowser, DevtoolsTarget } from "./ports.js";
+import { type MemoryPageChannel } from "./memory-page-channel.js";
+export type MemoryDevtoolsBrowser = DevtoolsBrowser & {
+    /** The tab's page, as the relay sees it: the one the next `openPage` returns, then the latest it returned. */
+    page(targetId: string): MemoryPageChannel;
+    /** Target ids passed to `openPage`, in order, that have not been closed since. */
+    attachedTargets(): string[];
+};
+/** A browser with the given tabs, each backed by a memory page channel. */
+export declare const createMemoryDevtoolsBrowser: (tabs: DevtoolsTarget[]) => MemoryDevtoolsBrowser;

package/dist/devtools-relay/memory-page-channel.d.ts

@@ -0,0 +1,16 @@
+import type { PageChannel } from "./ports.js";
+export type MemoryPageChannel = PageChannel & {
+    /** The page calls its binding with an object, sent as JSON. */
+    call(message: Record<string, unknown>): void;
+    /** The document is destroyed. */
+    resetContext(): void;
+    /** The connection is dropped: the context resets once, then the page stops calling the relay. */
+    close(): void;
+    /** What the relay delivered to `__APPDUCT__.receive`, parsed. */
+    received(): Record<string, unknown>[];
+    /** Every other expression evaluated in the page, in order. */
+    evaluated(): string[];
+    /** Makes `evaluate` reject for expressions matching `pattern`. */
+    failEvaluate(pattern: RegExp, error: Error): void;
+};
+export declare const createMemoryPageChannel: () => MemoryPageChannel;

package/dist/devtools-relay/node-daemon-socket.d.ts

@@ -0,0 +1,3 @@
+import type { OpenDaemonSocket } from "./ports.js";
+/** A `ws` client. It sends no `Origin`, which the daemon's web listener lets through. */
+export declare const openNodeDaemonSocket: OpenDaemonSocket;

package/dist/devtools-relay/node-devtools-browser.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectDevtoolsBrowser } from "./ports.js";
+/** A browser reached over its HTTP debugging endpoint, one raw-CDP WebSocket per relayed tab. */
+export declare const connectNodeDevtoolsBrowser: ConnectDevtoolsBrowser;

package/dist/devtools-relay/ports.d.ts

@@ -0,0 +1,48 @@
+/** What the relay needs from outside the process. Each port has a memory fake beside it. */
+/** The page the session runs in, as the relay sees it. A Playwright `Page` is adapted to this by `attachPage`. */
+export type PageChannel = {
+    /** Calls the page makes to its exposed binding, as the JSON string it passed. */
+    onBindingCall(handler: (json: string) => void): void;
+    /** Runs an expression in the page's current document. Rejects when there is none. */
+    evaluate(expression: string): Promise<unknown>;
+    /** A document was destroyed or replaced: a reload, a navigation to another document, or the page closing. */
+    onContextReset(handler: () => void): void;
+};
+export type DaemonSocketEvents = {
+    open(): void;
+    message(text: string): void;
+    close(code: number, reason: string): void;
+};
+export type DaemonSocket = {
+    send(text: string): void;
+    close(code: number, reason: string): void;
+};
+/** Opens a WebSocket to the daemon's web listener, with no `Origin`. */
+export type OpenDaemonSocket = (url: string, events: DaemonSocketEvents) => DaemonSocket;
+/** A tab the browser lists. */
+export type DevtoolsTarget = {
+    /** The CDP target id, stable for the life of the tab. */
+    id: string;
+    url: string;
+    title: string;
+};
+/** A tab opened for relaying: the page channel plus the way to let go of it. */
+export type DevtoolsPage = PageChannel & {
+    /** Drops the tab's binding connection. The page keeps running; it just has no relay. */
+    close(): void;
+};
+/** A Chromium launched with `--remote-debugging-port`, as the daemon sees it. */
+export type DevtoolsBrowser = {
+    /** The open tabs, in the order the browser lists them. Rejects when the browser cannot be reached. */
+    targets(): Promise<DevtoolsTarget[]>;
+    /**
+     * Opens the tab for relaying: `window.__appductBinding(json)` exists in its current document and in
+     * every later one, and `onContextReset` fires when its document is destroyed or the tab closes.
+     * Opening a tab that is already open drops the earlier connection.
+     */
+    openPage(targetId: string): Promise<DevtoolsPage>;
+    /** Drops every connection `openPage` made. */
+    close(): void;
+};
+/** Reaches the browser whose debugging endpoint is `browserUrl`, such as `http://127.0.0.1:9222`. */
+export type ConnectDevtoolsBrowser = (browserUrl: string) => DevtoolsBrowser;

package/dist/devtools-relay/relay.d.ts

@@ -0,0 +1,16 @@
+import { type BootstrapPayload } from "@appduct/shared";
+import type { OpenDaemonSocket, PageChannel } from "./ports.js";
+/** A link from `link({ target: "web", url })`: the page URL with `#appduct=<payload>`. */
+export type RelayLink = {
+    url: string;
+};
+/** The bootstrap payload in the link's fragment. */
+export declare const linkPayload: (link: RelayLink) => string;
+/** The bootstrap a link carries; throws when the link has no payload or the payload is not an Appduct link. */
+export declare const parseLink: (link: RelayLink) => BootstrapPayload;
+/**
+ * Carries one page's session frames between the page's binding and the daemon's web listener. The
+ * page asks for a daemon socket when its transport opens, and the relay closes it when the page's
+ * document is destroyed, so the daemon suspends the session and the reloaded page resumes it.
+ */
+export declare const relayPage: (page: PageChannel, link: RelayLink, openDaemonSocket: OpenDaemonSocket) => void;

package/dist/index.js

@@ -126,8 +126,11 @@ var createCli = () => {
     `link: deep-link URI scheme (also: APPDUCT_SCHEME; default: .appduct/config.json, then app.json's "expo.scheme", then the Android/iOS project files in <cwd>).`
   ).option(
     "--open <target>",
-    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
-  ).option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
+    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental), or with `web <url>` return the page URL and a connect script for a web page."
+  ).option(
+    "--browser-url <url>",
+    "link: with --open web, attach the tab of a Chrome launched with --remote-debugging-port (such as http://127.0.0.1:9222) and claim a session on it."
+  ).option("--target-id <id>", "link: with --browser-url, the CDP target id of the tab to attach when several tabs match <url>.").option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
     "--app-id <id>",
     `link: installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
   ).option(
@@ -169,6 +172,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -229,6 +233,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -299,6 +304,12 @@ var loadConfig = async (paths, options = {}) => {
       "restartDaemonOnVersionMismatch"
     );
   }
+  if (parsed.webOrigins !== void 0) {
+    if (!Array.isArray(parsed.webOrigins)) {
+      throw configError("webOrigins", "must be an array of origin strings.");
+    }
+    config.webOrigins = parsed.webOrigins.map((origin) => requireNonEmptyString(origin, "webOrigins"));
+  }
   if (parsed.policy !== void 0) {
     if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
       throw configError("policy", "must be an object.");
@@ -407,7 +418,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
   // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
   // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -882,6 +893,36 @@ var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -1002,6 +1043,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],

package/dist/link.d.ts

@@ -17,7 +17,7 @@
  * (`sha256/<44-char-base64>`, may contain `+`/`/`/`=`), so it is percent-encoded here; native/JS
  * parsers use `URLSearchParams`, which decodes it back.
  */
-import { type AgentEndpoint, type LinkCreateResult } from "@appduct/shared";
+import { type AgentEndpoint, type LinkCreateResult, type WebAttachParams, type WebAttachResult } from "@appduct/shared";
 import { type ExecFn, type OpenTarget } from "./cli/open-target.js";
 import { type SpawnFn } from "./rpc/client.js";
 /**
@@ -30,6 +30,40 @@ import { type SpawnFn } from "./rpc/client.js";
  * *after* the bootstrap blob, so anything reading `appduct=` must stop at the `&`.
  */
 export declare const composeDeepLink: (scheme: string, result: LinkCreateResult) => string;
+/** What a web target hands back instead of a deep link: the page URL to open, and the script to
+ * run in an already-open page. Both carry the same bootstrap payload. */
+export type WebLinkResult = {
+    sessionId: string;
+    /** The page URL with `#appduct=<payload>` appended (replacing any fragment it had). */
+    url: string;
+    script: string;
+    /** Unix seconds. */
+    expiresAt: number;
+};
+/** Throws a usage error unless `pageUrl` is an http(s) URL. Called before a link is minted, so a
+ * bad URL does not strand a pending link. */
+export declare const assertWebPageUrl: (pageUrl: string) => void;
+/** Composes the web target's result from a `link.create` result minted with `transport: "web"`. */
+export declare const composeWebLink: (pageUrl: string, result: LinkCreateResult) => WebLinkResult;
+export type MintWebLinkOptions = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    autoSpawn?: boolean;
+    ttlSeconds?: number;
+    /** The page the link will be opened in. */
+    url: string;
+};
+/** Mints a link only the web listener accepts. Needs no scheme: a web page is reached by URL. */
+export declare const mintWebLink: (options: MintWebLinkOptions) => Promise<WebLinkResult>;
+export type AttachWebTabOptions = WebAttachParams & {
+    stateDir: string;
+    spawn?: SpawnFn;
+    autoSpawn?: boolean;
+};
+/** Asks the daemon to attach a tab of the debugging-port browser at `browserUrl` and claim a session on it. */
+export declare const attachWebTab: ({ stateDir, spawn, autoSpawn, ...params }: AttachWebTabOptions) => Promise<WebAttachResult & {
+    attached: true;
+}>;
 export type MintLinkOptions = {
     stateDir: string;
     spawn?: SpawnFn;

package/dist/mcp/connect-tool.d.ts

@@ -11,7 +11,9 @@
  * caller asked for it with `target: "none"`), where it carries explicit instructions telling the
  * agent to show the code and ask.
  */
+import { type WebAttachResult } from "@appduct/shared";
 import { type ExecFn, type OpenTarget } from "../cli/open-target.js";
+import { type WebLinkResult } from "../link.js";
 import { type SpawnFn } from "../rpc/client.js";
 import type { DaemonCall } from "./daemon-tools.js";
 export declare const CONNECT_TOOL_NAME = "appduct_connect";
@@ -24,7 +26,16 @@ export declare const CONNECT_TOOL_DESCRIPTOR: {
         readonly properties: {
             readonly target: {
                 readonly type: "string";
-                readonly enum: readonly ["android", "ios-sim", "ios-device", "none"];
+                readonly enum: readonly ["android", "ios-sim", "ios-device", "none", "web"];
+            };
+            readonly url: {
+                readonly type: "string";
+            };
+            readonly browserUrl: {
+                readonly type: "string";
+            };
+            readonly targetId: {
+                readonly type: "string";
             };
             readonly device: {
                 readonly type: "string";
@@ -108,7 +119,9 @@ export type ConnectToolResult = {
     /** Present only on the QR path: what the agent must do before waiting. See {@link QR_INSTRUCTIONS}. */
     instructions?: string;
 };
-export declare const handleConnectTool: (rawArgs: unknown, deps: ConnectToolDeps) => Promise<ConnectToolResult>;
+export declare const handleConnectTool: (rawArgs: unknown, deps: ConnectToolDeps) => Promise<ConnectToolResult | WebLinkResult | (WebAttachResult & {
+    attached: true;
+})>;
 export type WaitForSessionToolDeps = {
     stateDir: string;
     spawn?: SpawnFn;

package/dist/native-scheme.d.ts

@@ -1,6 +1,5 @@
 /**
- * Static-file scheme discovery for plain iOS (Xcode) and Android (Gradle) apps
- * (docs/tasks/20-cli-native-scheme-discovery.md, phase 3 of issue #48).
+ * Static-file scheme discovery for plain iOS (Xcode) and Android (Gradle) apps.
  *
  * `scheme.ts`'s `resolveScheme` treats this module as one more thing to try after `<cwd>/app.json`
  * — it never walks up (an app root is where these commands run, same rule as `app.json`), and,
@@ -8,6 +7,8 @@
  * `xcodebuild`, no Gradle evaluation. Every probe is a plain read of a well-known project file,
  * parsed defensively:
  *
+ * - Flutter (a root with a `pubspec.yaml`): the Android probes below read `android/app/…` instead
+ *   of `app/…`; the iOS walk already reaches `ios/Runner` and `macos/Runner`.
  * - Android: `app/build.gradle.kts` / `app/build.gradle` for a `manifestPlaceholders["appductScheme"]`
  *   (or `.appductScheme =`) assignment, then `app/src/main/AndroidManifest.xml` for the first
  *   `<data android:scheme>` inside an intent filter that also declares
@@ -35,19 +36,22 @@ export type NativeSchemeProbeResult = {
     origin: string;
 };
 export type NativeSchemeDiscovery = {
-    /** `undefined` when no probe resolved a scheme. */
-    result?: NativeSchemeProbeResult;
+    /** Every probe that resolved a scheme, in probe order (all agree on the scheme, or discovery
+     * throws). Empty when none did. */
+    results: NativeSchemeProbeResult[];
     /** Every probe's human-readable description, in order, for {@link describeMissingScheme}-style
      * reporting — always as many entries as there are probes, whether or not any of them hit. */
     tried: string[];
 };
+/** Whether `root` is a Flutter project root: it has a `pubspec.yaml`. */
+export declare const isFlutterProject: (root: string) => Promise<boolean>;
 /**
  * Runs every static-file probe against `root` (never walking up — same rule as `app.json`) and
  * decides the result:
  *
- * - No probe resolves a scheme: `result` is `undefined`.
- * - Every probe that resolves one agrees: that scheme wins, attributed to whichever probe ran
- *   first (the order in {@link PROBES}).
+ * - No probe resolves a scheme: `results` is empty.
+ * - Every probe that resolves one agrees: `results` holds each of them in the order of
+ *   {@link PROBES}, so a caller can see every platform the project spans, not one winner.
  * - Two probes resolve *different* schemes: throws a usage error naming both sources and their
  *   values, since guessing which one is right would silently target the wrong app on one
  *   platform.

package/dist/scheme.d.ts

@@ -39,7 +39,7 @@
  * redirects the state directory — `--state-dir` / `APPDUCT_STATE_DIR` remain the only way to do
  * that — so a project file can never move the daemon's key, socket or audit log.
  */
-import { type NativeSchemeSource } from "./native-scheme.js";
+import { type NativeSchemeProbeResult, type NativeSchemeSource } from "./native-scheme.js";
 /** The directory a project-level config lives in, relative to an app root. */
 export declare const PROJECT_CONFIG_DIR = ".appduct";
 /** The project-level config filename, inside {@link PROJECT_CONFIG_DIR}. */
@@ -85,6 +85,10 @@ export type StaticProjectSchemeDiscovery = {
      * it) — distinct from `tried` below, which lists every location whether or not it hit. Only set
      * alongside `scheme`. */
     origin?: string;
+    /** Every native-project probe that resolved a scheme, in probe order — `scheme`, `source` and
+     * `origin` are the first of them. Empty when `app.json` answered (the native probes do not run)
+     * or nothing did; the platforms a project spans are read from here. */
+    nativeResults: NativeSchemeProbeResult[];
     /** Every location this step consulted, in order: `app.json` first (unchanged from pre-#48), then
      * every `native-scheme.ts` probe — always present, hit or miss, one entry each. */
     tried: string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appduct",
-  "version": "0.14.0",
-  "description": "Driving React Native tools without in-app debug UI.",
+  "version": "0.15.1",
+  "description": "Call functions inside your running iOS, Android or React Native app from a terminal, test or AI agent.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,6 +24,8 @@
   },
   "keywords": [
     "appduct",
+    "ios",
+    "android",
     "react-native",
     "agent"
   ],
@@ -45,14 +47,22 @@
     "reflect-metadata": "^0.2.2",
     "toqr": "^0.1.1",
     "ws": "^8.18.3",
-    "@appduct/shared": "0.14.0"
+    "@appduct/shared": "0.15.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "~19.1.17",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.25.12",
     "eslint": "^10",
-    "typescript": "~5.9.2"
+    "playwright-core": "1.56.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "typescript": "~5.9.2",
+    "vite": "^8.1.4",
+    "webpack": "^5.111.1",
+    "@appduct/web": "0.15.1",
+    "@appduct/react-native": "0.15.1"
   },
   "files": [
     "bin.js",
@@ -62,7 +72,7 @@
     "build": "tsc -p tsconfig.build.json && node scripts/bundle.mjs",
     "clean": "rm -rf dist",
     "lint": "eslint src",
-    "test": "vitest run --config ../../vitest.config.ts src/__tests__",
+    "test": "vitest run src/__tests__",
     "typecheck": "tsc -p tsconfig.json"
   }
 }