appduct 0.14.0 → 0.15.1

package/dist/client/index.js

@@ -1,32 +1,71 @@
-// src/client/connect.ts
-import { RPC_METHODS as RPC_METHODS4 } from "@appduct/shared";
-
-// src/daemon/state-dir.ts
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { mkdir, chmod } from "node:fs/promises";
-var resolveStateDir = (override) => {
-  return override ?? process.env.APPDUCT_STATE_DIR ?? join(homedir(), ".appduct");
-};
-var getStateDirPaths = (stateDir) => {
-  return {
-    root: stateDir,
-    socketPath: join(stateDir, "daemon.sock"),
-    pidFilePath: join(stateDir, "daemon.pid"),
-    logFilePath: join(stateDir, "daemon.log"),
-    eventsLogPath: join(stateDir, "events.log"),
-    keyPath: join(stateDir, "key.pem"),
-    configPath: join(stateDir, "config.json"),
-    auditDir: join(stateDir, "audit"),
-    spawnLockPath: join(stateDir, "daemon.spawn.lock")
+// src/devtools-relay/relay.ts
+import { decodeBootstrap } from "@appduct/shared";
+var linkPayload = (link2) => {
+  const payload = new URLSearchParams(new URL(link2.url).hash.slice(1)).get("appduct");
+  if (payload === null) throw new Error('The link has no #appduct= payload: pass the result of link({ target: "web", url }).');
+  return payload;
+};
+var parseLink = (link2) => {
+  const bootstrap = decodeBootstrap(linkPayload(link2));
+  if (!bootstrap) throw new Error("The link's #appduct= payload is not a valid Appduct link.");
+  return bootstrap;
+};
+var GOING_AWAY = 1001;
+var relayPage = (page, link2, openDaemonSocket) => {
+  const bootstrap = parseLink(link2);
+  const host = bootstrap.address.includes(":") ? `[${bootstrap.address}]` : bootstrap.address;
+  const url = `ws://${host}:${bootstrap.port}`;
+  let current;
+  const tellPage = (message) => {
+    page.evaluate(`window.__APPDUCT__.receive(${JSON.stringify(JSON.stringify(message))})`).catch(() => void 0);
+  };
+  const closeCurrent = (code, reason) => {
+    const socket = current;
+    current = void 0;
+    socket?.close(code, reason);
   };
+  page.onBindingCall((json) => {
+    const message = JSON.parse(json);
+    if (message.kind === "open") {
+      closeCurrent(GOING_AWAY, "superseded");
+      const id = message.id;
+      const socket = openDaemonSocket(url, {
+        open: () => current === socket && tellPage({ kind: "open", id }),
+        message: (text) => current === socket && tellPage({ kind: "message", id, text }),
+        close: (code, reason) => {
+          if (current !== socket) return;
+          current = void 0;
+          tellPage({ kind: "close", id, code, reason });
+        }
+      });
+      current = socket;
+    } else if (message.kind === "send") {
+      current?.send(message.text ?? "");
+    } else if (message.kind === "close") {
+      closeCurrent(message.code ?? 1e3, message.reason ?? "");
+    }
+  });
+  page.onContextReset(() => closeCurrent(GOING_AWAY, "page_gone"));
 };
-var ensureStateDir = async (stateDir) => {
-  const paths = getStateDirPaths(stateDir);
-  await mkdir(paths.auditDir, { recursive: true });
-  await chmod(paths.root, 448);
-  await chmod(paths.auditDir, 448);
-  return paths;
+
+// src/devtools-relay/node-devtools-browser.ts
+import WebSocket from "ws";
+
+// src/devtools-relay/node-daemon-socket.ts
+import WebSocket2 from "ws";
+var openNodeDaemonSocket = (url, events) => {
+  const socket = new WebSocket2(url);
+  socket.on("open", () => events.open());
+  socket.on("message", (data, isBinary) => {
+    if (isBinary) {
+      socket.close(4008, "binary_frame_not_supported");
+      return;
+    }
+    events.message(data.toString());
+  });
+  socket.on("error", () => void 0);
+  socket.on("close", (code, reason) => events.close(code, reason.toString()));
+  return { send: (text) => socket.send(text), close: (code, reason) => socket.close(code, reason) };
 };
 
 // src/rpc/client.ts
@@ -52,6 +91,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -112,6 +152,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -182,6 +223,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.");
@@ -267,6 +314,34 @@ var isSocketConnectable = (socketPath) => {
   });
 };
 
+// src/daemon/state-dir.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, chmod } from "node:fs/promises";
+var resolveStateDir = (override) => {
+  return override ?? process.env.APPDUCT_STATE_DIR ?? join(homedir(), ".appduct");
+};
+var getStateDirPaths = (stateDir) => {
+  return {
+    root: stateDir,
+    socketPath: join(stateDir, "daemon.sock"),
+    pidFilePath: join(stateDir, "daemon.pid"),
+    logFilePath: join(stateDir, "daemon.log"),
+    eventsLogPath: join(stateDir, "events.log"),
+    keyPath: join(stateDir, "key.pem"),
+    configPath: join(stateDir, "config.json"),
+    auditDir: join(stateDir, "audit"),
+    spawnLockPath: join(stateDir, "daemon.spawn.lock")
+  };
+};
+var ensureStateDir = async (stateDir) => {
+  const paths = getStateDirPaths(stateDir);
+  await mkdir(paths.auditDir, { recursive: true });
+  await chmod(paths.root, 448);
+  await chmod(paths.auditDir, 448);
+  return paths;
+};
+
 // src/daemon/log-rotation.ts
 var STATE_FILE_MODE = 384;
 var daemonLogBackupPath = (logFilePath) => `${logFilePath}.1`;
@@ -1025,6 +1100,119 @@ var openDaemonStream = async (options) => {
   };
 };
 
+// src/errors.ts
+var AppductCliError = class extends Error {
+  type;
+  details;
+  constructor(type, message, details) {
+    super(message);
+    this.name = "AppductCliError";
+    this.type = type;
+    this.details = details;
+  }
+};
+var usageError = (message, details) => {
+  return new AppductCliError("usage_error", message, details);
+};
+var connectionError = (message, details) => {
+  return new AppductCliError("connection_error", message, details);
+};
+var isAppductCliError = (value) => {
+  return value instanceof AppductCliError;
+};
+
+// src/client/errors.ts
+var AppductError = class extends Error {
+  type;
+  details;
+  /** The JSON-RPC error code, when this wraps a `DaemonRpcError`. */
+  code;
+  constructor(type, message, details, code) {
+    super(message);
+    this.name = "AppductError";
+    this.type = type;
+    this.details = details;
+    this.code = code;
+  }
+};
+var toAppductError = (error) => {
+  if (error instanceof AppductError) {
+    return error;
+  }
+  const withCause = (result) => {
+    result.cause = error;
+    return result;
+  };
+  if (error instanceof DaemonRpcError) {
+    const type = error.data?.type ?? "client_error";
+    return withCause(new AppductError(type, error.message, error.data?.details, error.code));
+  }
+  if (isDaemonUnreachableError(error)) {
+    return withCause(
+      new AppductError(
+        "connection_error",
+        error instanceof Error ? error.message : "The Appduct daemon is unreachable."
+      )
+    );
+  }
+  if (isAppductCliError(error)) {
+    return withCause(new AppductError("client_error", error.message, error.details));
+  }
+  if (error instanceof Error) {
+    return withCause(new AppductError("client_error", error.message));
+  }
+  return new AppductError("client_error", "An unexpected error occurred.", error);
+};
+
+// src/client/attach-page.ts
+var BINDING = "__appductBinding";
+var ANNOUNCE_DOCUMENT = `if (window === window.top) window.${BINDING}(JSON.stringify({ kind: "context" }));`;
+var channels = /* @__PURE__ */ new WeakMap();
+var channelOf = async (page) => {
+  const existing = channels.get(page);
+  if (existing) {
+    existing.reset();
+    await page.evaluate(`window.__APPDUCT__?.receive(${JSON.stringify(JSON.stringify({ kind: "close", code: 1001, reason: "superseded" }))})`).catch(() => void 0);
+    return existing;
+  }
+  let bindingHandlers = [];
+  let resetHandlers = [];
+  const reset = () => resetHandlers.forEach((handler) => handler());
+  await page.exposeBinding(BINDING, (source, json) => {
+    if (source.frame !== page.mainFrame()) return;
+    if (JSON.parse(json).kind === "context") reset();
+    else bindingHandlers.forEach((handler) => handler(json));
+  });
+  await page.addInitScript(ANNOUNCE_DOCUMENT);
+  page.on("close", reset);
+  const channel = {
+    onBindingCall: (handler) => void bindingHandlers.push(handler),
+    onContextReset: (handler) => void resetHandlers.push(handler),
+    evaluate: (expression) => page.evaluate(expression),
+    reset: () => {
+      reset();
+      bindingHandlers = [];
+      resetHandlers = [];
+    }
+  };
+  channels.set(page, channel);
+  return channel;
+};
+var attachPage = async (page, options) => {
+  try {
+    parseLink(options.link);
+    const payload = linkPayload(options.link);
+    relayPage(await channelOf(page), options.link, openNodeDaemonSocket);
+    await page.waitForFunction("typeof window.__APPDUCT__?.connect === 'function'");
+    await page.evaluate(`window.__APPDUCT__.connect(${JSON.stringify(payload)}, { transport: "devtools" })`);
+  } catch (error) {
+    throw toAppductError(error);
+  }
+};
+
+// src/client/connect.ts
+import { RPC_METHODS as RPC_METHODS4 } from "@appduct/shared";
+
 // src/client/app-client.ts
 import {
   clampToolTimeoutMs,
@@ -1132,70 +1320,6 @@ var waitForAppEvent = async (stream, options) => {
   }
 };
 
-// src/errors.ts
-var AppductCliError = class extends Error {
-  type;
-  details;
-  constructor(type, message, details) {
-    super(message);
-    this.name = "AppductCliError";
-    this.type = type;
-    this.details = details;
-  }
-};
-var usageError = (message, details) => {
-  return new AppductCliError("usage_error", message, details);
-};
-var connectionError = (message, details) => {
-  return new AppductCliError("connection_error", message, details);
-};
-var isAppductCliError = (value) => {
-  return value instanceof AppductCliError;
-};
-
-// src/client/errors.ts
-var AppductError = class extends Error {
-  type;
-  details;
-  /** The JSON-RPC error code, when this wraps a `DaemonRpcError`. */
-  code;
-  constructor(type, message, details, code) {
-    super(message);
-    this.name = "AppductError";
-    this.type = type;
-    this.details = details;
-    this.code = code;
-  }
-};
-var toAppductError = (error) => {
-  if (error instanceof AppductError) {
-    return error;
-  }
-  const withCause = (result) => {
-    result.cause = error;
-    return result;
-  };
-  if (error instanceof DaemonRpcError) {
-    const type = error.data?.type ?? "client_error";
-    return withCause(new AppductError(type, error.message, error.data?.details, error.code));
-  }
-  if (isDaemonUnreachableError(error)) {
-    return withCause(
-      new AppductError(
-        "connection_error",
-        error instanceof Error ? error.message : "The Appduct daemon is unreachable."
-      )
-    );
-  }
-  if (isAppductCliError(error)) {
-    return withCause(new AppductError("client_error", error.message, error.details));
-  }
-  if (error instanceof Error) {
-    return withCause(new AppductError("client_error", error.message));
-  }
-  return new AppductError("client_error", "An unexpected error occurred.", error);
-};
-
 // src/client/app-client.ts
 var DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS = 3e4;
 var CALL_TRANSPORT_TIMEOUT_SLACK_MS = 5e3;
@@ -1965,31 +2089,42 @@ var probeIosProjectYml = async (root) => {
   };
 };
 var PROBES = [
-  probeAndroidGradle,
-  probeAndroidManifest,
-  probeIosInfoPlist,
-  probeIosProjectYml
+  ["android", probeAndroidGradle],
+  ["android", probeAndroidManifest],
+  ["ios", probeIosInfoPlist],
+  ["ios", probeIosProjectYml]
 ];
+var isFlutterProject = async (root) => {
+  return (await readCappedText(join4(root, "pubspec.yaml"))).ok;
+};
 var discoverNativeScheme = async (root) => {
   const tried = [];
   const results = [];
-  for (const probe of PROBES) {
-    const outcome = await probe(root);
-    tried.push(...outcome.tried);
-    if (outcome.result !== void 0) {
-      results.push(outcome.result);
+  const flutter = await isFlutterProject(root);
+  const androidRoot = flutter ? join4(root, "android") : root;
+  const iosRoots = flutter ? [join4(root, "ios"), join4(root, "macos")] : [root];
+  for (const [platform, probe] of PROBES) {
+    let roots = [root];
+    if (platform === "android") {
+      roots = [androidRoot];
+    } else if (probe === probeIosInfoPlist) {
+      roots = iosRoots;
+    }
+    for (const probeRoot of roots) {
+      const outcome = await probe(probeRoot);
+      tried.push(...outcome.tried);
+      if (outcome.result !== void 0) {
+        results.push(outcome.result);
+      }
     }
   }
-  if (results.length === 0) {
-    return { tried };
-  }
   const distinctSchemes = new Set(results.map((entry) => entry.scheme));
   if (distinctSchemes.size > 1) {
     throw usageError(
       "Conflicting deep-link schemes found in this project: " + results.map((entry) => `${entry.origin} says ${JSON.stringify(entry.scheme)}`).join(", but ") + ". Appduct will not guess which one is right \u2014 pass --scheme <scheme> to pick one."
     );
   }
-  return { result: results[0], tried };
+  return { results, tried };
 };
 
 // src/scheme.ts
@@ -2052,19 +2187,21 @@ var discoverStaticProjectScheme = async (cwd) => {
   const tried = [`${appJsonPath} ("expo.scheme")`];
   const appJsonScheme = await discoverExpoScheme(cwd);
   if (appJsonScheme !== void 0) {
-    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, tried };
+    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, nativeResults: [], tried };
   }
   const native = await discoverNativeScheme(resolve(cwd));
   tried.push(...native.tried);
-  if (native.result !== void 0) {
+  const [first] = native.results;
+  if (first !== void 0) {
     return {
-      scheme: native.result.scheme,
-      source: native.result.source,
-      origin: native.result.origin,
+      scheme: first.scheme,
+      source: first.source,
+      origin: first.origin,
+      nativeResults: native.results,
       tried
     };
   }
-  return { tried };
+  return { nativeResults: [], tried };
 };
 var globalConfigDirs = (options = {}) => {
   const excluded = /* @__PURE__ */ new Set([join5(resolve(options.homeDir ?? homedir2()), PROJECT_CONFIG_DIR)]);
@@ -2248,6 +2385,34 @@ ${tried.map((location, index) => `  ${index + 1}. ${location}`).join("\n")}
 // src/link.ts
 var OPEN_TARGET_ADDRESS_OVERRIDE = "127.0.0.1";
 var composeDeepLink = (scheme, result) => `${scheme}:///?appduct=${result.deepLinkPayload}&pin=${encodeURIComponent(result.pin)}`;
+var assertWebPageUrl = (pageUrl) => {
+  let protocol;
+  try {
+    protocol = new URL(pageUrl).protocol;
+  } catch {
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    throw usageError(`"url" must be an http(s) URL (got "${pageUrl}").`);
+  }
+};
+var composeWebLink = (pageUrl, result) => {
+  const payload = result.deepLinkPayload;
+  return {
+    sessionId: result.sessionId,
+    url: `${pageUrl.split("#")[0]}#appduct=${payload}`,
+    script: `window.__APPDUCT__.connect("${payload}")`,
+    expiresAt: result.expiresAt
+  };
+};
+var mintWebLink = async (options) => {
+  assertWebPageUrl(options.url);
+  const result = await callDaemon(
+    RPC_METHODS5.linkCreate,
+    { ttlSeconds: options.ttlSeconds, transport: "web" },
+    { stateDir: options.stateDir, spawn: options.spawn, autoSpawn: options.autoSpawn }
+  );
+  return composeWebLink(options.url, result);
+};
 var mintLink = async (options) => {
   if (options.target !== void 0 && !isOpenTarget(options.target)) {
     throw usageError(
@@ -2334,8 +2499,17 @@ var mintLink = async (options) => {
 
 // src/client/bootstrap.ts
 var DEFAULT_WAIT_FOR_SESSION_TIMEOUT_MS = 12e4;
-var link = async (options = {}) => {
+async function link(options = {}) {
   try {
+    if (options.target === "web") {
+      return await mintWebLink({
+        stateDir: resolveStateDir(options.stateDir),
+        spawn: options.spawn,
+        autoSpawn: options.autoSpawn,
+        ttlSeconds: options.ttlSeconds,
+        url: options.url
+      });
+    }
     return await mintLink({
       stateDir: resolveStateDir(options.stateDir),
       spawn: options.spawn,
@@ -2354,7 +2528,7 @@ var link = async (options = {}) => {
   } catch (error) {
     throw toAppductError(error);
   }
-};
+}
 var waitForSession = async (sessionId, options = {}) => {
   const stateDir = resolveStateDir(options.stateDir);
   const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_FOR_SESSION_TIMEOUT_MS;
@@ -2427,6 +2601,7 @@ var waitForSession = async (sessionId, options = {}) => {
 };
 export {
   AppductError,
+  attachPage,
   connect3 as connect,
   link,
   waitForSession

package/dist/commands/doctor.d.ts

@@ -1,8 +1,7 @@
 /**
- * `appduct doctor <artifact>` (docs/tasks/08-appduct-doctor.md): the release-gate replacement
- * for the runtime `debuggable` check removed elsewhere in opt-in hardening — see
- * `artifact-inspect.ts`'s doc comment for the detection strategy and why it never collapses a
- * missing-tool or unreadable-artifact case into "absent".
+ * `appduct doctor <artifact>`: the release-gate replacement for the runtime `debuggable` check
+ * removed elsewhere in opt-in hardening — see `artifact-inspect.ts`'s doc comment for the detection
+ * strategy and why it never collapses a missing-tool or unreadable-artifact case into "absent".
  *
  * This handler owns only the CLI-facing concerns: option validation (mutually exclusive
  * `--assert-present`/`--assert-absent`) and turning a failed assertion into a distinct

package/dist/commands/init.d.ts

@@ -6,8 +6,9 @@
  * #63, the installed app's id per platform (`appId.ios`/`appId.android` — needed to deliver a
  * link with `--open ios-device`/`--open android` without an "Open with" chooser silently eating
  * it), and returns the two things that are not discoverable from the filesystem: the MCP server
- * entry to paste into an agent's config, and the `import "@appduct/react-native/auto"` reminder
- * the app needs.
+ * entry to paste into an agent's config, and the wiring step this project still needs — the
+ * `import "@appduct/react-native/auto"` reminder for a React Native app, the equivalent native
+ * wiring for a plain iOS or Android one (issue #153).
  *
  * Unlike `scheme`, an app id has no discovery tier: `--ios-app-id`/`--android-app-id` (or an
  * already-recorded value) is the whole story, and the two are independent flags rather than one
@@ -41,6 +42,11 @@
  * step via {@link discoverStaticProjectScheme} specifically so the two can never disagree about
  * what "discovery" means. `InitCommandData.source` names every origin this command itself can
  * produce.
+ *
+ * One read does go above the root, and it is not an exception to the rule above:
+ * {@link declaresReactNative} walks up a bounded number of directories for a `package.json`, which
+ * chooses which wiring *hint* to print and writes nothing. Nothing that lands in the file `init`
+ * writes is inherited from a parent directory.
  */
 import type { CliResult, InitCommandData } from "../cli/result-types.js";
 export type InitCommandOptions = {

package/dist/commands/link.d.ts

@@ -3,7 +3,7 @@
  * CLI-specific error wording) around the shared `mintLink` core (`../link.ts`), which both this
  * command and `appduct/client`'s `link()` use so the deep-link shape can't drift between them.
  */
-import type { CliResult, LinkCommandData } from "../cli/result-types.js";
+import type { CliResult, LinkCommandData, WebAttachCommandData, WebLinkCommandData } from "../cli/result-types.js";
 import { type ExecFn } from "../cli/open-target.js";
 import type { SpawnFn } from "../rpc/client.js";
 export type LinkCommandOptions = {
@@ -13,6 +13,12 @@ export type LinkCommandOptions = {
     device?: string;
     appId?: string;
     relaunch?: boolean;
+    /** The page to open, with `--open web`. */
+    url?: string;
+    /** With `--open web`: the debugging endpoint of a Chromium whose tab the daemon attaches. */
+    browserUrl?: string;
+    /** With `--browser-url`: the CDP target id of the tab to attach. */
+    targetId?: string;
 };
 export type LinkCommandContext = {
     stateDir: string;
@@ -27,3 +33,6 @@ export type LinkCommandContext = {
     schemeEnv?: NodeJS.ProcessEnv;
 };
 export declare const handleLinkCommand: (options: LinkCommandOptions, context: LinkCommandContext) => Promise<CliResult<LinkCommandData>>;
+/** `appduct sessions link --open web <url>`: no device and no scheme, just the page URL carrying
+ * the link and the script that connects an already-open page. */
+export declare const handleWebLinkCommand: (options: LinkCommandOptions, context: LinkCommandContext) => Promise<CliResult<WebLinkCommandData | WebAttachCommandData>>;

package/dist/daemon/calls.d.ts

@@ -67,7 +67,7 @@ export type CallsManager = {
     cancel: (sessionId: string, callId: string, reason: string) => boolean;
     /** Rejects every pending call for a session immediately (suspend/revoke/expiry transitions). */
     rejectSession: (sessionId: string, errorType: "session_suspended" | "unknown_session", options?: {
-        backgrounded?: boolean;
+        message?: (alias: string) => string;
     }) => void;
     /** Rejects and clears every pending call across every session (daemon shutdown). */
     disposeAll: () => void;

package/dist/daemon/config.d.ts

@@ -47,6 +47,12 @@ export type AppductConfig = {
      * Default 10 MiB. */
     eventsLogMaxBytes: number;
     policy: AppductPolicyConfig;
+    /**
+     * Origins besides localhost, `127.0.0.1` and `[::1]` (any port) that may connect to the web
+     * listener, each written as a browser sends it, e.g. `"https://app.example.test"`. Compared as
+     * exact strings. Default: none.
+     */
+    webOrigins: string[];
     /**
      * When the CLI/MCP client finds the running daemon on a different Appduct version, restart it
      * even if that drops live sessions (issue #30, ARCHITECTURE.md §4's "Version drift"). Default

package/dist/daemon/daemon.d.ts

@@ -7,10 +7,11 @@
  * recorded to the audit log inline in the `tools.call` handler below.
  */
 import type { Clock } from "../cli/types.js";
+import { type ConnectDevtoolsBrowser } from "../devtools-relay/index.js";
 import { detectAdvertisedAddress } from "./address.js";
 import { type AppductConfig, type ConfigWarnFn } from "./config.js";
 import { type EventBus } from "./event-bus.js";
-import { type DaemonListener } from "./listener.js";
+import { type DaemonListener, type WebListener } from "./listener.js";
 import { type RpcServer } from "./rpc-server.js";
 import { type StateDirPaths } from "./state-dir.js";
 import { type TimerFns } from "./timers.js";
@@ -27,6 +28,8 @@ export type DaemonOptions = {
      * `config.advertisedIp`. Overridable so tests can simulate a network change between two
      * `link.create` calls without mocking `os.networkInterfaces()` process-wide. */
     detectAddress?: () => ReturnType<typeof detectAdvertisedAddress>;
+    /** Reaches a debugging-port browser for `web.attach`; defaults to raw CDP over `ws`. */
+    connectDevtoolsBrowser?: ConnectDevtoolsBrowser;
 };
 export type RunningDaemon = {
     paths: StateDirPaths;
@@ -34,6 +37,8 @@ export type RunningDaemon = {
     startedAt: Date;
     server: RpcServer;
     listener: DaemonListener;
+    /** The plain-HTTP listener web pages connect to. */
+    webListener: WebListener;
     /** The host certificate the listener serves, so an in-process client can trust it. */
     tls: TlsManager;
     eventBus: EventBus;

package/dist/daemon/links.d.ts

@@ -5,7 +5,7 @@
  * Pending links are cheap and re-issuable — they are never persisted and never appear in
  * `sessions.list`/`sessions.describe` (only claimed sessions do; see sessions.ts).
  */
-import { type AgentEndpoint } from "@appduct/shared";
+import { type AgentEndpoint, type LinkTransport } from "@appduct/shared";
 import type { Clock } from "../cli/types.js";
 import type { EventBus } from "./event-bus.js";
 import type { TimerFns } from "./timers.js";
@@ -15,6 +15,8 @@ export type PendingLink = {
     token: Buffer;
     createdAt: Date;
     expiresAt: Date;
+    /** The listener this link can be claimed on, and only that one. */
+    transport: LinkTransport;
 };
 export type CreatedLink = {
     link: PendingLink;
@@ -22,8 +24,9 @@ export type CreatedLink = {
     endpoint: AgentEndpoint;
 };
 export type PendingLinkRegistryOptions = {
-    /** Resolves the current advertised endpoint at mint time (address may be re-detected). */
-    getEndpoint: () => AgentEndpoint;
+    /** Resolves the current advertised endpoint of a transport at mint time (the native address may
+     * be re-detected). */
+    getEndpoint: (transport: LinkTransport) => AgentEndpoint;
     clock: Clock;
     timers: TimerFns;
     eventBus: EventBus;
@@ -31,8 +34,9 @@ export type PendingLinkRegistryOptions = {
 export type PendingLinkRegistry = {
     /** `addressOverride` forces the endpoint address encoded into this one link's bootstrap payload
      * (the emulator/simulator fast path: `127.0.0.1`), leaving the detected endpoint used by
-     * every other link unaffected. */
-    create: (ttlSeconds: number, addressOverride?: string) => CreatedLink;
+     * every other link unaffected. It does not apply to a `web` link, whose address is always the
+     * loopback one the web listener binds. */
+    create: (ttlSeconds: number, addressOverride?: string, transport?: LinkTransport) => CreatedLink;
     /** Looks up a pending link without consuming it (used to distinguish "unknown" from "already claimed"). */
     get: (sessionId: string) => PendingLink | undefined;
     /** Removes and returns the link (successful claim consumes its single use). */