dsh-web-fetch-playwright 0.1.1 → 0.2.2

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.
@@ -20,8 +20,16 @@ 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;
31
+ /** How many fetches may render at once (1–200); blank = backend default. */
32
+ maxConcurrency?: number;
25
33
  }
26
34
  /** What the Playwright card renders. */
27
35
  export interface PlaywrightCardState extends CardShell {
@@ -31,8 +39,12 @@ export interface PlaywrightCardState extends CardShell {
31
39
  playwrightPath: CardFieldState;
32
40
  /** CDP endpoint input. */
33
41
  cdpEndpoint: CardFieldState;
42
+ /** CDP shared-context checkbox (draft 'true'/'false'). */
43
+ shareBrowserContext: CardFieldState;
34
44
  /** Denoise checkbox (draft 'true'/'false'). */
35
45
  denoise: CardFieldState;
46
+ /** Concurrency input (draft decimal integer). */
47
+ maxConcurrency: CardFieldState;
36
48
  }
37
49
  /** The registration-side face the card's slot entry injects. */
38
50
  export interface PlaywrightCardFace extends CardActions {
@@ -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;
@@ -94,6 +94,16 @@ export declare function radioField(field: string, values: readonly string[]): Ca
94
94
  * @returns the field's conversion spec.
95
95
  */
96
96
  export declare function checkboxField(field: string): CardFieldSpec;
97
+ /**
98
+ * An integer field over an inclusive range. The draft is the decimal string;
99
+ * an empty draft clears the field (re-inherit the schema default), and
100
+ * anything but an integer in range blocks the save as invalid.
101
+ * @param field - field name inside the namespace section.
102
+ * @param min - smallest accepted integer (inclusive).
103
+ * @param max - largest accepted integer (inclusive).
104
+ * @returns the field's conversion spec.
105
+ */
106
+ export declare function numberField(field: string, min: number, max: number): CardFieldSpec;
97
107
  /**
98
108
  * Stages the Playwright card's edits over one settings namespace and writes
99
109
  * them on save. Publishes through a snapshot store because slot components
@@ -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' | '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 {
@@ -9,8 +9,28 @@
9
9
  import z from '@deepseek-ai/schemastery';
10
10
  /** Default CDP endpoint when the settings section leaves it blank. */
11
11
  export declare const DEFAULT_CDP_ENDPOINT = "127.0.0.1:9222";
12
+ /**
13
+ * Default concurrency for the local backend: each slot launches a whole
14
+ * Chromium, so the default stays frugal; parallel `web_fetch` bursts stop
15
+ * queueing without a browser farm per fetch.
16
+ */
17
+ export declare const DEFAULT_MAX_CONCURRENCY_LOCAL = 4;
18
+ /**
19
+ * Default concurrency for the CDP backend: the browser already exists, each
20
+ * fetch only opens a tab (isolated context) inside it over one shared
21
+ * connection — so the budget behaves like "max concurrent tabs" and defaults
22
+ * high.
23
+ */
24
+ export declare const DEFAULT_MAX_CONCURRENCY_CDP = 50;
25
+ /** Ceiling the schema accepts for `maxConcurrency` (local slots are browsers). */
26
+ export declare const MAX_CONCURRENCY_CEILING = 200;
12
27
  /** Which browser backend serves a fetch. */
13
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';
14
34
  /** Plugin config: everything optional — the schema fills the defaults. */
15
35
  export interface Config {
16
36
  /** Backend selector: local Playwright launch or a remote CDP endpoint. */
@@ -23,12 +43,52 @@ export interface Config {
23
43
  playwrightPath?: string;
24
44
  /** CDP backend: `host:port`, `http(s)://…`, or `ws(s)://…`. Empty = default. */
25
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;
26
54
  /** Whether the Readability + DOMPurify denoise pipeline runs before markdown. */
27
55
  denoise?: boolean;
56
+ /**
57
+ * How many fetches may render at once. Blank = backend default (4 for
58
+ * local — each slot launches a browser; 50 for CDP — each slot is a tab in
59
+ * the already-running remote browser).
60
+ */
61
+ maxConcurrency?: number;
28
62
  }
29
63
  export declare const Config: z<Config>;
30
- /** Complete config after schemastery applies every field default. */
31
- export type ResolvedConfig = Required<Config>;
64
+ /**
65
+ * Complete config after schemastery applies the field defaults it owns.
66
+ * `maxConcurrency` stays optional — {@link effectiveMaxConcurrency} resolves
67
+ * it against the backend.
68
+ */
69
+ export type ResolvedConfig = Omit<Required<Config>, 'maxConcurrency'> & {
70
+ maxConcurrency?: number;
71
+ };
72
+ /**
73
+ * The concurrency limit a fetch actually runs with: an explicit setting
74
+ * wins; otherwise the backend default (local launches browsers, CDP only
75
+ * opens tabs, so their budgets differ by an order of magnitude).
76
+ *
77
+ * @param config - the resolved settings section (or any partial of it).
78
+ * @returns the effective limit for the semaphore.
79
+ */
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;
32
92
  /**
33
93
  * Normalize a configured CDP endpoint for `chromium.connectOverCDP`:
34
94
  * blank becomes the default loopback endpoint; `wss?://` and `https?://`
@@ -11,8 +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
+ export { CdpConnectionPool } from './cdp-pool.ts';
17
+ export type { CdpAcquireMode, CdpConnect, CdpLease } from './cdp-pool.ts';
16
18
  export { PLAYWRIGHT_FETCH_PROVIDER_ID, PlaywrightFetchProvider } from './provider.ts';
17
19
  export { htmlToMarkdown } from './markdown.ts';
18
20
  export type { DenoiseMode, DenoiseResult } from './markdown.ts';
@@ -4,26 +4,47 @@
4
4
  * error taxonomy (URL hygiene, abort/timeout translation, content-type
5
5
  * classification) so the tool layer sees the same codes from either backend.
6
6
  *
7
- * Lifecycle is per-fetch and fully reversible: local launches close their
8
- * browser, CDP connections disconnect, and an aborted signal closes both —
9
- * no browser outlives the call that opened it. Concurrency is capped at
10
- * {@link MAX_CONCURRENT_FETCHES} local browsers.
7
+ * Lifecycle: the local backend launches a browser per fetch and closes it —
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 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.
11
19
  *
12
20
  * Private-network and SSRF protection is not implemented (same stance as the
13
21
  * shipped HTTP provider); a page this provider can reach is whatever the
14
- * 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).
15
24
  *
16
25
  * @module dsh-web-fetch-playwright/provider
17
26
  */
18
27
  import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
19
28
  import type { ResolvedConfig } from './config.ts';
20
- import type { PlaywrightBrowser, PlaywrightContext } from './types.ts';
29
+ import { CdpConnectionPool } from './cdp-pool.ts';
30
+ import type { PlaywrightBrowser, PlaywrightContext, PlaywrightPage } from './types.ts';
21
31
  /** Stable id this provider registers under (the bundle patch pins it). */
22
32
  export declare const PLAYWRIGHT_FETCH_PROVIDER_ID = "playwright";
23
- /** One open browser plus its per-fetch context, closed together. */
33
+ /**
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.
38
+ */
24
39
  export interface BrowserSession {
25
40
  browser: PlaywrightBrowser;
26
41
  context: PlaywrightContext;
42
+ /** The fetch-owned tab this fetch renders in. */
43
+ page: PlaywrightPage;
44
+ /** True when `browser` is the CDP pool's shared connection — never closed per fetch. */
45
+ sharedBrowser?: boolean;
46
+ /** True when `context` is the remote default context — close only the page. */
47
+ persistent?: boolean;
27
48
  }
28
49
  /**
29
50
  * A single abort deadline composing the caller's signal with this provider's
@@ -50,22 +71,31 @@ export declare class PlaywrightFetchProvider implements WebFetchProvider {
50
71
  private readonly configSource;
51
72
  readonly id = "playwright";
52
73
  private readonly semaphore;
74
+ /** Shared CDP connection; injectable so the suite can substitute a fake. */
75
+ protected readonly cdpPool: CdpConnectionPool;
53
76
  /**
54
77
  * @param configSource - thunk returning the currently authoritative config.
78
+ * @param cdpPool - optional pool over the CDP backend (tests inject fakes).
55
79
  */
56
- constructor(configSource: () => ResolvedConfig);
80
+ constructor(configSource: () => ResolvedConfig, cdpPool?: CdpConnectionPool);
57
81
  /** Cheap and side-effect free; backend problems surface per fetch instead. */
58
82
  available(): boolean;
83
+ /**
84
+ * Drop the shared CDP connection (plugin teardown). Local browsers need
85
+ * nothing — they never outlive their fetch. In-flight CDP fetches keep
86
+ * their leases and close them when they finish.
87
+ */
88
+ dispose(): Promise<void>;
59
89
  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
60
90
  /**
61
- * 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
62
92
  * test suite can substitute a fake browser.
63
93
  * @param config - the resolved settings section.
64
94
  * @param deadline - the fetch budget, applied to launch/connect timeouts.
65
95
  * @returns the browser session the fetch will use.
66
96
  */
67
97
  protected openSession(config: ResolvedConfig, deadline: Deadline): Promise<BrowserSession>;
68
- /** Navigate, settle, and decode one URL inside an open session. */
98
+ /** Navigate, settle, and decode one URL inside an open session's tab. */
69
99
  private retrieve;
70
100
  }
71
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,16 @@ 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[];
64
+ /** Liveness probe; absent on minimal fakes (assumed live). */
65
+ isConnected?(): boolean;
66
+ /** Optional disconnect notification used to drop a stale shared CDP connection. */
67
+ on?(event: 'disconnected', listener: () => void): unknown;
47
68
  }
48
69
  /** The `chromium` namespace of whichever Playwright module serves a fetch. */
49
70
  export interface PlaywrightChromium {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-web-fetch-playwright",
3
- "version": "0.1.1",
3
+ "version": "0.2.2",
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",
@@ -82,10 +82,11 @@
82
82
  "permissions": [
83
83
  "network:fetch (renders the URLs the user requests in a local browser)",
84
84
  "network:connect (user-configured CDP endpoint, default 127.0.0.1:9222)",
85
- "fs:read (user-configured playwright/browser executable path)"
85
+ "fs:read (user-configured playwright/browser executable path)",
86
+ "network:fetch (CDP profile mode: renders the URLs the user requests WITH the remote browser's logged-in sessions)"
86
87
  ],
87
88
  "jurisdiction": [],
88
- "retention": "none"
89
+ "retention": "none (profile mode: site data lands in the remote browser's own persistent user-data-dir, which this plugin never cleans)"
89
90
  },
90
91
  "dependencies": {
91
92
  "@deepseek-ai/schemastery": ">=3.18.1-rc.1 <4",
@@ -0,0 +1,211 @@
1
+ /**
2
+ * The CDP backend's shared connection: one `connectOverCDP` session reused by
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.
10
+ *
11
+ * Liveness is handled three ways: `isConnected()` is checked before reuse, a
12
+ * `disconnected` event (when the backend emits it) drops the reference
13
+ * immediately, and an open-lease failure against a dead connection triggers
14
+ * exactly one reconnect-and-retry before the error surfaces. A changed
15
+ * endpoint (settings edit) replaces the connection.
16
+ *
17
+ * @module dsh-web-fetch-playwright/cdp-pool
18
+ */
19
+
20
+ import type { PlaywrightBrowser, PlaywrightContext, PlaywrightPage } from './types.ts'
21
+
22
+ /** Opens the shared connection; injected so tests can substitute a fake. */
23
+ export type CdpConnect = (endpoint: string, timeoutMs: number) => Promise<PlaywrightBrowser>
24
+
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. */
29
+ export interface CdpLease {
30
+ /** The shared connection — close only what the lease owns, never this. */
31
+ browser: PlaywrightBrowser
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
+ */
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
43
+ }
44
+
45
+ /** A reusable `connectOverCDP` session handing out per-fetch pages. */
46
+ export class CdpConnectionPool {
47
+ private browser: PlaywrightBrowser | undefined
48
+ private endpoint = ''
49
+ private connecting: Promise<PlaywrightBrowser> | undefined
50
+ private connectingEndpoint = ''
51
+ /** Bumped by dispose/replace so a settling connect knows it was abandoned. */
52
+ private generation = 0
53
+
54
+ /**
55
+ * @param connect - opens a connection to an endpoint (the provider's real
56
+ * one resolves the bundled playwright-core; tests inject fakes).
57
+ */
58
+ constructor(private readonly connect: CdpConnect) {}
59
+
60
+ /**
61
+ * Lease a fetch's page on the shared connection, connecting (or
62
+ * reconnecting) first if needed. Concurrent first fetches share one
63
+ * connect attempt.
64
+ *
65
+ * @param endpoint - normalized CDP endpoint URL.
66
+ * @param timeoutMs - connect timeout budget.
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.
72
+ * @throws whatever the connect function throws when no connection can be
73
+ * established (the provider wraps it in a structured WebError), or a
74
+ * diagnostic error when `profile` mode finds no default context.
75
+ */
76
+ async acquire(endpoint: string, timeoutMs: number, mode: CdpAcquireMode = 'isolated'): Promise<CdpLease> {
77
+ const browser = await this.ensure(endpoint, timeoutMs)
78
+ try {
79
+ return await this.openLease(browser, mode)
80
+ } catch (error: unknown) {
81
+ // The connection may have died between ensure() and opening the lease;
82
+ // one fresh connection attempt, then the error propagates as-is.
83
+ if (this.isLive(browser)) throw error
84
+ this.drop(browser)
85
+ const fresh = await this.ensure(endpoint, timeoutMs)
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
117
+ }
118
+ }
119
+
120
+ /**
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.
125
+ */
126
+ async release(lease: CdpLease): Promise<void> {
127
+ await lease.page.close().catch(() => {})
128
+ if (!lease.persistent) await lease.context.close().catch(() => {})
129
+ }
130
+
131
+ /**
132
+ * Drop the shared connection (plugin teardown or endpoint change). Fetches
133
+ * holding leases keep their contexts until they release them. A connect
134
+ * still in flight is abandoned — its own continuation closes the stray
135
+ * browser (nothing here waits on it, so teardown cannot deadlock).
136
+ */
137
+ async dispose(): Promise<void> {
138
+ const browser = this.browser
139
+ this.browser = undefined
140
+ this.endpoint = ''
141
+ this.connecting = undefined
142
+ this.connectingEndpoint = ''
143
+ this.generation++
144
+ await browser?.close().catch(() => {})
145
+ }
146
+
147
+ /** The shared connection for `endpoint`, connecting or reconnecting as needed. */
148
+ private async ensure(endpoint: string, timeoutMs: number): Promise<PlaywrightBrowser> {
149
+ if (this.browser !== undefined && this.endpoint === endpoint && this.isLive(this.browser)) return this.browser
150
+ if (this.connecting !== undefined && this.connectingEndpoint === endpoint) return this.connecting
151
+ // Dead connection or different endpoint: (re)connect. An in-flight connect
152
+ // to another endpoint is abandoned by the generation bump below — its own
153
+ // continuation closes the stray browser and rejects to its waiter.
154
+ return await this.connectFresh(endpoint, timeoutMs)
155
+ }
156
+
157
+ /** Start a connection to `endpoint`, superseding whatever was there. */
158
+ private connectFresh(endpoint: string, timeoutMs: number): Promise<PlaywrightBrowser> {
159
+ const stale = this.browser
160
+ this.browser = undefined
161
+ this.endpoint = ''
162
+ const generation = ++this.generation
163
+ const attempt = (async () => {
164
+ const browser = await this.connect(endpoint, timeoutMs)
165
+ // A dispose/replace won the race while we were connecting: this
166
+ // connection is unwanted — close it and surface the abandonment.
167
+ if (generation !== this.generation) {
168
+ await browser.close().catch(() => {})
169
+ throw new Error('cdp connection abandoned before it attached')
170
+ }
171
+ this.browser = browser
172
+ this.endpoint = endpoint
173
+ this.watch(browser)
174
+ return browser
175
+ })()
176
+ this.connecting = attempt
177
+ this.connectingEndpoint = endpoint
178
+ void attempt.then(
179
+ () => { if (this.connecting === attempt) this.connecting = undefined },
180
+ () => { if (this.connecting === attempt) this.connecting = undefined },
181
+ )
182
+ void stale?.close().catch(() => {})
183
+ return attempt
184
+ }
185
+
186
+ /** Clear the reference when this exact connection reports it went away. */
187
+ private watch(browser: PlaywrightBrowser): void {
188
+ try {
189
+ browser.on?.('disconnected', () => {
190
+ if (this.browser === browser) {
191
+ this.browser = undefined
192
+ this.endpoint = ''
193
+ }
194
+ })
195
+ } catch {
196
+ // a backend that refuses listeners just loses proactive detection
197
+ }
198
+ }
199
+
200
+ /** Forget a connection known to be dead (absent probe = assume dead here). */
201
+ private drop(browser: PlaywrightBrowser): void {
202
+ if (this.browser === browser) {
203
+ this.browser = undefined
204
+ this.endpoint = ''
205
+ }
206
+ }
207
+
208
+ private isLive(browser: PlaywrightBrowser): boolean {
209
+ return browser.isConnected?.() !== false
210
+ }
211
+ }
@@ -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
  ]}
@@ -112,6 +128,19 @@ export function PlaywrightCard(props: PlaywrightCardProps) {
112
128
  onEdit={(text) => { props.edit('denoise', text) }}
113
129
  onReset={() => { props.resetField('denoise') }}
114
130
  />
131
+ <ValueField
132
+ id="plugin-config-playwright-concurrency"
133
+ label={t('maxConcurrency')}
134
+ hint={t('maxConcurrencyHint')}
135
+ placeholder={t('maxConcurrencyPlaceholder')}
136
+ overriddenLabel={t('overridden')}
137
+ resetLabel={t('reset')}
138
+ invalidLabel={t('invalidText')}
139
+ disabled={disabled}
140
+ {...state.maxConcurrency}
141
+ onEdit={(text) => { props.edit('maxConcurrency', text) }}
142
+ onReset={() => { props.resetField('maxConcurrency') }}
143
+ />
115
144
  </PluginCard>
116
145
  )
117
146
  }