dsh-web-fetch-playwright 0.2.6 → 0.2.8

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.
package/lib/index.js CHANGED
@@ -1,5 +1,4 @@
1
1
  import { createRequire } from "node:module";
2
- import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
3
2
  import z from "@deepseek-ai/schemastery";
4
3
  import { WebError } from "@deepseek-ai/dsh-web";
5
4
  import { JSDOM, VirtualConsole } from "jsdom";
@@ -11,14 +10,6 @@ import { accessSync, constants, readFileSync, realpathSync, statSync } from "nod
11
10
  import { delimiter, dirname, join } from "node:path";
12
11
  import { pathToFileURL } from "node:url";
13
12
  //#region src/config.ts
14
- /**
15
- * Settings/config surface for the Playwright fetch provider: the schemastery
16
- * schema the loader validates the row against, the settings namespace's
17
- * resolved shape, and the small pure normalizers the provider applies per
18
- * fetch (CDP endpoint shaping) — kept network-free for unit tests.
19
- *
20
- * @module dsh-web-fetch-playwright/config
21
- */
22
13
  /** Default CDP endpoint when the settings section leaves it blank. */
23
14
  const DEFAULT_CDP_ENDPOINT = "127.0.0.1:9222";
24
15
  /**
@@ -33,16 +24,59 @@ const MAX_CHALLENGE_WAIT_MS = 6e4;
33
24
  /** Default same-page re-navigation attempts after a challenge wait runs out. */
34
25
  const DEFAULT_CHALLENGE_RETRIES = 1;
35
26
  const Config = z.object({
36
- backend: z.union([z.const("local"), z.const("cdp")]).default("local"),
37
- playwrightPath: z.string().default(""),
38
- cdpEndpoint: z.string().default(""),
39
- shareBrowserContext: z.boolean().default(true),
40
- denoise: z.boolean().default(true),
41
- maxConcurrency: z.number().step(1).min(1).max(200),
42
- challengeWaitMs: z.number().step(100).min(0).max(MAX_CHALLENGE_WAIT_MS).default(DEFAULT_CHALLENGE_WAIT_MS),
43
- challengeRetries: z.number().step(1).min(0).max(3).default(1)
27
+ backend: z.union([z.const("local"), z.const("cdp")]).default("local").volatile(),
28
+ playwrightPath: z.string().default("").volatile(),
29
+ cdpEndpoint: z.string().default("").volatile(),
30
+ shareBrowserContext: z.boolean().default(true).volatile(),
31
+ denoise: z.boolean().default(true).volatile(),
32
+ maxConcurrency: z.number().step(1).min(1).max(200).volatile(),
33
+ challengeWaitMs: z.number().step(100).min(0).max(MAX_CHALLENGE_WAIT_MS).default(DEFAULT_CHALLENGE_WAIT_MS).volatile(),
34
+ challengeRetries: z.number().step(1).min(0).max(3).default(1).volatile()
44
35
  });
45
36
  /**
37
+ * Read the live references `apply` holds into one plain input for
38
+ * {@link resolveConfig}; a settings commit has usually replaced the
39
+ * snapshots since the last call, which is the whole point.
40
+ *
41
+ * @param config - the plugin config as the loader resolved it.
42
+ * @returns the current snapshots, ready for resolution.
43
+ */
44
+ function snapshotsOf(config) {
45
+ return {
46
+ backend: config.backend.get(),
47
+ playwrightPath: config.playwrightPath.get(),
48
+ cdpEndpoint: config.cdpEndpoint.get(),
49
+ shareBrowserContext: config.shareBrowserContext.get(),
50
+ denoise: config.denoise.get(),
51
+ maxConcurrency: config.maxConcurrency.get(),
52
+ challengeWaitMs: config.challengeWaitMs.get(),
53
+ challengeRetries: config.challengeRetries.get()
54
+ };
55
+ }
56
+ /**
57
+ * Resolve any accepted config input into the fully-defaulted, plain form the
58
+ * provider consumes per fetch. Validation goes through the schema, so the
59
+ * volatile wrappers that produces are unwrapped immediately — the provider
60
+ * consumes plain values. The input face is `Partial` by design (composition
61
+ * entries and volatile snapshots both omit fields; defaults supply them).
62
+ *
63
+ * @param config - composition entry, settings-section value, or volatile snapshots.
64
+ * @returns the resolved config.
65
+ */
66
+ function resolveConfig(config) {
67
+ const resolved = Config(config);
68
+ return {
69
+ backend: resolved.backend.get(),
70
+ playwrightPath: resolved.playwrightPath.get(),
71
+ cdpEndpoint: resolved.cdpEndpoint.get(),
72
+ shareBrowserContext: resolved.shareBrowserContext.get(),
73
+ denoise: resolved.denoise.get(),
74
+ maxConcurrency: resolved.maxConcurrency.get(),
75
+ challengeWaitMs: resolved.challengeWaitMs.get(),
76
+ challengeRetries: resolved.challengeRetries.get()
77
+ };
78
+ }
79
+ /**
46
80
  * The concurrency limit a fetch actually runs with: an explicit setting
47
81
  * wins; otherwise the backend default (local launches browsers, CDP only
48
82
  * opens tabs, so their budgets differ by an order of magnitude).
@@ -127,7 +161,10 @@ function normalizeCdpEndpoint(input) {
127
161
  * (`/cdn-cgi/challenge-platform/` scripts, `#challenge-*` elements,
128
162
  * `cf-chl-widget-` Turnstile frames, `window._cf_chl_opt`). Markers are
129
163
  * deliberately structural: a blog post that merely MENTIONS Cloudflare
130
- * must not classify as a challenge.
164
+ * must not classify as a challenge. Bot Management's passive JSD
165
+ * telemetry (`/cdn-cgi/challenge-platform/scripts/jsd/`), which
166
+ * Cloudflare injects into every NORMAL page of a protected zone, is
167
+ * explicitly neutralized — it is not a challenge signal.
131
168
  *
132
169
  * The security stance (issue #2): this module only DETECTS and classifies.
133
170
  * Solving, spoofing, CAPTCHA answering, and cookie lifting live outside the
@@ -195,14 +232,29 @@ function escapeRegExp(text) {
195
232
  */
196
233
  const CHALLENGE_TITLE_RE = new RegExp(`^(?:${CHALLENGE_TITLE_CORES.map(escapeRegExp).join("|")})[\\s.!??…。!]*$`, "i");
197
234
  /**
235
+ * Cloudflare Bot Management's passive JavaScript-Detections (JSD)
236
+ * telemetry directory. Cloudflare injects this into EVERY normal page of
237
+ * a protected zone — as a direct `<script src>` or as the URL strung
238
+ * inside the hidden-1x1-iframe bootstrap's inline script text — with the
239
+ * page itself a plain 200 of real content. The path therefore proves
240
+ * nothing about a challenge and must be neutralized before the
241
+ * challenge-platform prefix check: real interstitials load orchestrate
242
+ * scripts (`/cdn-cgi/challenge-platform/h/[b|g]/orchestrate/...`), which
243
+ * never live under `scripts/jsd/`.
244
+ */
245
+ const TELEMETRY_JSD_DIR = "/cdn-cgi/challenge-platform/scripts/jsd/";
246
+ /**
198
247
  * Structural markers a challenge document carries in its HTML. Kept in
199
248
  * attribute/assignment form (`id="…"`, `window._cf_chl_opt`) rather than bare
200
249
  * substrings so an article that merely QUOTES these strings in prose or code
201
250
  * samples does not classify — the marker must look like the real element.
251
+ * The bare `/cdn-cgi/challenge-platform/` prefix is checked only after
252
+ * {@link TELEMETRY_JSD_DIR} occurrences are stripped (see
253
+ * {@link classifyChallengeHtml}); `scripts/jsd/main.js` in any spelling is
254
+ * passive telemetry and deliberately absent from this list.
202
255
  */
203
256
  const CHALLENGE_HTML_MARKERS = [
204
257
  "/cdn-cgi/challenge-platform/",
205
- "/cdn-cgi/scripts/jsd/main.js",
206
258
  "id=\"cf-chl-widget-",
207
259
  "window._cf_chl_opt",
208
260
  "id=\"challenge-form\"",
@@ -283,7 +335,8 @@ function classifyChallengeHtml(html) {
283
335
  const lowered = html.toLowerCase();
284
336
  if (lowered.includes(BLOCKED_BODY_PHRASE) && BLOCKED_BODY_MARKERS.some((marker) => lowered.includes(marker))) return "blocked";
285
337
  if (CHALLENGE_TITLE_RE.test(title)) return "challenge";
286
- if (CHALLENGE_HTML_MARKERS.some((marker) => lowered.includes(marker))) return "challenge";
338
+ const withoutTelemetry = lowered.split(TELEMETRY_JSD_DIR).join("");
339
+ if (CHALLENGE_HTML_MARKERS.some((marker) => withoutTelemetry.includes(marker))) return "challenge";
287
340
  if (lowered.includes("class=\"ray-id\"") && lowered.includes("class=\"footer-inner\"")) return "challenge";
288
341
  return "none";
289
342
  }
@@ -293,7 +346,10 @@ function classifyChallengeHtml(html) {
293
346
  * what makes SPA-style clears visible — the document swaps its content
294
347
  * without any navigation, so only a DOM read can see the change. The title
295
348
  * regex is baked in at build time from the same single source the Node-side
296
- * check uses, so the two can never drift apart.
349
+ * check uses, so the two can never drift apart. Script srcs under
350
+ * `/cdn-cgi/challenge-platform/scripts/jsd/` are Bot Management's passive
351
+ * JSD telemetry — present on every normal page of a protected zone — and are
352
+ * excluded just like in {@link classifyChallengeHtml}.
297
353
  */
298
354
  const CHALLENGE_DOM_PROBE = `(() => {
299
355
  const re = new RegExp(${JSON.stringify(CHALLENGE_TITLE_RE.source)}, ${JSON.stringify(CHALLENGE_TITLE_RE.flags)})
@@ -302,7 +358,7 @@ const CHALLENGE_DOM_PROBE = `(() => {
302
358
  if (document.querySelector('[id^="cf-chl-widget-"]')) return true
303
359
  for (const script of Array.from(document.scripts)) {
304
360
  const src = script.getAttribute('src') || ''
305
- if (src.includes('/cdn-cgi/challenge-platform/') || src.includes('/cdn-cgi/scripts/jsd/main.js')) return true
361
+ if (src.includes('/cdn-cgi/challenge-platform/') && !src.includes('/cdn-cgi/challenge-platform/scripts/jsd/')) return true
306
362
  }
307
363
  if (document.querySelector('.footer .footer-inner .ray-id')) return true
308
364
  return false
@@ -1403,24 +1459,31 @@ function guardPopups(page) {
1403
1459
  //#region src/index.ts
1404
1460
  /** Cordis plugin name used by loader diagnostics. */
1405
1461
  const name = "dsh-web-fetch-playwright";
1406
- /** The web seam this provider registers into. */
1462
+ /**
1463
+ * The capability seam this plugin registers into. The settings section
1464
+ * needs no inject: the host's settings service derives it from the entry's
1465
+ * `Config` schema (its volatile fields) by entry id.
1466
+ */
1407
1467
  const inject = ["web"];
1408
- /** Settings namespace carrying this provider's configuration card. */
1409
- const WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE = settingsNamespace("web-fetch-playwright");
1410
- /** Register the Playwright fetch provider with `ctx.web`. */
1468
+ /**
1469
+ * Settings namespace carrying this provider's configuration page: the
1470
+ * composition entry id, which is what the settings service keys the
1471
+ * derived section by.
1472
+ */
1473
+ const WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE = "web-fetch-playwright";
1474
+ /**
1475
+ * Register the Playwright fetch provider with `ctx.web`.
1476
+ *
1477
+ * @param ctx - plugin context supplying the web seam.
1478
+ * @param config - the loader-resolved plugin config; its volatile fields are
1479
+ * live references a settings commit updates in place.
1480
+ */
1411
1481
  function apply(ctx, config) {
1412
- let current = () => config;
1413
- installSettingsSection(ctx, WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE, Config, config, {
1414
- setSource: (source) => {
1415
- current = source;
1416
- },
1417
- onChange: () => {}
1418
- });
1419
- const provider = new PlaywrightFetchProvider(() => current());
1482
+ const provider = new PlaywrightFetchProvider(() => resolveConfig(snapshotsOf(config)));
1420
1483
  ctx.effect(() => () => {
1421
1484
  provider.dispose();
1422
1485
  }, "dsh-web-fetch-playwright: shared CDP connection");
1423
1486
  ctx.web.registerFetchProvider(provider);
1424
1487
  }
1425
1488
  //#endregion
1426
- export { CHALLENGE_DOM_PROBE, CHALLENGE_FINISH_RESERVE_MS, CHALLENGE_POLL_INTERVAL_MS, CHALLENGE_TITLE_RE, CdpConnectionPool, Config, DEFAULT_CDP_ENDPOINT, DEFAULT_CHALLENGE_RETRIES, DEFAULT_CHALLENGE_WAIT_MS, PLAYWRIGHT_FETCH_PROVIDER_ID, PlaywrightFetchProvider, WEB_FETCH_CHALLENGE_CODE, WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE, apply, classifyChallengeHtml, classifyChallengeResponse, effectiveChallengeRetries, effectiveChallengeWaitMs, effectiveContextMode, htmlToMarkdown, inject, isChallengeCompatibleResponse, name, normalizeCdpEndpoint };
1489
+ export { CHALLENGE_DOM_PROBE, CHALLENGE_FINISH_RESERVE_MS, CHALLENGE_POLL_INTERVAL_MS, CHALLENGE_TITLE_RE, CdpConnectionPool, Config, DEFAULT_CDP_ENDPOINT, DEFAULT_CHALLENGE_RETRIES, DEFAULT_CHALLENGE_WAIT_MS, PLAYWRIGHT_FETCH_PROVIDER_ID, PlaywrightFetchProvider, WEB_FETCH_CHALLENGE_CODE, WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE, apply, classifyChallengeHtml, classifyChallengeResponse, effectiveChallengeRetries, effectiveChallengeWaitMs, effectiveContextMode, htmlToMarkdown, inject, isChallengeCompatibleResponse, name, normalizeCdpEndpoint, resolveConfig, snapshotsOf };
@@ -16,7 +16,10 @@
16
16
  * (`/cdn-cgi/challenge-platform/` scripts, `#challenge-*` elements,
17
17
  * `cf-chl-widget-` Turnstile frames, `window._cf_chl_opt`). Markers are
18
18
  * deliberately structural: a blog post that merely MENTIONS Cloudflare
19
- * must not classify as a challenge.
19
+ * must not classify as a challenge. Bot Management's passive JSD
20
+ * telemetry (`/cdn-cgi/challenge-platform/scripts/jsd/`), which
21
+ * Cloudflare injects into every NORMAL page of a protected zone, is
22
+ * explicitly neutralized — it is not a challenge signal.
20
23
  *
21
24
  * The security stance (issue #2): this module only DETECTS and classifies.
22
25
  * Solving, spoofing, CAPTCHA answering, and cookie lifting live outside the
@@ -78,6 +81,9 @@ export declare function classifyChallengeHtml(html: string): ChallengeVerdict;
78
81
  * what makes SPA-style clears visible — the document swaps its content
79
82
  * without any navigation, so only a DOM read can see the change. The title
80
83
  * regex is baked in at build time from the same single source the Node-side
81
- * check uses, so the two can never drift apart.
84
+ * check uses, so the two can never drift apart. Script srcs under
85
+ * `/cdn-cgi/challenge-platform/scripts/jsd/` are Bot Management's passive
86
+ * JSD telemetry — present on every normal page of a protected zone — and are
87
+ * excluded just like in {@link classifyChallengeHtml}.
82
88
  */
83
89
  export declare const CHALLENGE_DOM_PROBE: string;
@@ -1,31 +1,27 @@
1
1
  /**
2
- * The card chrome — a faithful local copy of the shipped `ui-settings-plugins`
3
- * PluginCard (disclosure header, unsaved marker, save/discard footer), with
4
- * the chevron inlined so the bundle stays self-contained.
2
+ * The form chrome — a page-level container (read-only notice, the staged
3
+ * controls, and the save/discard footer), in the rhythm of the shipped
4
+ * plugin-configuration forms. Since the Plugins page (dsh ≥ 0.1.7) draws the
5
+ * title, description, and navigation around a configuration entry, this is
6
+ * the body only; the disclosure header of the old settings-list card is
7
+ * gone with that seat.
5
8
  *
6
9
  * @module dsh-web-fetch-playwright/client/PluginCard
7
10
  */
8
- import { type ReactNode } from 'react';
11
+ import type { ReactNode } from 'react';
9
12
  import type { CardShell } from './form.ts';
10
13
  /** Copy keys the chrome itself renders (the card's dictionary supplies them). */
11
- export interface CardChromeCopy {
12
- expand: string;
13
- collapse: string;
14
- unsaved: string;
14
+ export interface CardFormCopy {
15
15
  readOnly: string;
16
16
  saveFailed: string;
17
17
  discard: string;
18
18
  save: string;
19
19
  saving: string;
20
20
  }
21
- /** Card chrome props. */
22
- export interface PluginCardProps {
21
+ /** Form chrome props. */
22
+ export interface CardFormProps {
23
23
  /** Chrome copy (a subset of the card's locale keys). */
24
- copy: CardChromeCopy;
25
- /** The plugin's display name. */
26
- title: string;
27
- /** The line describing what this plugin's settings govern. */
28
- description: string;
24
+ copy: CardFormCopy;
29
25
  /** The card's form state: availability, writability, and what a save would do. */
30
26
  state: CardShell;
31
27
  /** Write every staged edit. */
@@ -36,8 +32,8 @@ export interface PluginCardProps {
36
32
  children: ReactNode;
37
33
  }
38
34
  /**
39
- * Render the Playwright card's chrome.
40
- * @param props - the card's copy, name, form state, and controls.
41
- * @returns the card, or nothing when the namespace is unavailable.
35
+ * Render the Playwright form's chrome.
36
+ * @param props - the form's copy, form state, and controls.
37
+ * @returns the form body with its footer.
42
38
  */
43
- export declare function PluginCard(props: PluginCardProps): import("react").JSX.Element | null;
39
+ export declare function CardForm(props: CardFormProps): import("react").JSX.Element;
@@ -5,15 +5,22 @@
5
5
  * the denoise checkbox, staged and saved through the card form like the
6
6
  * built-in plugin cards.
7
7
  *
8
+ * The Plugins page asks for `view: 'summary'` (a row's description
9
+ * fallback) or `view: 'page'` (this form). The same component serves both
10
+ * seats it is registered into: the bundle's own page (between its
11
+ * description and its rows) and the row's page (under the plugin's own
12
+ * title); one controller stages the edits shared by the two.
13
+ *
8
14
  * @module dsh-web-fetch-playwright/client/card
9
15
  */
10
16
  import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
11
17
  import type { PlaywrightCardFace } from './controller.ts';
12
18
  /** Props the renderer binds for the Playwright card. */
13
- export type PlaywrightCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'web-fetch-playwright'> & InjectFace<PlaywrightCardFace>;
19
+ export type PlaywrightCardProps = (PropsRuntime<'plugins.bundle.config'> | PropsRuntime<'plugins.row.config'>) & PropsLocale<'web-fetch-playwright'> & InjectFace<PlaywrightCardFace>;
14
20
  /**
15
- * Render the Playwright card.
16
- * @param props - locale copy, the card snapshot, and its form actions.
17
- * @returns the card.
21
+ * Render the Playwright card: its one-liner for the list, or the staged form
22
+ * for the page.
23
+ * @param props - the view asked for, locale copy, the card snapshot, and its form actions.
24
+ * @returns the one-liner, the form, or nothing while the namespace is unavailable.
18
25
  */
19
- export declare function PlaywrightCard(props: PlaywrightCardProps): import("react").JSX.Element;
26
+ export declare function PlaywrightCard(props: PlaywrightCardProps): string | import("react").JSX.Element | null;
@@ -1,15 +1,21 @@
1
1
  /**
2
2
  * The Playwright card's controller: the staged form over the
3
- * `web-fetch-playwright` settings namespace, projected into one snapshot the
4
- * card's slot entry injects.
3
+ * `web-fetch-playwright` plugin-entry configuration form, projected into one
4
+ * snapshot the card's slot entry injects.
5
+ *
6
+ * Since dsh 0.1.7 the scope is the shared `configForms` form for the plugin
7
+ * entry — the host's settings service derives the section from the plugin's
8
+ * Config schema (its volatile fields), keyed by the composition entry id.
5
9
  *
6
10
  * @module dsh-web-fetch-playwright/client/controller
7
11
  */
8
- import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
12
+ import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
9
13
  import type { CardShell, CardFieldState, CardActions, SnapshotStore } from './form.ts';
10
14
  /**
11
- * Settings namespace this card edits. Spelled here rather than imported: a
12
- * client package must not depend on a Host package.
15
+ * Settings namespace this card edits: the composition entry id, which is
16
+ * what the host's settings service keys the section derived from the
17
+ * plugin's Config schema by. Spelled here rather than imported: a client
18
+ * package must not depend on a Host package.
13
19
  */
14
20
  export declare const WEB_FETCH_PLAYWRIGHT_NS = "web-fetch-playwright";
15
21
  /** The section fields this card edits. */
@@ -60,18 +66,22 @@ export interface PlaywrightCardFace extends CardActions {
60
66
  playwrightCard: SnapshotStore<PlaywrightCardState>;
61
67
  };
62
68
  }
63
- /** Bridges the `web-fetch-playwright` settings scope onto the card. */
69
+ /**
70
+ * Bridges the `web-fetch-playwright` configuration form onto the card.
71
+ */
64
72
  export declare class PlaywrightCardController {
65
73
  private readonly form;
66
74
  private readonly store;
67
75
  /**
68
- * @param scope - the bound settings scope for the `web-fetch-playwright` namespace.
76
+ * @param scope - the shared configuration form for the `web-fetch-playwright` entry.
69
77
  */
70
- constructor(scope: SettingsScope<PlaywrightSettings>);
78
+ constructor(scope: ConfigForm<PlaywrightSettings>);
71
79
  private projection;
72
80
  /**
73
81
  * Build the face the card's slot registration injects.
74
82
  * @returns the card's snapshot and its form actions.
75
83
  */
76
84
  inject(): PlaywrightCardFace;
85
+ /** Release the form subscription and every bound stores. */
86
+ dispose(): void;
77
87
  }
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * The staged-form model behind the Playwright card — a faithful subset of the
3
- * shipped `ui-settings-plugins` CardForm (same staging semantics: edits stay
3
+ * shipped plugin-configuration CardForm (same staging semantics: edits stay
4
4
  * local until the card's save, presence in the user layer — not value
5
5
  * equality — marks a field overridden), plus the two field kinds this card
6
6
  * adds: a radio group (backend) and a checkbox (denoise), staged through the
7
- * same draft mechanism as text.
7
+ * same draft mechanism as text. Since dsh 0.1.7 the scope is the shared
8
+ * `configForms` form for the plugin entry (reads ride the describe mirror;
9
+ * writes are revision-fenced path mutations).
8
10
  *
9
11
  * Bundled locally because external client bundles cannot value-import
10
12
  * `@deepseek-ai/*` packages; the snapshot store is a local structural clone
@@ -12,7 +14,7 @@
12
14
  *
13
15
  * @module dsh-web-fetch-playwright/client/form
14
16
  */
15
- import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
17
+ import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
16
18
  /** The write one field's staged draft performs when the card is saved. */
17
19
  export type FieldWrite = {
18
20
  kind: 'set';
@@ -105,22 +107,26 @@ export declare function checkboxField(field: string): CardFieldSpec;
105
107
  */
106
108
  export declare function numberField(field: string, min: number, max: number): CardFieldSpec;
107
109
  /**
108
- * Stages the Playwright card's edits over one settings namespace and writes
109
- * them on save. Publishes through a snapshot store because slot components
110
- * read through a selector while both the scope and the drafts change below.
110
+ * Stages the Playwright card's edits over one plugin-entry configuration
111
+ * form and writes them on save. Publishes through a snapshot store because
112
+ * slot components read through a selector while both the form and the drafts
113
+ * change below.
111
114
  */
112
115
  export declare class CardForm<T> {
113
116
  private readonly scope;
114
117
  private readonly specs;
115
118
  private readonly staged;
116
119
  private readonly listeners;
120
+ private readonly unsubscribe;
117
121
  private saving;
118
122
  private failed;
119
123
  /**
120
- * @param scope - the bound settings scope for this card's namespace.
124
+ * @param scope - the shared configuration form for this plugin's entry.
121
125
  * @param specs - the section fields this card edits.
122
126
  */
123
- constructor(scope: SettingsScope<T>, specs: CardFieldSpec[]);
127
+ constructor(scope: ConfigForm<T>, specs: CardFieldSpec[]);
128
+ /** Release the form subscription and every bound stores. */
129
+ dispose(): void;
124
130
  /**
125
131
  * Publish a projection of this form, rebuilt whenever the scope or a draft
126
132
  * changes.
@@ -147,7 +153,9 @@ export declare class CardForm<T> {
147
153
  /**
148
154
  * Write every staged edit, then re-seed from what the Host accepted. A save
149
155
  * that did not land keeps its drafts, so the user corrects them instead of
150
- * retyping.
156
+ * retyping. The shared form reports `false` (and reloads Host state) for a
157
+ * refused revision or validation, and a transport drop rejects — both fold
158
+ * into the same failed-save path.
151
159
  */
152
160
  save(): Promise<void>;
153
161
  /**
@@ -1,9 +1,19 @@
1
1
  /**
2
- * Browser half of `dsh-web-fetch-playwright`: registers the locale dictionary
3
- * and the plugin-configuration card keyed by the `web-fetch-playwright`
4
- * settings namespace, so the card pairs with the Host section the plugin half
5
- * registers — the shipped configurable-plugins tab dispatches it with no
6
- * changes.
2
+ * Browser half of `dsh-web-fetch-playwright`: registers the locale
3
+ * dictionary and the plugin-configuration card keyed by the
4
+ * `web-fetch-playwright` settings namespace (the composition entry id the
5
+ * host's settings service derives from the plugin's Config schema).
6
+ *
7
+ * Since dsh 0.1.7 the Plugins page owns a plugin's configuration, and its
8
+ * slot contract offers a bundle two seats: the bundle's own form on its
9
+ * package page (`plugins.bundle.config`, keyed by package name — what the
10
+ * user opens straight from the plugin list) and one row's page
11
+ * (`plugins.row.config`, keyed `<package name>#<row id>` — the row's
12
+ * configure control). This bundle is one plugin with one config, so BOTH
13
+ * seats inject the SAME card and controller: whichever way the user arrives,
14
+ * the form is on the first page they land on, and one staging area follows
15
+ * them between the two. The mounts ride `configForms.whileServed`, so a
16
+ * deployment that never composed the host entry shows no trace of the card.
7
17
  *
8
18
  * @module dsh-web-fetch-playwright/client
9
19
  */
@@ -11,7 +21,8 @@ import type { Context } from 'cordis';
11
21
  /** Required services (cordis fiber inject). */
12
22
  export declare const inject: string[];
13
23
  /**
14
- * Mount the Playwright plugin-configuration card.
24
+ * Mount the Playwright plugin-configuration card while the Host serves the
25
+ * `web-fetch-playwright` namespace.
15
26
  * @param ctx - the browser plugin context.
16
27
  */
17
28
  export declare function apply(ctx: Context): void;
@@ -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' | 'shareBrowserContext' | 'shareBrowserContextHint' | 'denoise' | 'denoiseHint' | 'maxConcurrency' | 'maxConcurrencyHint' | 'maxConcurrencyPlaceholder' | 'challengeWaitMs' | 'challengeWaitMsHint' | 'challengeWaitMsPlaceholder' | 'overridden' | 'reset' | 'readOnly' | 'expand' | 'collapse' | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed' | 'invalidText';
8
+ export type PlaywrightCardLocaleKey = 'description' | 'backendLabel' | 'backendLocal' | 'backendLocalHint' | 'backendCdp' | 'backendCdpHint' | 'playwrightPath' | 'playwrightPathHint' | 'playwrightPathPlaceholder' | 'cdpEndpoint' | 'cdpEndpointHint' | 'shareBrowserContext' | 'shareBrowserContextHint' | 'denoise' | 'denoiseHint' | 'maxConcurrency' | 'maxConcurrencyHint' | 'maxConcurrencyPlaceholder' | 'challengeWaitMs' | 'challengeWaitMsHint' | 'challengeWaitMsPlaceholder' | 'overridden' | 'reset' | 'readOnly' | 'save' | 'saving' | 'discard' | '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 {
@@ -4,8 +4,15 @@
4
4
  * resolved shape, and the small pure normalizers the provider applies per
5
5
  * fetch (CDP endpoint shaping) — kept network-free for unit tests.
6
6
  *
7
+ * Since dsh 0.1.7 the settings service derives a plugin's configuration page
8
+ * from its composition entry's `Config` schema: every field marked
9
+ * `.volatile()` is editable live (Settings → Plugins), and a committed edit
10
+ * is pushed into the running plugin's volatile references without a remount —
11
+ * this schema IS the `web-fetch-playwright` settings section.
12
+ *
7
13
  * @module dsh-web-fetch-playwright/config
8
14
  */
15
+ import type { Volatile } from '@deepseek-ai/cordis';
9
16
  import z from '@deepseek-ai/schemastery';
10
17
  /** Default CDP endpoint when the settings section leaves it blank. */
11
18
  export declare const DEFAULT_CDP_ENDPOINT = "127.0.0.1:9222";
@@ -86,7 +93,72 @@ export interface Config {
86
93
  */
87
94
  maxConcurrency?: number;
88
95
  }
89
- export declare const Config: z<Config>;
96
+ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
97
+ backend: z<"local" | "cdp", "local" | "cdp", "volatile-defined">;
98
+ playwrightPath: z<string, string, "volatile-defined">;
99
+ cdpEndpoint: z<string, string, "volatile-defined">;
100
+ shareBrowserContext: z<boolean, boolean, "volatile-defined">;
101
+ denoise: z<boolean, boolean, "volatile-defined">;
102
+ maxConcurrency: z<number, number, "volatile">;
103
+ challengeWaitMs: z<number, number, "volatile-defined">;
104
+ challengeRetries: z<number, number, "volatile-defined">;
105
+ }>>, Schemastery.ObjectT<NoInfer<{
106
+ backend: z<"local" | "cdp", "local" | "cdp", "volatile-defined">;
107
+ playwrightPath: z<string, string, "volatile-defined">;
108
+ cdpEndpoint: z<string, string, "volatile-defined">;
109
+ shareBrowserContext: z<boolean, boolean, "volatile-defined">;
110
+ denoise: z<boolean, boolean, "volatile-defined">;
111
+ maxConcurrency: z<number, number, "volatile">;
112
+ challengeWaitMs: z<number, number, "volatile-defined">;
113
+ challengeRetries: z<number, number, "volatile-defined">;
114
+ }>>, "plain">;
115
+ /**
116
+ * The config `apply` receives once the schema resolves: every volatile field
117
+ * arrives as a live reference whose snapshot a settings commit replaces in
118
+ * place, so the provider re-reads them per fetch (the plugin never remounts
119
+ * for an edit).
120
+ */
121
+ export interface PlaywrightPluginConfig {
122
+ /** Backend selector as a live reference. */
123
+ backend: Volatile<PlaywrightBackend>;
124
+ /** Local backend executable path as a live reference. */
125
+ playwrightPath: Volatile<string>;
126
+ /** CDP endpoint as a live reference. */
127
+ cdpEndpoint: Volatile<string>;
128
+ /** Shared-context toggle as a live reference. */
129
+ shareBrowserContext: Volatile<boolean>;
130
+ /** Denoise toggle as a live reference. */
131
+ denoise: Volatile<boolean>;
132
+ /**
133
+ * Concurrency limit as a live reference; `undefined` while unset (the
134
+ * field owns no default — the backend resolves one).
135
+ */
136
+ maxConcurrency: Volatile<number | undefined>;
137
+ /** Challenge wait budget (ms) as a live reference. */
138
+ challengeWaitMs: Volatile<number>;
139
+ /** Challenge retry count as a live reference. */
140
+ challengeRetries: Volatile<number>;
141
+ }
142
+ /**
143
+ * Read the live references `apply` holds into one plain input for
144
+ * {@link resolveConfig}; a settings commit has usually replaced the
145
+ * snapshots since the last call, which is the whole point.
146
+ *
147
+ * @param config - the plugin config as the loader resolved it.
148
+ * @returns the current snapshots, ready for resolution.
149
+ */
150
+ export declare function snapshotsOf(config: PlaywrightPluginConfig): Config;
151
+ /**
152
+ * Resolve any accepted config input into the fully-defaulted, plain form the
153
+ * provider consumes per fetch. Validation goes through the schema, so the
154
+ * volatile wrappers that produces are unwrapped immediately — the provider
155
+ * consumes plain values. The input face is `Partial` by design (composition
156
+ * entries and volatile snapshots both omit fields; defaults supply them).
157
+ *
158
+ * @param config - composition entry, settings-section value, or volatile snapshots.
159
+ * @returns the resolved config.
160
+ */
161
+ export declare function resolveConfig(config: Partial<Config>): ResolvedConfig;
90
162
  /**
91
163
  * Complete config after schemastery applies the field defaults it owns.
92
164
  * `maxConcurrency` stays optional — {@link effectiveMaxConcurrency} resolves
@@ -1,18 +1,22 @@
1
1
  /**
2
2
  * `dsh-web-fetch-playwright`: registers the Playwright/CDP
3
- * {@link PlaywrightFetchProvider} with `ctx.web` and exposes its settings
4
- * section ('web-fetch-playwright') so the web client's plugin-configuration
5
- * card can edit it live.
3
+ * {@link PlaywrightFetchProvider} with `ctx.web`.
4
+ *
5
+ * The `web-fetch-playwright` settings section is derived from this plugin's
6
+ * `Config` schema (dsh ≥ 0.1.7): its volatile fields are editable live on
7
+ * the Plugins page, and a committed change is pushed into the running
8
+ * config's volatile references — the provider re-reads them per fetch, so an
9
+ * edit reaches the next request without a restart or re-registration.
6
10
  *
7
11
  * A function plugin (NOT a default-export service): like the shipped search
8
- * providers, it registers INTO the seam's fetch registry.
12
+ * providers, it registers INTO the web seam's fetch registry.
9
13
  *
10
14
  * @module dsh-web-fetch-playwright
11
15
  */
12
16
  import type { Context } from '@deepseek-ai/cordis';
13
- import { Config } from './config.ts';
14
- export { Config, DEFAULT_CDP_ENDPOINT, DEFAULT_CHALLENGE_RETRIES, DEFAULT_CHALLENGE_WAIT_MS, effectiveChallengeRetries, effectiveChallengeWaitMs, effectiveContextMode, normalizeCdpEndpoint } from './config.ts';
15
- export type { Config as PlaywrightFetchConfig, CdpContextMode, PlaywrightBackend, ResolvedConfig } from './config.ts';
17
+ import type { PlaywrightPluginConfig } from './config.ts';
18
+ export { Config, DEFAULT_CDP_ENDPOINT, DEFAULT_CHALLENGE_RETRIES, DEFAULT_CHALLENGE_WAIT_MS, effectiveChallengeRetries, effectiveChallengeWaitMs, effectiveContextMode, normalizeCdpEndpoint, resolveConfig, snapshotsOf, } from './config.ts';
19
+ export type { Config as PlaywrightFetchConfig, CdpContextMode, PlaywrightBackend, PlaywrightPluginConfig, ResolvedConfig, } from './config.ts';
16
20
  export { CdpConnectionPool } from './cdp-pool.ts';
17
21
  export type { CdpAcquireMode, CdpConnect, CdpLease } from './cdp-pool.ts';
18
22
  export { CHALLENGE_DOM_PROBE, CHALLENGE_FINISH_RESERVE_MS, CHALLENGE_POLL_INTERVAL_MS, CHALLENGE_TITLE_RE, classifyChallengeHtml, classifyChallengeResponse, isChallengeCompatibleResponse } from './challenge.ts';
@@ -22,9 +26,23 @@ export { htmlToMarkdown } from './markdown.ts';
22
26
  export type { DenoiseMode, DenoiseResult } from './markdown.ts';
23
27
  /** Cordis plugin name used by loader diagnostics. */
24
28
  export declare const name = "dsh-web-fetch-playwright";
25
- /** The web seam this provider registers into. */
29
+ /**
30
+ * The capability seam this plugin registers into. The settings section
31
+ * needs no inject: the host's settings service derives it from the entry's
32
+ * `Config` schema (its volatile fields) by entry id.
33
+ */
26
34
  export declare const inject: string[];
27
- /** Settings namespace carrying this provider's configuration card. */
28
- export declare const WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
29
- /** Register the Playwright fetch provider with `ctx.web`. */
30
- export declare function apply(ctx: Context, config: Config): void;
35
+ /**
36
+ * Settings namespace carrying this provider's configuration page: the
37
+ * composition entry id, which is what the settings service keys the
38
+ * derived section by.
39
+ */
40
+ export declare const WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE = "web-fetch-playwright";
41
+ /**
42
+ * Register the Playwright fetch provider with `ctx.web`.
43
+ *
44
+ * @param ctx - plugin context supplying the web seam.
45
+ * @param config - the loader-resolved plugin config; its volatile fields are
46
+ * live references a settings commit updates in place.
47
+ */
48
+ export declare function apply(ctx: Context, config: PlaywrightPluginConfig): void;