@farmslot/adapter-web 0.17.7 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.18.0 - 2026-11-05
+
+- Run ordinary websites in an owned extension-free browser with shared CDP actions, screenshots and whole-run recording. Existing extension launches retain their lifecycle.
+
 ## 0.17.7 - 2026-11-04
 
 - Check host-resolver blocking in an owned blank document so strict application CSP needs no harness-only source. Keep application HTTP and WebSocket blocking checks unchanged.

package/README.md

@@ -108,6 +108,12 @@ const binding = createWalletRequestBinding({
 });
 ```
 
+## Plain websites
+
+`@farmslot/adapter-web/plain-web` exports `createPlainWebAdapter({ manifestPath, url, serverLabel })`. The project supplies its action catalog and a URL function using its selected ports. The runtime owns an isolated browser and reuses shared CDP actions, screenshots and whole-run recording. The project owns its application server.
+
+Browser stop is scoped to the selected checkout's profile and retains the application server. This path needs no extension, signer or wallet policy and makes no assumptions about the application framework or page selectors.
+
 ## Web-dapp adapter
 
 `@farmslot/adapter-web/web-dapp` (ESM) is the lifecycle of a web app under test whose dev server the slot owns. `createWebDappAdapter({ id, signerModule, cli, hooks })` returns an `@farmslot/adapter-sdk` `ProjectRuntime`: launch, stop, runtime status, doctor checks, logs and the wallet request-log findings. It runs one slot browser per slot, and a wallet host attached to it over CDP that records the wallet requests (and, with `signer=injected`, answers them with the strict wallet from `dapp`).

package/dist/launch-browser.d.cts

@@ -3,9 +3,9 @@ export type LaunchBrowserOptions = {
     chromeBin: string;
     profile: string;
     /**
-     * Unpacked extension to load.
+     * Unpacked extension to load; omitted for a plain web page.
      */
-    extensionDir: string;
+    extensionDir?: string | undefined;
     /**
      * Holds browser-resolution.json and the runtime identity.
      */
@@ -72,7 +72,7 @@ export type LaunchBrowserOptions = {
  * @property {number} cdpPort
  * @property {string} chromeBin
  * @property {string} profile
- * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} [extensionDir] Unpacked extension to load; omitted for a plain web page.
  * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
  * @property {string} chromeLog
  * @property {string} chromePid

package/dist/plain-web.d.mts

@@ -0,0 +1,17 @@
+/** Runtime files and the browser profile always belong to the selected checkout. */
+export function plainWebRuntimeDir(target: any): string;
+/**
+ * Use existing browser ownership, CDP actions and whole-run recording for a plain website.
+ * @param {PlainWebAdapterConfig} config
+ * @returns {import('@farmslot/adapter-sdk').ProjectRuntime}
+ */
+export function createPlainWebAdapter(config: PlainWebAdapterConfig): import("@farmslot/adapter-sdk").ProjectRuntime;
+/** Releases only the selected checkout's owned profile. The application server is retained. */
+export function stopPlainWebBrowser(target: any): {
+    stopped: boolean;
+};
+export type PlainWebAdapterConfig = {
+    manifestPath: string;
+    url: (target: string) => string;
+    serverLabel?: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.17.7",
+  "version": "0.18.0",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {
@@ -68,6 +68,10 @@
     "./web-dapp": {
       "types": "./dist/web-dapp/index.d.mts",
       "default": "./src/web-dapp/index.mjs"
+    },
+    "./plain-web": {
+      "types": "./dist/plain-web.d.mts",
+      "default": "./src/plain-web.mjs"
     }
   },
   "scripts": {

package/src/launch-browser.cjs

@@ -67,7 +67,7 @@ const BROWSER_RESOLVER_CLI = require.resolve('./browser-resolver.cjs');
  * @property {number} cdpPort
  * @property {string} chromeBin
  * @property {string} profile
- * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} [extensionDir] Unpacked extension to load; omitted for a plain web page.
  * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
  * @property {string} chromeLog
  * @property {string} chromePid
@@ -114,7 +114,6 @@ function normalizeOptions(options) {
   const flags = {
     chromeBin: 'chrome-bin',
     profile: 'profile',
-    extensionDir: 'extension-dir',
     runtimeDir: 'runtime-dir',
     chromeLog: 'chrome-log',
     chromePid: 'chrome-pid',
@@ -122,6 +121,10 @@ function normalizeOptions(options) {
   for (const [key, flag] of Object.entries(flags)) {
     if (!opts[key]) throw new Error(`Missing --${flag}`);
   }
+  if (!opts.extensionDir && !opts.stopOnly) {
+    if (!opts.startUrl || !/^https?:$/u.test(new URL(opts.startUrl).protocol))
+      throw new Error('Plain web launch requires an explicit HTTP(S) --start-url');
+  }
   opts.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
   opts.progress = opts.progress ?? (() => {});
   return opts;
@@ -135,7 +138,7 @@ function runLaunch(opts, acquireLock) {
   if (!opts.stopOnly) {
     if (!fs.existsSync(opts.chromeBin))
       throw new Error(`Chrome binary not found: ${opts.chromeBin}`);
-    if (!fs.existsSync(path.join(extensionDir, 'manifest.json'))) {
+    if (extensionDir && !fs.existsSync(path.join(extensionDir, 'manifest.json'))) {
       throw new Error(
         `Extension dist manifest not found: ${path.join(extensionDir, 'manifest.json')}`,
       );
@@ -189,7 +192,7 @@ function runLaunch(opts, acquireLock) {
   // run's Chrome would hold the lock and the write fails.
   if (opts.stopOnly) return { stopped: true };
   try {
-    removeExtensionWorkerRegistrations(profile);
+    if (extensionDir) removeExtensionWorkerRegistrations(profile);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(
@@ -221,7 +224,7 @@ function runLaunch(opts, acquireLock) {
   const initialUrl =
     opts.startUrl || extensionPageUrl(extensionDir, opts.homePage) || 'chrome://extensions/';
   const browser = launchBrowserResolution(opts.browserResolution, opts.chromeBin);
-  const loadsOverCdp = browser.extensionLoading === CDP_LOAD_UNPACKED;
+  const loadsOverCdp = Boolean(extensionDir) && browser.extensionLoading === CDP_LOAD_UNPACKED;
   let cdpLoad = null;
   let owner = null;
   const runtimeNonce = createRuntimeIdentityNonce();
@@ -238,10 +241,14 @@ function runLaunch(opts, acquireLock) {
     ...isolatedProfileArgs(),
     '--disable-default-apps',
     '--disable-popup-blocking',
-    '--disable-extensions-file-access-check',
-    '--disable-extensions-content-verification',
-    '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
-    ...extensionLaunchArgs(extensionDir, browser.extensionLoading),
+    ...(extensionDir
+      ? [
+          '--disable-extensions-file-access-check',
+          '--disable-extensions-content-verification',
+          '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+          ...extensionLaunchArgs(extensionDir, browser.extensionLoading),
+        ]
+      : []),
   ]);
   // Initial tab: the caller's URL when provided, else the extension home. The
   // extension home avoids leaving disposable chrome://newtab/ or extensions
@@ -333,7 +340,7 @@ function runLaunch(opts, acquireLock) {
         cdpLoad = loadExtensionOverCdp(opts, browserPid, initialUrl, clearLaunchMarkers);
       else if (application) openBackgroundWindow(opts, browserPid, initialUrl, clearLaunchMarkers);
       owner = cdpLoad?.owner ?? ownerIdentity(cdpPort, profile, browserPid, log);
-      for (const problem of pruneExtraHomeTabs(cdpPort, extensionDir, opts)) {
+      for (const problem of extensionDir ? pruneExtraHomeTabs(cdpPort, extensionDir, opts) : []) {
         log(`[launch] home-tab pruning: ${problem}`);
       }
     } finally {
@@ -658,7 +665,8 @@ function processIsOwnedBrowser(pid, profile, extensionDir, extensionOwnerRoot) {
   const command = processCommand(pid);
   if (!command) return false;
   if (command.includes(`--user-data-dir=${profile}`)) return true;
-  const ownerRoot = extensionOwnerRoot ? extensionOwnerRoot(path.resolve(extensionDir)) : null;
+  const ownerRoot =
+    extensionDir && extensionOwnerRoot ? extensionOwnerRoot(path.resolve(extensionDir)) : null;
   return Boolean(ownerRoot && command.includes(`--load-extension=${ownerRoot}`));
 }
 

package/src/plain-web.mjs

@@ -0,0 +1,219 @@
+// A regular website in a slot-owned browser. The project owns its application server.
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { CdpWebPage, listCdpTargets } from '@farmslot/recipe-runner/runtime/cdp';
+
+import { assertSameOwner, cdpOwner } from './browser-cdp.cjs';
+import { resolveBrowser } from './browser-resolver.cjs';
+import { removeRuntimeIdentity } from './chrome-args.cjs';
+import { launchBrowser } from './launch-browser.cjs';
+import { stopProfileProcessesSync } from './validation-process-ownership.cjs';
+
+/** @typedef {{
+ * manifestPath: string,
+ * url: (target: string) => string,
+ * serverLabel?: string
+ * }} PlainWebAdapterConfig
+ */
+
+function port(env = process.env) {
+  const value = Number(env.RECIPE_CDP_PORT ?? env.CDP_PORT);
+  if (!Number.isInteger(value) || value < 1 || value > 65535)
+    throw new Error('The plain web runtime requires the assigned --cdp-port.');
+  return value;
+}
+
+/** Runtime files and the browser profile always belong to the selected checkout. */
+export function plainWebRuntimeDir(target) {
+  return path.join(fs.realpathSync(target), '.agent', 'web');
+}
+
+function browserOptions(target, env = process.env) {
+  const runtimeDir = plainWebRuntimeDir(target);
+  return {
+    cdpPort: port(env),
+    runtimeDir,
+    profile: path.join(runtimeDir, 'profile'),
+    chromeLog: path.join(runtimeDir, 'browser.log'),
+    chromePid: path.join(runtimeDir, 'browser.pid'),
+  };
+}
+
+function owned(target, env = process.env) {
+  const options = browserOptions(target, env);
+  return cdpOwner(options.cdpPort, options.profile);
+}
+
+/**
+ * Use existing browser ownership, CDP actions and whole-run recording for a plain website.
+ * @param {PlainWebAdapterConfig} config
+ * @returns {import('@farmslot/adapter-sdk').ProjectRuntime}
+ */
+export function createPlainWebAdapter(config) {
+  const hint = 'Prepare the selected slot, then launch its plain web browser.';
+  async function page(target, env = process.env) {
+    const owner = owned(target, env);
+    const file = path.join(plainWebRuntimeDir(target), 'page.json');
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const selected = (await listCdpTargets('127.0.0.1', port(env))).find(
+      (entry) => entry.id === state.pageId && entry.type === 'page',
+    );
+    assertSameOwner(owner);
+    if (!selected) throw new Error(`The owned application page is unavailable. ${hint}`);
+    return selected;
+  }
+  /** @type {import('@farmslot/adapter-sdk').ProjectRuntime} */
+  const runtime = {
+    id: 'web',
+    sdkVersion: 1,
+    headless: false,
+    targets: ['web', 'cli'],
+    resolveSlotPorts() {},
+    async runtimeStatus(target) {
+      try {
+        await page(target);
+        const response = await fetch(config.url(target), { signal: AbortSignal.timeout(5000) });
+        await response.body?.cancel();
+        if (!response.ok) throw new Error(`Application returned HTTP ${response.status}.`);
+        return {
+          decision: 'ready',
+          reasons: [],
+          devServer: { label: config.serverLabel ?? 'website', status: 'up' },
+        };
+      } catch (error) {
+        return {
+          decision: 'blocked',
+          reasons: [error instanceof Error ? error.message : String(error)],
+          nextAction: hint,
+        };
+      }
+    },
+    devServer: {
+      label: 'browser',
+      describe: () => 'The owned website browser; the application server belongs to the project',
+      stop(target) {
+        stopPlainWebBrowser(target);
+        return {
+          kind: 'stopped',
+          status: 0,
+          summary: 'Website browser stopped; application server retained.',
+        };
+      },
+    },
+    logSources: (target) => [
+      { label: 'Browser', path: path.join(plainWebRuntimeDir(target), 'browser.log') },
+    ],
+    appLogSource: () => null,
+    hints: { launch: hint, relaunch: hint, runtimeProbeRecovery: () => hint },
+    harness: {
+      kind: 'built-in',
+      verify(target) {
+        return {
+          inProcess: async () => async (_args, io) => {
+            const status = await runtime.runtimeStatus(target);
+            if (status.decision !== 'ready') {
+              io.err(status.reasons.join('; '));
+              return 1;
+            }
+            io.out('ready');
+            return 0;
+          },
+        };
+      },
+    },
+    runtimeContext: { forbiddenFields: [] },
+    readiness: { captureProviders: ['cdp'], readyIndicator: () => 'ready' },
+    recording: {
+      async target(context) {
+        const owner = owned(context.projectRoot, context.env);
+        await page(context.projectRoot, context.env);
+        assertSameOwner(owner);
+        return { kind: 'pid', pid: owner.pid };
+      },
+    },
+    async launch({ target, jsonOutput }) {
+      const url = config.url(target);
+      const parsed = new URL(url);
+      if (!['http:', 'https:'].includes(parsed.protocol))
+        throw new Error('Expected an HTTP(S) application URL.');
+      const options = browserOptions(target);
+      const resolution = await resolveBrowser({
+        env: {
+          ...process.env,
+          RECIPE_HARNESS_BROWSER: process.env.RECIPE_HARNESS_BROWSER ?? 'chrome',
+        },
+        cft: () => ({
+          error:
+            'Select installed Chrome or set RECIPE_HARNESS_CHROME_BIN to an installed Chromium executable.',
+        }),
+        cachePath: path.join(options.runtimeDir, 'browser-probe.json'),
+        launchMethod: process.platform === 'darwin' ? 'launch-services' : 'spawn',
+        display: 'headful',
+      });
+      launchBrowser({ ...options, chromeBin: resolution.bin, startUrl: url });
+      try {
+        const owner = owned(target);
+        const deadline = Date.now() + 15_000;
+        let candidates = [];
+        do {
+          candidates = (await listCdpTargets('127.0.0.1', port())).filter(
+            (entry) => entry.type === 'page' && entry.url.startsWith(`${parsed.origin}/`),
+          );
+          if (candidates.length) break;
+          await delay(100);
+        } while (Date.now() < deadline);
+        if (candidates.length !== 1)
+          throw new Error('Expected one application page in the owned browser.');
+        assertSameOwner(owner);
+        fs.writeFileSync(
+          path.join(options.runtimeDir, 'page.json'),
+          JSON.stringify({ pageId: candidates[0].id }),
+          { mode: 0o600 },
+        );
+        const status = await runtime.runtimeStatus(target);
+        if (status.decision !== 'ready') throw new Error(status.reasons.join('; '));
+      } catch (error) {
+        stopPlainWebBrowser(target);
+        throw error;
+      }
+      if (jsonOutput)
+        console.log(
+          JSON.stringify({
+            schemaVersion: 1,
+            command: 'launch',
+            status: 'pass',
+            adapter: 'web',
+            target,
+            url,
+            cdpPort: options.cdpPort,
+          }),
+        );
+      return 0;
+    },
+    actions: {
+      manifestPath: () => config.manifestPath,
+      semantic: [],
+      cdpTarget: { transport: 'cdp', probePath: '/json/version' },
+      ui: ({ createCdpWebUiTransport }) => ({
+        base: createCdpWebUiTransport({
+          getPage: async ({ context }) =>
+            CdpWebPage.connectToTarget(await page(context.projectRoot, context.env)),
+        }),
+      }),
+    },
+  };
+  return runtime;
+}
+
+/** Releases only the selected checkout's owned profile. The application server is retained. */
+export function stopPlainWebBrowser(target) {
+  const runtimeDir = plainWebRuntimeDir(target);
+  // Stop also works without active port options, including a repeated closeout.
+  stopProfileProcessesSync(path.join(runtimeDir, 'profile'));
+  removeRuntimeIdentity(runtimeDir);
+  fs.rmSync(path.join(runtimeDir, 'browser.pid'), { force: true });
+  fs.rmSync(path.join(runtimeDir, 'page.json'), { force: true });
+  return { stopped: true };
+}