dsh-web-fetch-playwright 0.2.0 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,29 +1,43 @@
1
1
  /**
2
2
  * The CDP backend's shared connection: one `connectOverCDP` session reused by
3
- * every fetch, each fetch leasing an isolated context (a tab in the remote
4
- * browser) that it closes when done. The connection itself outlives fetches —
5
- * reconnecting per fetch would spend 100–500ms per call and open one socket
6
- * per concurrent tab for no benefit.
3
+ * every fetch, each fetch leasing a page (a tab in the remote browser) that
4
+ * it closes when done — in an isolated throwaway context (`isolated` mode),
5
+ * or in the remote browser's default context (`profile` mode, whose cookies
6
+ * and localStorage are the real profile's, so its persistent logins apply;
7
+ * that context is never closed, only the tab is). The connection itself
8
+ * outlives fetches — reconnecting per fetch would spend 100–500ms per call
9
+ * and open one socket per concurrent tab for no benefit.
7
10
  *
8
11
  * Liveness is handled three ways: `isConnected()` is checked before reuse, a
9
12
  * `disconnected` event (when the backend emits it) drops the reference
10
- * immediately, and a `newContext` failure against a dead connection triggers
13
+ * immediately, and an open-lease failure against a dead connection triggers
11
14
  * exactly one reconnect-and-retry before the error surfaces. A changed
12
15
  * endpoint (settings edit) replaces the connection.
13
16
  *
14
17
  * @module dsh-web-fetch-playwright/cdp-pool
15
18
  */
16
- import type { PlaywrightBrowser, PlaywrightContext } from './types.ts';
19
+ import type { PlaywrightBrowser, PlaywrightContext, PlaywrightPage } from './types.ts';
17
20
  /** Opens the shared connection; injected so tests can substitute a fake. */
18
21
  export type CdpConnect = (endpoint: string, timeoutMs: number) => Promise<PlaywrightBrowser>;
19
- /** One fetch's lease: the shared browser plus a context it owns. */
22
+ /** How a lease scopes its fetch: throwaway context or the remote profile. */
23
+ export type CdpAcquireMode = 'isolated' | 'profile';
24
+ /** One fetch's lease: the shared browser, a context, and the tab it owns. */
20
25
  export interface CdpLease {
21
26
  /** The shared connection — close only what the lease owns, never this. */
22
27
  browser: PlaywrightBrowser;
23
- /** The fetch-owned isolated context; {@link CdpConnectionPool.release} closes it. */
28
+ /**
29
+ * The context the page lives in: fetch-owned (`isolated`) or the remote
30
+ * browser's default context (`profile`). NEVER close the latter — closing
31
+ * it tears down the whole shared connection (playwright-core maps a
32
+ * default-context close to "close browser" for this connection).
33
+ */
24
34
  context: PlaywrightContext;
35
+ /** The fetch-owned tab; {@link CdpConnectionPool.release} always closes it. */
36
+ page: PlaywrightPage;
37
+ /** True when `context` is the remote default context: release must not close it. */
38
+ persistent: boolean;
25
39
  }
26
- /** A reusable `connectOverCDP` session handing out per-fetch contexts. */
40
+ /** A reusable `connectOverCDP` session handing out per-fetch pages. */
27
41
  export declare class CdpConnectionPool {
28
42
  private readonly connect;
29
43
  private browser;
@@ -38,21 +52,33 @@ export declare class CdpConnectionPool {
38
52
  */
39
53
  constructor(connect: CdpConnect);
40
54
  /**
41
- * Lease a fresh isolated context on the shared connection, connecting (or
55
+ * Lease a fetch's page on the shared connection, connecting (or
42
56
  * reconnecting) first if needed. Concurrent first fetches share one
43
57
  * connect attempt.
44
58
  *
45
59
  * @param endpoint - normalized CDP endpoint URL.
46
60
  * @param timeoutMs - connect timeout budget.
47
- * @returns the shared browser and a context the caller must release.
61
+ * @param mode - `isolated` (default): a fresh throwaway context plus a page
62
+ * in it; `profile`: a page in the remote browser's default context — the
63
+ * real profile — which is never closed, only the page is.
64
+ * @returns the shared browser, the page's context, and the page the caller
65
+ * must release.
48
66
  * @throws whatever the connect function throws when no connection can be
49
- * established (the provider wraps it in a structured WebError).
67
+ * established (the provider wraps it in a structured WebError), or a
68
+ * diagnostic error when `profile` mode finds no default context.
69
+ */
70
+ acquire(endpoint: string, timeoutMs: number, mode?: CdpAcquireMode): Promise<CdpLease>;
71
+ /**
72
+ * Open one lease's page on a live connection. The profile-mode handle is
73
+ * taken fresh every call (never cached across connections): a reconnect
74
+ * yields a new Browser object whose `contexts()[0]` must be re-read.
50
75
  */
51
- acquire(endpoint: string, timeoutMs: number): Promise<CdpLease>;
76
+ private openLease;
52
77
  /**
53
- * Close a fetch-owned context. The shared connection stays open for the
54
- * next fetch.
55
- * @param lease - the lease whose context goes away.
78
+ * Close a fetch-owned page, plus its context when the lease owns one. The
79
+ * remote default context (persistent leases) and the shared connection
80
+ * stay for the next fetch.
81
+ * @param lease - the lease whose page (and, when isolated, context) goes away.
56
82
  */
57
83
  release(lease: CdpLease): Promise<void>;
58
84
  /**
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * The Playwright plugin-configuration card: backend radio group (each option
3
- * carrying its backend-specific input nested inside — local path under Local
4
- * Playwright, CDP endpoint under Remote CDP) plus the denoise checkbox,
5
- * staged and saved through the card form like the built-in plugin cards.
3
+ * carrying its backend-specific inputs nested inside — local path under Local
4
+ * Playwright, CDP endpoint and shared-context checkbox under Remote CDP) plus
5
+ * the denoise checkbox, staged and saved through the card form like the
6
+ * built-in plugin cards.
6
7
  *
7
8
  * @module dsh-web-fetch-playwright/client/card
8
9
  */
@@ -20,6 +20,12 @@ export interface PlaywrightSettings {
20
20
  playwrightPath?: string;
21
21
  /** CDP backend: endpoint (host:port / http(s) / ws). */
22
22
  cdpEndpoint?: string;
23
+ /**
24
+ * CDP backend: whether fetches share the remote browser's context (its
25
+ * real profile — cookies, localStorage, persistent logins) as tabs, or
26
+ * each use a fresh isolated context. Absent = schema default (true).
27
+ */
28
+ shareBrowserContext?: boolean;
23
29
  /** Whether the Readability + DOMPurify pipeline runs. */
24
30
  denoise?: boolean;
25
31
  /** How many fetches may render at once (1–200); blank = backend default. */
@@ -33,6 +39,8 @@ export interface PlaywrightCardState extends CardShell {
33
39
  playwrightPath: CardFieldState;
34
40
  /** CDP endpoint input. */
35
41
  cdpEndpoint: CardFieldState;
42
+ /** CDP shared-context checkbox (draft 'true'/'false'). */
43
+ shareBrowserContext: CardFieldState;
36
44
  /** Denoise checkbox (draft 'true'/'false'). */
37
45
  denoise: CardFieldState;
38
46
  /** Concurrency input (draft decimal integer). */
@@ -54,7 +54,11 @@ export declare function RadioGroupField(props: {
54
54
  onEdit: (text: string) => void;
55
55
  onReset: () => void;
56
56
  }): import("react").JSX.Element;
57
- /** A staged checkbox: the denoise toggle. An absent stored value defaults to on. */
57
+ /**
58
+ * A staged checkbox: the denoise toggle and the CDP shared-context toggle.
59
+ * An absent stored value formats as '' — callers render the schema default
60
+ * (denoise on, context shared).
61
+ */
58
62
  export declare function CheckboxField(props: {
59
63
  id: string;
60
64
  label: string;
@@ -66,4 +70,6 @@ export declare function CheckboxField(props: {
66
70
  disabled: boolean;
67
71
  onEdit: (text: string) => void;
68
72
  onReset: () => void;
73
+ /** Render inside a radio option: no card-level chrome, hint under the label. */
74
+ embedded?: boolean;
69
75
  }): import("react").JSX.Element;
@@ -5,7 +5,7 @@
5
5
  * @module dsh-web-fetch-playwright/client/locales
6
6
  */
7
7
  /** Locale keys this card renders. */
8
- export type PlaywrightCardLocaleKey = 'title' | 'description' | 'backendLabel' | 'backendLocal' | 'backendLocalHint' | 'backendCdp' | 'backendCdpHint' | 'playwrightPath' | 'playwrightPathHint' | 'playwrightPathPlaceholder' | 'cdpEndpoint' | 'cdpEndpointHint' | 'denoise' | 'denoiseHint' | 'maxConcurrency' | 'maxConcurrencyHint' | 'maxConcurrencyPlaceholder' | 'overridden' | 'reset' | 'readOnly' | 'expand' | 'collapse' | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed' | 'invalidText';
8
+ export type PlaywrightCardLocaleKey = 'title' | 'description' | 'backendLabel' | 'backendLocal' | 'backendLocalHint' | 'backendCdp' | 'backendCdpHint' | 'playwrightPath' | 'playwrightPathHint' | 'playwrightPathPlaceholder' | 'cdpEndpoint' | 'cdpEndpointHint' | 'shareBrowserContext' | 'shareBrowserContextHint' | 'denoise' | 'denoiseHint' | 'maxConcurrency' | 'maxConcurrencyHint' | 'maxConcurrencyPlaceholder' | 'overridden' | 'reset' | 'readOnly' | 'expand' | 'collapse' | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed' | 'invalidText';
9
9
  /** This plugin's dictionary namespace, merged into the locale key map. */
10
10
  declare module '@deepseek-ai/dsh-client-ui-slots' {
11
11
  interface LocaleNamespaceMap {
@@ -26,6 +26,11 @@ export declare const DEFAULT_MAX_CONCURRENCY_CDP = 50;
26
26
  export declare const MAX_CONCURRENCY_CEILING = 200;
27
27
  /** Which browser backend serves a fetch. */
28
28
  export type PlaywrightBackend = 'local' | 'cdp';
29
+ /**
30
+ * How the CDP backend scopes a fetch: a throwaway isolated context, or a tab
31
+ * in the remote browser's real profile (default context).
32
+ */
33
+ export type CdpContextMode = 'isolated' | 'profile';
29
34
  /** Plugin config: everything optional — the schema fills the defaults. */
30
35
  export interface Config {
31
36
  /** Backend selector: local Playwright launch or a remote CDP endpoint. */
@@ -38,6 +43,14 @@ export interface Config {
38
43
  playwrightPath?: string;
39
44
  /** CDP backend: `host:port`, `http(s)://…`, or `ws(s)://…`. Empty = default. */
40
45
  cdpEndpoint?: string;
46
+ /**
47
+ * CDP backend only. `true` (default): each fetch is a tab in the remote
48
+ * browser's default context — the real profile — so cookies/localStorage
49
+ * come from (and are written back to) it and its persistent logins apply.
50
+ * `false`: a fresh incognito-like isolated context per fetch, no shared
51
+ * state. Meaningless for the local backend (collapses to isolated).
52
+ */
53
+ shareBrowserContext?: boolean;
41
54
  /** Whether the Readability + DOMPurify denoise pipeline runs before markdown. */
42
55
  denoise?: boolean;
43
56
  /**
@@ -65,6 +78,17 @@ export type ResolvedConfig = Omit<Required<Config>, 'maxConcurrency'> & {
65
78
  * @returns the effective limit for the semaphore.
66
79
  */
67
80
  export declare function effectiveMaxConcurrency(config: Pick<Config, 'backend' | 'maxConcurrency'>): number;
81
+ /**
82
+ * The context mode a fetch actually runs with: profile (a tab in the remote
83
+ * browser's real profile) requires the CDP backend — a local launch has no
84
+ * meaningful shared profile — and the checkbox (which defaults on, so an
85
+ * absent value reads as `true`, mirroring the schema default); everything
86
+ * else collapses to isolated.
87
+ *
88
+ * @param config - the resolved settings section (or any partial of it).
89
+ * @returns the mode the pool acquires its lease with.
90
+ */
91
+ export declare function effectiveContextMode(config: Pick<Config, 'backend' | 'shareBrowserContext'>): CdpContextMode;
68
92
  /**
69
93
  * Normalize a configured CDP endpoint for `chromium.connectOverCDP`:
70
94
  * blank becomes the default loopback endpoint; `wss?://` and `https?://`
@@ -11,10 +11,10 @@
11
11
  */
12
12
  import type { Context } from '@deepseek-ai/cordis';
13
13
  import { Config } from './config.ts';
14
- export { Config, DEFAULT_CDP_ENDPOINT, normalizeCdpEndpoint } from './config.ts';
15
- export type { Config as PlaywrightFetchConfig, PlaywrightBackend, ResolvedConfig } from './config.ts';
14
+ export { Config, DEFAULT_CDP_ENDPOINT, effectiveContextMode, normalizeCdpEndpoint } from './config.ts';
15
+ export type { Config as PlaywrightFetchConfig, CdpContextMode, PlaywrightBackend, ResolvedConfig } from './config.ts';
16
16
  export { CdpConnectionPool } from './cdp-pool.ts';
17
- export type { CdpConnect, CdpLease } from './cdp-pool.ts';
17
+ export type { CdpAcquireMode, CdpConnect, CdpLease } from './cdp-pool.ts';
18
18
  export { PLAYWRIGHT_FETCH_PROVIDER_ID, PlaywrightFetchProvider } from './provider.ts';
19
19
  export { htmlToMarkdown } from './markdown.ts';
20
20
  export type { DenoiseMode, DenoiseResult } from './markdown.ts';
@@ -6,37 +6,45 @@
6
6
  *
7
7
  * Lifecycle: the local backend launches a browser per fetch and closes it —
8
8
  * nothing outlives the call. The CDP backend keeps ONE shared connection to
9
- * the remote browser for the provider's lifetime; each fetch only opens an
10
- * isolated context (a tab) inside it and closes that on completion, so the
11
- * concurrency cap counts tabs, not browsers. Either way, an aborted signal
12
- * closes the fetch's context. Concurrency is capped at the `maxConcurrency`
13
- * setting (explicit, or the backend default — {@link DEFAULT_MAX_CONCURRENCY_LOCAL}
14
- * browsers / {@link DEFAULT_MAX_CONCURRENCY_CDP} tabs); further fetches wait
15
- * briefly in a queue and fail fast (rather than hang until abort) when no
16
- * slot frees.
9
+ * the remote browser for the provider's lifetime; each fetch only opens a
10
+ * page (tab) inside it and closes that on completion — in a throwaway
11
+ * isolated context, or (the default, `shareBrowserContext`) in the remote
12
+ * browser's default context so its profile, cookies, and persistent logins
13
+ * apply; that default context is never closed. The concurrency cap counts
14
+ * tabs, not browsers. Either way, an aborted signal closes the fetch's page.
15
+ * Concurrency is capped at the `maxConcurrency` setting (explicit, or the
16
+ * backend default — {@link DEFAULT_MAX_CONCURRENCY_LOCAL} browsers /
17
+ * {@link DEFAULT_MAX_CONCURRENCY_CDP} tabs); further fetches wait briefly in
18
+ * a queue and fail fast (rather than hang until abort) when no slot frees.
17
19
  *
18
20
  * Private-network and SSRF protection is not implemented (same stance as the
19
21
  * shipped HTTP provider); a page this provider can reach is whatever the
20
- * browser can reach.
22
+ * browser can reach. Profile mode additionally acts WITH the remote
23
+ * browser's logged-in sessions (see the README's risk notes).
21
24
  *
22
25
  * @module dsh-web-fetch-playwright/provider
23
26
  */
24
27
  import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
25
28
  import type { ResolvedConfig } from './config.ts';
26
29
  import { CdpConnectionPool } from './cdp-pool.ts';
27
- import type { PlaywrightBrowser, PlaywrightContext } from './types.ts';
30
+ import type { PlaywrightBrowser, PlaywrightContext, PlaywrightPage } from './types.ts';
28
31
  /** Stable id this provider registers under (the bundle patch pins it). */
29
32
  export declare const PLAYWRIGHT_FETCH_PROVIDER_ID = "playwright";
30
33
  /**
31
- * One render session: a browser and the context this fetch owns. Local
32
- * backends own the browser too; CDP sessions ride the shared connection and
33
- * only their context closes at the end.
34
+ * One render session: a browser, the context this fetch works in, and the
35
+ * tab it owns. Local backends own the browser too; CDP sessions ride the
36
+ * shared connection, and in `profile` mode the context is the remote
37
+ * browser's default context — shared, never closed, only the tab is.
34
38
  */
35
39
  export interface BrowserSession {
36
40
  browser: PlaywrightBrowser;
37
41
  context: PlaywrightContext;
42
+ /** The fetch-owned tab this fetch renders in. */
43
+ page: PlaywrightPage;
38
44
  /** True when `browser` is the CDP pool's shared connection — never closed per fetch. */
39
45
  sharedBrowser?: boolean;
46
+ /** True when `context` is the remote default context — close only the page. */
47
+ persistent?: boolean;
40
48
  }
41
49
  /**
42
50
  * A single abort deadline composing the caller's signal with this provider's
@@ -80,14 +88,14 @@ export declare class PlaywrightFetchProvider implements WebFetchProvider {
80
88
  dispose(): Promise<void>;
81
89
  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
82
90
  /**
83
- * Open the configured backend and its per-fetch context. Split out so the
91
+ * Open the configured backend and its per-fetch page. Split out so the
84
92
  * test suite can substitute a fake browser.
85
93
  * @param config - the resolved settings section.
86
94
  * @param deadline - the fetch budget, applied to launch/connect timeouts.
87
95
  * @returns the browser session the fetch will use.
88
96
  */
89
97
  protected openSession(config: ResolvedConfig, deadline: Deadline): Promise<BrowserSession>;
90
- /** Navigate, settle, and decode one URL inside an open session. */
98
+ /** Navigate, settle, and decode one URL inside an open session's tab. */
91
99
  private retrieve;
92
100
  }
93
101
  export {};
@@ -25,8 +25,19 @@ export interface PlaywrightPage {
25
25
  url(): string;
26
26
  content(): Promise<string>;
27
27
  close(): Promise<void>;
28
+ /**
29
+ * Resource-filter interception at page level — installed on the page (not
30
+ * its context) so profile mode never intercepts tabs it does not own.
31
+ */
32
+ route(glob: string, handler: (route: PlaywrightRoute) => Promise<void>): Promise<void>;
33
+ /** Popup notification; the fetch closes whatever its page spawns. */
34
+ on?(event: 'popup', listener: (page: PlaywrightPage) => void): unknown;
28
35
  }
29
- /** An isolated browser context (the CDP backend gets a fresh one per fetch). */
36
+ /**
37
+ * A browser context: fetch-owned and isolated (local backend, or CDP
38
+ * `isolated` mode), or the remote browser's default context carrying its
39
+ * real profile (CDP `profile` mode — never closed by a fetch).
40
+ */
30
41
  export interface PlaywrightContext {
31
42
  newPage(): Promise<PlaywrightPage>;
32
43
  route(glob: string, handler: (route: PlaywrightRoute) => Promise<void>): Promise<void>;
@@ -44,6 +55,12 @@ export interface PlaywrightRoute {
44
55
  export interface PlaywrightBrowser {
45
56
  newContext(): Promise<PlaywrightContext>;
46
57
  close(): Promise<void>;
58
+ /**
59
+ * Contexts visible to this connection. Over CDP the default context — the
60
+ * remote browser's real profile — is always dispatched first, so `[0]` is
61
+ * it; absent on minimal fakes (isolated mode never calls this).
62
+ */
63
+ contexts?(): PlaywrightContext[];
47
64
  /** Liveness probe; absent on minimal fakes (assumed live). */
48
65
  isConnected?(): boolean;
49
66
  /** Optional disconnect notification used to drop a stale shared CDP connection. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-web-fetch-playwright",
3
- "version": "0.2.0",
3
+ "version": "0.2.3",
4
4
  "description": "Playwright/CDP web-fetch provider for DeepSeek Harness: renders pages in a real browser, denoises them (Readability + DOMPurify), and returns markdown.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -75,10 +75,11 @@
75
75
  "permissions": [
76
76
  "network:fetch (renders the URLs the user requests in a local browser)",
77
77
  "network:connect (user-configured CDP endpoint, default 127.0.0.1:9222)",
78
- "fs:read (user-configured playwright/browser executable path)"
78
+ "fs:read (user-configured playwright/browser executable path)",
79
+ "network:fetch (CDP profile mode: renders the URLs the user requests WITH the remote browser's logged-in sessions)"
79
80
  ],
80
81
  "jurisdiction": [],
81
- "retention": "none"
82
+ "retention": "none (profile mode: site data lands in the remote browser's own persistent user-data-dir, which this plugin never cleans)"
82
83
  },
83
84
  "dependencies": {
84
85
  "@deepseek-ai/schemastery": ">=3.18.1-rc.1 <4",
package/src/cdp-pool.ts CHANGED
@@ -1,33 +1,48 @@
1
1
  /**
2
2
  * The CDP backend's shared connection: one `connectOverCDP` session reused by
3
- * every fetch, each fetch leasing an isolated context (a tab in the remote
4
- * browser) that it closes when done. The connection itself outlives fetches —
5
- * reconnecting per fetch would spend 100–500ms per call and open one socket
6
- * per concurrent tab for no benefit.
3
+ * every fetch, each fetch leasing a page (a tab in the remote browser) that
4
+ * it closes when done — in an isolated throwaway context (`isolated` mode),
5
+ * or in the remote browser's default context (`profile` mode, whose cookies
6
+ * and localStorage are the real profile's, so its persistent logins apply;
7
+ * that context is never closed, only the tab is). The connection itself
8
+ * outlives fetches — reconnecting per fetch would spend 100–500ms per call
9
+ * and open one socket per concurrent tab for no benefit.
7
10
  *
8
11
  * Liveness is handled three ways: `isConnected()` is checked before reuse, a
9
12
  * `disconnected` event (when the backend emits it) drops the reference
10
- * immediately, and a `newContext` failure against a dead connection triggers
13
+ * immediately, and an open-lease failure against a dead connection triggers
11
14
  * exactly one reconnect-and-retry before the error surfaces. A changed
12
15
  * endpoint (settings edit) replaces the connection.
13
16
  *
14
17
  * @module dsh-web-fetch-playwright/cdp-pool
15
18
  */
16
19
 
17
- import type { PlaywrightBrowser, PlaywrightContext } from './types.ts'
20
+ import type { PlaywrightBrowser, PlaywrightContext, PlaywrightPage } from './types.ts'
18
21
 
19
22
  /** Opens the shared connection; injected so tests can substitute a fake. */
20
23
  export type CdpConnect = (endpoint: string, timeoutMs: number) => Promise<PlaywrightBrowser>
21
24
 
22
- /** One fetch's lease: the shared browser plus a context it owns. */
25
+ /** How a lease scopes its fetch: throwaway context or the remote profile. */
26
+ export type CdpAcquireMode = 'isolated' | 'profile'
27
+
28
+ /** One fetch's lease: the shared browser, a context, and the tab it owns. */
23
29
  export interface CdpLease {
24
30
  /** The shared connection — close only what the lease owns, never this. */
25
31
  browser: PlaywrightBrowser
26
- /** The fetch-owned isolated context; {@link CdpConnectionPool.release} closes it. */
32
+ /**
33
+ * The context the page lives in: fetch-owned (`isolated`) or the remote
34
+ * browser's default context (`profile`). NEVER close the latter — closing
35
+ * it tears down the whole shared connection (playwright-core maps a
36
+ * default-context close to "close browser" for this connection).
37
+ */
27
38
  context: PlaywrightContext
39
+ /** The fetch-owned tab; {@link CdpConnectionPool.release} always closes it. */
40
+ page: PlaywrightPage
41
+ /** True when `context` is the remote default context: release must not close it. */
42
+ persistent: boolean
28
43
  }
29
44
 
30
- /** A reusable `connectOverCDP` session handing out per-fetch contexts. */
45
+ /** A reusable `connectOverCDP` session handing out per-fetch pages. */
31
46
  export class CdpConnectionPool {
32
47
  private browser: PlaywrightBrowser | undefined
33
48
  private endpoint = ''
@@ -43,37 +58,74 @@ export class CdpConnectionPool {
43
58
  constructor(private readonly connect: CdpConnect) {}
44
59
 
45
60
  /**
46
- * Lease a fresh isolated context on the shared connection, connecting (or
61
+ * Lease a fetch's page on the shared connection, connecting (or
47
62
  * reconnecting) first if needed. Concurrent first fetches share one
48
63
  * connect attempt.
49
64
  *
50
65
  * @param endpoint - normalized CDP endpoint URL.
51
66
  * @param timeoutMs - connect timeout budget.
52
- * @returns the shared browser and a context the caller must release.
67
+ * @param mode - `isolated` (default): a fresh throwaway context plus a page
68
+ * in it; `profile`: a page in the remote browser's default context — the
69
+ * real profile — which is never closed, only the page is.
70
+ * @returns the shared browser, the page's context, and the page the caller
71
+ * must release.
53
72
  * @throws whatever the connect function throws when no connection can be
54
- * established (the provider wraps it in a structured WebError).
73
+ * established (the provider wraps it in a structured WebError), or a
74
+ * diagnostic error when `profile` mode finds no default context.
55
75
  */
56
- async acquire(endpoint: string, timeoutMs: number): Promise<CdpLease> {
76
+ async acquire(endpoint: string, timeoutMs: number, mode: CdpAcquireMode = 'isolated'): Promise<CdpLease> {
57
77
  const browser = await this.ensure(endpoint, timeoutMs)
58
78
  try {
59
- return { browser, context: await browser.newContext() }
79
+ return await this.openLease(browser, mode)
60
80
  } catch (error: unknown) {
61
- // The connection may have died between ensure() and newContext(); one
62
- // fresh connection attempt, then the error propagates as-is.
81
+ // The connection may have died between ensure() and opening the lease;
82
+ // one fresh connection attempt, then the error propagates as-is.
63
83
  if (this.isLive(browser)) throw error
64
84
  this.drop(browser)
65
85
  const fresh = await this.ensure(endpoint, timeoutMs)
66
- return { browser: fresh, context: await fresh.newContext() }
86
+ return await this.openLease(fresh, mode)
87
+ }
88
+ }
89
+
90
+ /**
91
+ * Open one lease's page on a live connection. The profile-mode handle is
92
+ * taken fresh every call (never cached across connections): a reconnect
93
+ * yields a new Browser object whose `contexts()[0]` must be re-read.
94
+ */
95
+ private async openLease(browser: PlaywrightBrowser, mode: CdpAcquireMode): Promise<CdpLease> {
96
+ if (mode === 'profile') {
97
+ // [0] is the default context: playwright-core's BrowserDispatcher
98
+ // always dispatches it first, and contexts created outside this
99
+ // connection never appear here — so the pick is deterministic.
100
+ const context = browser.contexts?.()[0]
101
+ if (context === undefined) {
102
+ throw new Error('the CDP endpoint exposed no default browser context (profile mode requires a real browser profile)')
103
+ }
104
+ // A failed newPage leaves nothing behind (the default context is not
105
+ // ours to clean), so the acquire-level retry can simply try again.
106
+ return { browser, context, page: await context.newPage(), persistent: true }
107
+ }
108
+ const context = await browser.newContext()
109
+ try {
110
+ return { browser, context, page: await context.newPage(), persistent: false }
111
+ } catch (error: unknown) {
112
+ // The context exists but its page does not: close it now, or a
113
+ // transient newPage failure on a live connection strands the context
114
+ // until the whole connection goes away.
115
+ await context.close().catch(() => {})
116
+ throw error
67
117
  }
68
118
  }
69
119
 
70
120
  /**
71
- * Close a fetch-owned context. The shared connection stays open for the
72
- * next fetch.
73
- * @param lease - the lease whose context goes away.
121
+ * Close a fetch-owned page, plus its context when the lease owns one. The
122
+ * remote default context (persistent leases) and the shared connection
123
+ * stay for the next fetch.
124
+ * @param lease - the lease whose page (and, when isolated, context) goes away.
74
125
  */
75
126
  async release(lease: CdpLease): Promise<void> {
76
- await lease.context.close().catch(() => {})
127
+ await lease.page.close().catch(() => {})
128
+ if (!lease.persistent) await lease.context.close().catch(() => {})
77
129
  }
78
130
 
79
131
  /**
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * The Playwright plugin-configuration card: backend radio group (each option
3
- * carrying its backend-specific input nested inside — local path under Local
4
- * Playwright, CDP endpoint under Remote CDP) plus the denoise checkbox,
5
- * staged and saved through the card form like the built-in plugin cards.
3
+ * carrying its backend-specific inputs nested inside — local path under Local
4
+ * Playwright, CDP endpoint and shared-context checkbox under Remote CDP) plus
5
+ * the denoise checkbox, staged and saved through the card form like the
6
+ * built-in plugin cards.
6
7
  *
7
8
  * @module dsh-web-fetch-playwright/client/card
8
9
  */
@@ -75,20 +76,35 @@ export function PlaywrightCard(props: PlaywrightCardProps) {
75
76
  label: t('backendCdp'),
76
77
  hint: t('backendCdpHint'),
77
78
  content: (
78
- <ValueField
79
- embedded
80
- id="plugin-config-playwright-cdp"
81
- label={t('cdpEndpoint')}
82
- hint={t('cdpEndpointHint')}
83
- placeholder="127.0.0.1:9222"
84
- overriddenLabel={t('overridden')}
85
- resetLabel={t('reset')}
86
- invalidLabel={t('invalidText')}
87
- disabled={disabled || backend !== 'cdp'}
88
- {...state.cdpEndpoint}
89
- onEdit={(text) => { props.edit('cdpEndpoint', text) }}
90
- onReset={() => { props.resetField('cdpEndpoint') }}
91
- />
79
+ <>
80
+ <ValueField
81
+ embedded
82
+ id="plugin-config-playwright-cdp"
83
+ label={t('cdpEndpoint')}
84
+ hint={t('cdpEndpointHint')}
85
+ placeholder="127.0.0.1:9222"
86
+ overriddenLabel={t('overridden')}
87
+ resetLabel={t('reset')}
88
+ invalidLabel={t('invalidText')}
89
+ disabled={disabled || backend !== 'cdp'}
90
+ {...state.cdpEndpoint}
91
+ onEdit={(text) => { props.edit('cdpEndpoint', text) }}
92
+ onReset={() => { props.resetField('cdpEndpoint') }}
93
+ />
94
+ <CheckboxField
95
+ embedded
96
+ id="plugin-config-playwright-share-context"
97
+ label={t('shareBrowserContext')}
98
+ hint={t('shareBrowserContextHint')}
99
+ checked={state.shareBrowserContext.text !== 'false'}
100
+ overridden={state.shareBrowserContext.overridden}
101
+ overriddenLabel={t('overridden')}
102
+ resetLabel={t('reset')}
103
+ disabled={disabled || backend !== 'cdp'}
104
+ onEdit={(text) => { props.edit('shareBrowserContext', text) }}
105
+ onReset={() => { props.resetField('shareBrowserContext') }}
106
+ />
107
+ </>
92
108
  ),
93
109
  },
94
110
  ]}
@@ -24,6 +24,12 @@ export interface PlaywrightSettings {
24
24
  playwrightPath?: string
25
25
  /** CDP backend: endpoint (host:port / http(s) / ws). */
26
26
  cdpEndpoint?: string
27
+ /**
28
+ * CDP backend: whether fetches share the remote browser's context (its
29
+ * real profile — cookies, localStorage, persistent logins) as tabs, or
30
+ * each use a fresh isolated context. Absent = schema default (true).
31
+ */
32
+ shareBrowserContext?: boolean
27
33
  /** Whether the Readability + DOMPurify pipeline runs. */
28
34
  denoise?: boolean
29
35
  /** How many fetches may render at once (1–200); blank = backend default. */
@@ -38,6 +44,8 @@ export interface PlaywrightCardState extends CardShell {
38
44
  playwrightPath: CardFieldState
39
45
  /** CDP endpoint input. */
40
46
  cdpEndpoint: CardFieldState
47
+ /** CDP shared-context checkbox (draft 'true'/'false'). */
48
+ shareBrowserContext: CardFieldState
41
49
  /** Denoise checkbox (draft 'true'/'false'). */
42
50
  denoise: CardFieldState
43
51
  /** Concurrency input (draft decimal integer). */
@@ -67,6 +75,7 @@ export class PlaywrightCardController {
67
75
  radioField('backend', ['local', 'cdp']),
68
76
  textField('playwrightPath'),
69
77
  textField('cdpEndpoint'),
78
+ checkboxField('shareBrowserContext'),
70
79
  checkboxField('denoise'),
71
80
  numberField('maxConcurrency', 1, 200),
72
81
  ],
@@ -80,6 +89,7 @@ export class PlaywrightCardController {
80
89
  backend: this.form.field('backend'),
81
90
  playwrightPath: this.form.field('playwrightPath'),
82
91
  cdpEndpoint: this.form.field('cdpEndpoint'),
92
+ shareBrowserContext: this.form.field('shareBrowserContext'),
83
93
  denoise: this.form.field('denoise'),
84
94
  maxConcurrency: this.form.field('maxConcurrency'),
85
95
  }
@@ -132,6 +132,12 @@
132
132
  color: var(--dsw-alias-label-tertiary);
133
133
  }
134
134
 
135
+ /* Embedded fields (inside a radio option): align the hint under the label
136
+ text column (checkbox 16px + 10px gap) rather than the box. */
137
+ .hintIndented {
138
+ margin-left: 26px;
139
+ }
140
+
135
141
  /* ── radio group ──────────────────────────────────────────────────────── */
136
142
 
137
143
  .radioGroup {
@@ -202,6 +208,12 @@
202
208
  margin-left: 24px;
203
209
  }
204
210
 
211
+ /* Stacked nested fields (endpoint input + shared-context checkbox) keep the
212
+ card's field rhythm between them. */
213
+ .radioContent > * + * {
214
+ margin-top: 12px;
215
+ }
216
+
205
217
  .radioContent input[type='text']:enabled {
206
218
  cursor: text;
207
219
  }