dsh-web-fetch-playwright 0.1.0

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.
@@ -0,0 +1,43 @@
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.
5
+ *
6
+ * @module dsh-web-fetch-playwright/client/PluginCard
7
+ */
8
+ import { type ReactNode } from 'react';
9
+ import type { CardShell } from './form.ts';
10
+ /** 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;
15
+ readOnly: string;
16
+ saveFailed: string;
17
+ discard: string;
18
+ save: string;
19
+ saving: string;
20
+ }
21
+ /** Card chrome props. */
22
+ export interface PluginCardProps {
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;
29
+ /** The card's form state: availability, writability, and what a save would do. */
30
+ state: CardShell;
31
+ /** Write every staged edit. */
32
+ onSave: () => void;
33
+ /** Drop every staged edit. */
34
+ onDiscard: () => void;
35
+ /** The plugin's controls. */
36
+ children: ReactNode;
37
+ }
38
+ /**
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.
42
+ */
43
+ export declare function PluginCard(props: PluginCardProps): import("react").JSX.Element | null;
@@ -0,0 +1,18 @@
1
+ /**
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.
6
+ *
7
+ * @module dsh-web-fetch-playwright/client/card
8
+ */
9
+ import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
10
+ import type { PlaywrightCardFace } from './controller.ts';
11
+ /** Props the renderer binds for the Playwright card. */
12
+ export type PlaywrightCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'web-fetch-playwright'> & InjectFace<PlaywrightCardFace>;
13
+ /**
14
+ * Render the Playwright card.
15
+ * @param props - locale copy, the card snapshot, and its form actions.
16
+ * @returns the card.
17
+ */
18
+ export declare function PlaywrightCard(props: PlaywrightCardProps): import("react").JSX.Element;
@@ -0,0 +1,58 @@
1
+ /**
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.
5
+ *
6
+ * @module dsh-web-fetch-playwright/client/controller
7
+ */
8
+ import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
9
+ import type { CardShell, CardFieldState, CardActions, SnapshotStore } from './form.ts';
10
+ /**
11
+ * Settings namespace this card edits. Spelled here rather than imported: a
12
+ * client package must not depend on a Host package.
13
+ */
14
+ export declare const WEB_FETCH_PLAYWRIGHT_NS = "web-fetch-playwright";
15
+ /** The section fields this card edits. */
16
+ export interface PlaywrightSettings {
17
+ /** Backend selector: local Playwright launch or a remote CDP endpoint. */
18
+ backend?: string;
19
+ /** Local backend: playwright/browser executable path. */
20
+ playwrightPath?: string;
21
+ /** CDP backend: endpoint (host:port / http(s) / ws). */
22
+ cdpEndpoint?: string;
23
+ /** Whether the Readability + DOMPurify pipeline runs. */
24
+ denoise?: boolean;
25
+ }
26
+ /** What the Playwright card renders. */
27
+ export interface PlaywrightCardState extends CardShell {
28
+ /** Backend radio group. */
29
+ backend: CardFieldState;
30
+ /** Local-backend path input. */
31
+ playwrightPath: CardFieldState;
32
+ /** CDP endpoint input. */
33
+ cdpEndpoint: CardFieldState;
34
+ /** Denoise checkbox (draft 'true'/'false'). */
35
+ denoise: CardFieldState;
36
+ }
37
+ /** The registration-side face the card's slot entry injects. */
38
+ export interface PlaywrightCardFace extends CardActions {
39
+ hooks: {
40
+ /** Card snapshot bound by the renderer as usePlaywrightCard. */
41
+ playwrightCard: SnapshotStore<PlaywrightCardState>;
42
+ };
43
+ }
44
+ /** Bridges the `web-fetch-playwright` settings scope onto the card. */
45
+ export declare class PlaywrightCardController {
46
+ private readonly form;
47
+ private readonly store;
48
+ /**
49
+ * @param scope - the bound settings scope for the `web-fetch-playwright` namespace.
50
+ */
51
+ constructor(scope: SettingsScope<PlaywrightSettings>);
52
+ private projection;
53
+ /**
54
+ * Build the face the card's slot registration injects.
55
+ * @returns the card's snapshot and its form actions.
56
+ */
57
+ inject(): PlaywrightCardFace;
58
+ }
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The Playwright card's controls: the shipped ValueField (text input with
3
+ * override badge and reset) plus the two this card adds — a two-option radio
4
+ * group for the backend (each option carrying its backend-specific input
5
+ * nested inside) and a checkbox for the denoise toggle — styled on the same
6
+ * tokens and rhythm as the built-in plugin-configuration fields.
7
+ *
8
+ * @module dsh-web-fetch-playwright/client/fields
9
+ */
10
+ import type { ReactNode } from 'react';
11
+ /** A staged text field (copy of the shipped ValueField). */
12
+ export declare function ValueField(props: {
13
+ id: string;
14
+ label: string;
15
+ hint: string;
16
+ text: string;
17
+ overridden: boolean;
18
+ invalid: boolean;
19
+ overriddenLabel: string;
20
+ resetLabel: string;
21
+ invalidLabel: string;
22
+ disabled: boolean;
23
+ placeholder?: string;
24
+ /** Render inside a radio option: no card-level chrome (border, padding). */
25
+ embedded?: boolean;
26
+ onEdit: (text: string) => void;
27
+ onReset: () => void;
28
+ }): import("react").JSX.Element;
29
+ /** One radio option's copy, staged value, and nested control. */
30
+ export interface RadioOption {
31
+ /** The option's stored value ('local' | 'cdp'). */
32
+ value: string;
33
+ /** Option label shown beside the radio. */
34
+ label: string;
35
+ /** One-line explanation under the option. */
36
+ hint: string;
37
+ /**
38
+ * Optional control rendered inside the option, under the label and hint —
39
+ * used to nest each backend's fill-in input in its own radio option. The
40
+ * option box stays a plain div so the nested field's own label element is
41
+ * valid HTML (a `<label>` may not nest another `<label>`).
42
+ */
43
+ content?: ReactNode;
44
+ }
45
+ /** A staged radio group: the backend selector. */
46
+ export declare function RadioGroupField(props: {
47
+ label: string;
48
+ options: readonly RadioOption[];
49
+ text: string;
50
+ overridden: boolean;
51
+ overriddenLabel: string;
52
+ resetLabel: string;
53
+ disabled: boolean;
54
+ onEdit: (text: string) => void;
55
+ onReset: () => void;
56
+ }): import("react").JSX.Element;
57
+ /** A staged checkbox: the denoise toggle. An absent stored value defaults to on. */
58
+ export declare function CheckboxField(props: {
59
+ id: string;
60
+ label: string;
61
+ hint: string;
62
+ checked: boolean;
63
+ overridden: boolean;
64
+ overriddenLabel: string;
65
+ resetLabel: string;
66
+ disabled: boolean;
67
+ onEdit: (text: string) => void;
68
+ onReset: () => void;
69
+ }): import("react").JSX.Element;
@@ -0,0 +1,159 @@
1
+ /**
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
4
+ * local until the card's save, presence in the user layer — not value
5
+ * equality — marks a field overridden), plus the two field kinds this card
6
+ * adds: a radio group (backend) and a checkbox (denoise), staged through the
7
+ * same draft mechanism as text.
8
+ *
9
+ * Bundled locally because external client bundles cannot value-import
10
+ * `@deepseek-ai/*` packages; the snapshot store is a local structural clone
11
+ * of the runtime contract.
12
+ *
13
+ * @module dsh-web-fetch-playwright/client/form
14
+ */
15
+ import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
16
+ /** The write one field's staged draft performs when the card is saved. */
17
+ export type FieldWrite = {
18
+ kind: 'set';
19
+ value: unknown;
20
+ } | {
21
+ kind: 'clear';
22
+ };
23
+ /** How one section field converts between its stored value and its draft. */
24
+ export interface CardFieldSpec {
25
+ /** Field name inside the namespace section. */
26
+ field: string;
27
+ /** Render a stored value as a draft string; empty when the section carries none. */
28
+ format: (value: unknown) => string;
29
+ /**
30
+ * The write this draft stages, or undefined when the draft is not a value
31
+ * this field accepts — which blocks the save rather than discarding it.
32
+ */
33
+ parse: (text: string) => FieldWrite | undefined;
34
+ }
35
+ /** One field as the card renders it. */
36
+ export interface CardFieldState {
37
+ /** Draft string the control renders. */
38
+ text: string;
39
+ /** Whether saving would leave a user-layer entry for this field. */
40
+ overridden: boolean;
41
+ /** Whether the draft is not a value this field accepts, which blocks saving. */
42
+ invalid: boolean;
43
+ }
44
+ /** Form state every plugin card shares. */
45
+ export interface CardShell {
46
+ /** False while the namespace is not served to this client; the card renders nothing. */
47
+ available: boolean;
48
+ /** Whether the Host document accepts writes. */
49
+ writable: boolean;
50
+ /** Whether the form holds edits that a save would write. */
51
+ dirty: boolean;
52
+ /** Whether any staged draft is invalid, which blocks the save. */
53
+ invalid: boolean;
54
+ /** Whether a save is crossing the wire. */
55
+ saving: boolean;
56
+ /** Whether the last save did not land as staged; cleared by the next edit or save. */
57
+ failed: boolean;
58
+ }
59
+ /** The write actions the card's slot entry injects. */
60
+ export interface CardActions {
61
+ /** Stage a draft for one field. */
62
+ edit: (field: string, text: string) => void;
63
+ /** Stage a clear, so saving lets the field re-inherit the composition layer. */
64
+ resetField: (field: string) => void;
65
+ /** Write every staged edit, then re-seed from what the Host accepted. */
66
+ save: () => void;
67
+ /** Drop every staged edit. */
68
+ discard: () => void;
69
+ }
70
+ /** Minimal observable snapshot source (structural clone of the runtime contract). */
71
+ export interface SnapshotStore<T> {
72
+ getSnapshot(): T;
73
+ subscribe(listener: () => void): () => void;
74
+ set(next: T): void;
75
+ }
76
+ /**
77
+ * A free-text field. An empty draft clears the field, so emptying the control
78
+ * and saving is the same gesture as resetting it.
79
+ * @param field - field name inside the namespace section.
80
+ * @returns the field's conversion spec.
81
+ */
82
+ export declare function textField(field: string): CardFieldSpec;
83
+ /**
84
+ * A radio-group field over a fixed option set.
85
+ * @param field - field name inside the namespace section.
86
+ * @param values - the accepted option values.
87
+ * @returns the field's conversion spec.
88
+ */
89
+ export declare function radioField(field: string, values: readonly string[]): CardFieldSpec;
90
+ /**
91
+ * A checkbox field. The draft carries 'true'/'false'; an absent stored value
92
+ * formats as '' so the control can fall back to the schema default.
93
+ * @param field - field name inside the namespace section.
94
+ * @returns the field's conversion spec.
95
+ */
96
+ export declare function checkboxField(field: string): CardFieldSpec;
97
+ /**
98
+ * Stages the Playwright card's edits over one settings namespace and writes
99
+ * them on save. Publishes through a snapshot store because slot components
100
+ * read through a selector while both the scope and the drafts change below.
101
+ */
102
+ export declare class CardForm<T> {
103
+ private readonly scope;
104
+ private readonly specs;
105
+ private readonly staged;
106
+ private readonly listeners;
107
+ private saving;
108
+ private failed;
109
+ /**
110
+ * @param scope - the bound settings scope for this card's namespace.
111
+ * @param specs - the section fields this card edits.
112
+ */
113
+ constructor(scope: SettingsScope<T>, specs: CardFieldSpec[]);
114
+ /**
115
+ * Publish a projection of this form, rebuilt whenever the scope or a draft
116
+ * changes.
117
+ * @param project - build the card's state from the form's current reads.
118
+ * @returns the store the card's component reads through its bound selector.
119
+ */
120
+ bind<S>(project: () => S): SnapshotStore<S>;
121
+ /**
122
+ * Read the card-level state: what the Host serves, and what a save would do.
123
+ * @returns the form state every card shares.
124
+ */
125
+ shell(): CardShell;
126
+ /**
127
+ * Read one control's state.
128
+ * @param field - field name of a section field.
129
+ * @returns the draft string, whether a save would leave an override, and whether it is invalid.
130
+ */
131
+ field(field: string): CardFieldState;
132
+ /**
133
+ * Build the edit, reset, save, and discard actions bound to this form.
134
+ * @returns the actions the card's slot entry injects.
135
+ */
136
+ actions(): CardActions;
137
+ /**
138
+ * Write every staged edit, then re-seed from what the Host accepted. A save
139
+ * that did not land keeps its drafts, so the user corrects them instead of
140
+ * retyping.
141
+ */
142
+ save(): Promise<void>;
143
+ /**
144
+ * Every staged edit a save would write. An entry whose draft is not a value
145
+ * its field accepts carries no write: the form stays dirty and the save
146
+ * refuses rather than dropping the edit.
147
+ */
148
+ private plan;
149
+ private clear;
150
+ private store;
151
+ private stage;
152
+ private spec;
153
+ private snapshotOf;
154
+ private sectionValue;
155
+ private baseValue;
156
+ private userLayer;
157
+ private stored;
158
+ private publish;
159
+ }
@@ -0,0 +1,17 @@
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.
7
+ *
8
+ * @module dsh-web-fetch-playwright/client
9
+ */
10
+ import type { Context } from 'cordis';
11
+ /** Required services (cordis fiber inject). */
12
+ export declare const inject: string[];
13
+ /**
14
+ * Mount the Playwright plugin-configuration card.
15
+ * @param ctx - the browser plugin context.
16
+ */
17
+ export declare function apply(ctx: Context): void;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Locale bundles for the Playwright card (the plugin's own dictionary
3
+ * namespace, registered with the client locale service).
4
+ *
5
+ * @module dsh-web-fetch-playwright/client/locales
6
+ */
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';
9
+ /** This plugin's dictionary namespace, merged into the locale key map. */
10
+ declare module '@deepseek-ai/dsh-client-ui-slots' {
11
+ interface LocaleNamespaceMap {
12
+ 'web-fetch-playwright': PlaywrightCardLocaleKey;
13
+ }
14
+ }
15
+ /** English copy. */
16
+ export declare const en: Record<PlaywrightCardLocaleKey, string>;
17
+ /** Simplified Chinese copy. */
18
+ export declare const zh: Record<PlaywrightCardLocaleKey, string>;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Settings/config surface for the Playwright fetch provider: the schemastery
3
+ * schema the loader validates the row against, the settings namespace's
4
+ * resolved shape, and the small pure normalizers the provider applies per
5
+ * fetch (CDP endpoint shaping) — kept network-free for unit tests.
6
+ *
7
+ * @module dsh-web-fetch-playwright/config
8
+ */
9
+ import z from '@deepseek-ai/schemastery';
10
+ /** Default CDP endpoint when the settings section leaves it blank. */
11
+ export declare const DEFAULT_CDP_ENDPOINT = "127.0.0.1:9222";
12
+ /** Which browser backend serves a fetch. */
13
+ export type PlaywrightBackend = 'local' | 'cdp';
14
+ /** Plugin config: everything optional — the schema fills the defaults. */
15
+ export interface Config {
16
+ /** Backend selector: local Playwright launch or a remote CDP endpoint. */
17
+ backend?: PlaywrightBackend;
18
+ /**
19
+ * Local backend: path to a `playwright` executable (Node CLI) or to a
20
+ * Chromium-family browser executable. Empty = discover `playwright` on
21
+ * `$PATH`, then fall back to the plugin's bundled `playwright-core`.
22
+ */
23
+ playwrightPath?: string;
24
+ /** CDP backend: `host:port`, `http(s)://…`, or `ws(s)://…`. Empty = default. */
25
+ cdpEndpoint?: string;
26
+ /** Whether the Readability + DOMPurify denoise pipeline runs before markdown. */
27
+ denoise?: boolean;
28
+ }
29
+ export declare const Config: z<Config>;
30
+ /** Complete config after schemastery applies every field default. */
31
+ export type ResolvedConfig = Required<Config>;
32
+ /**
33
+ * Normalize a configured CDP endpoint for `chromium.connectOverCDP`:
34
+ * blank becomes the default loopback endpoint; `wss?://` and `https?://`
35
+ * pass through; a bare `host:port` gains the `http://` scheme Playwright's
36
+ * CDP discovery (`GET /json/version`) expects.
37
+ *
38
+ * @param input - the raw configured endpoint.
39
+ * @returns the endpoint string to hand to Playwright.
40
+ * @throws {Error} when the normalized value is not a parseable URL.
41
+ */
42
+ export declare function normalizeCdpEndpoint(input: string): string;
@@ -0,0 +1,26 @@
1
+ /**
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.
6
+ *
7
+ * A function plugin (NOT a default-export service): like the shipped search
8
+ * providers, it registers INTO the seam's fetch registry.
9
+ *
10
+ * @module dsh-web-fetch-playwright
11
+ */
12
+ import type { Context } from '@deepseek-ai/cordis';
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';
16
+ export { PLAYWRIGHT_FETCH_PROVIDER_ID, PlaywrightFetchProvider } from './provider.ts';
17
+ export { htmlToMarkdown } from './markdown.ts';
18
+ export type { DenoiseMode, DenoiseResult } from './markdown.ts';
19
+ /** Cordis plugin name used by loader diagnostics. */
20
+ export declare const name = "dsh-web-fetch-playwright";
21
+ /** The web seam this provider registers into. */
22
+ export declare const inject: string[];
23
+ /** Settings namespace carrying this provider's configuration card. */
24
+ export declare const WEB_FETCH_PLAYWRIGHT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
25
+ /** Register the Playwright fetch provider with `ctx.web`. */
26
+ export declare function apply(ctx: Context, config: Config): void;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The denoise pipeline: rendered HTML → sanitized article HTML → markdown.
3
+ *
4
+ * The classic stack, in order: jsdom parses the page Playwright rendered;
5
+ * Mozilla Readability extracts the article (dropping nav bars, sidebars,
6
+ * footers, and ad chrome by scoring link density and text mass); DOMPurify
7
+ * sanitizes whatever HTML remains and forbids the layout tags noise lives in;
8
+ * Turndown with the GFM plugin converts to markdown using the same style
9
+ * options and span-safe table rules as the shipped `dsh-tool-web` renderer,
10
+ * so output is consistent with what `web_fetch` produces elsewhere.
11
+ *
12
+ * Pure and synchronous — unit-tested against fixture pages.
13
+ *
14
+ * @module dsh-web-fetch-playwright/markdown
15
+ */
16
+ /** Which extraction path produced a result. */
17
+ export type DenoiseMode = 'article' | 'document';
18
+ /** One denoise pipeline outcome. */
19
+ export interface DenoiseResult {
20
+ /** The markdown body (title, when found, already prepended). */
21
+ markdown: string;
22
+ /** `article` = Readability extraction; `document` = whole-document fallback. */
23
+ mode: DenoiseMode;
24
+ }
25
+ /**
26
+ * Convert one rendered HTML document to denoised markdown.
27
+ *
28
+ * Readability failure (non-article pages) degrades to converting the
29
+ * sanitized whole document — layout tags are still forbidden, so the
30
+ * fallback stays cleaner than raw turndown, and a degraded page beats an
31
+ * error for a body the browser already rendered.
32
+ *
33
+ * @param html - the rendered page HTML (`page.content()`).
34
+ * @param url - the page URL, used to resolve relative links during parsing.
35
+ * @returns the markdown and the extraction mode used.
36
+ */
37
+ export declare function htmlToMarkdown(html: string, url: string): DenoiseResult;
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Locates a usable Playwright for the local backend. Resolution order:
3
+ *
4
+ * 1. the configured executable/document path (settings field `playwrightPath`);
5
+ * 2. when blank, a `playwright` executable discovered on `$PATH`;
6
+ * 3. the plugin's own bundled `playwright-core` dependency.
7
+ *
8
+ * A discovered path is classified, not assumed: the Node `playwright` CLI
9
+ * yields its package (whose `chromium` knows that installation's browser
10
+ * registry), while a Chromium-family browser binary yields the bundled
11
+ * `playwright-core` with `executablePath` pinned to it. The CDP backend needs
12
+ * no local browsers at all and always uses the bundled core.
13
+ *
14
+ * Pure probing lives here; the provider composes it with page navigation.
15
+ *
16
+ * @module dsh-web-fetch-playwright/playwright-resolve
17
+ */
18
+ import type { PlaywrightChromium } from './types.ts';
19
+ /** A resolved local backend: how to reach `chromium` and what to launch. */
20
+ export interface ResolvedPlaywright {
21
+ /** The `chromium` namespace serving `launch` / `connectOverCDP`. */
22
+ chromium: PlaywrightChromium;
23
+ /** Browser binary pinned for `launch({ executablePath })`, when one was configured. */
24
+ executablePath?: string;
25
+ /** Provenance for diagnostics. */
26
+ source: string;
27
+ }
28
+ /**
29
+ * Find `name` as an executable file on `$PATH`.
30
+ * @param name - the executable basename.
31
+ * @returns the first matching path, or undefined.
32
+ */
33
+ export declare function findOnPath(name: string): string | undefined;
34
+ /**
35
+ * Whether a file starts with a native-executable magic (ELF / Mach-O / MZ).
36
+ * @param path - the file to sniff.
37
+ * @returns true when the file is a compiled binary.
38
+ */
39
+ export declare function isNativeExecutable(path: string): boolean;
40
+ /**
41
+ * Walk up from a file (or the file's own directory) to the nearest package
42
+ * root whose manifest names Playwright.
43
+ * @param start - a file path inside or beside the candidate package.
44
+ * @param maxHops - upward directory bound.
45
+ * @returns the package root directory, or undefined.
46
+ */
47
+ export declare function findPlaywrightPackageRoot(start: string, maxHops?: number): string | undefined;
48
+ /**
49
+ * Resolve the local Playwright backend for one fetch.
50
+ *
51
+ * @param configuredPath - the settings `playwrightPath` (blank = auto-discover).
52
+ * @returns how to launch/connect, with provenance for diagnostics.
53
+ * @throws {Error} with an actionable message when nothing usable exists.
54
+ */
55
+ export declare function resolvePlaywrightBackend(configuredPath: string): Promise<ResolvedPlaywright>;
56
+ /** The CDP backend: the bundled core only — no local browser registry needed. */
57
+ export declare function resolveCdpBackend(): Promise<ResolvedPlaywright>;
@@ -0,0 +1,71 @@
1
+ /**
2
+ * The Playwright `WebFetchProvider`: renders one URL in a real browser and
3
+ * returns it as markdown (denoised) or HTML. Mirrors `dsh-web-fetch-http`'s
4
+ * error taxonomy (URL hygiene, abort/timeout translation, content-type
5
+ * classification) so the tool layer sees the same codes from either backend.
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.
11
+ *
12
+ * Private-network and SSRF protection is not implemented (same stance as the
13
+ * shipped HTTP provider); a page this provider can reach is whatever the
14
+ * browser can reach.
15
+ *
16
+ * @module dsh-web-fetch-playwright/provider
17
+ */
18
+ import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
19
+ import type { ResolvedConfig } from './config.ts';
20
+ import type { PlaywrightBrowser, PlaywrightContext } from './types.ts';
21
+ /** Stable id this provider registers under (the bundle patch pins it). */
22
+ export declare const PLAYWRIGHT_FETCH_PROVIDER_ID = "playwright";
23
+ /** One open browser plus its per-fetch context, closed together. */
24
+ export interface BrowserSession {
25
+ browser: PlaywrightBrowser;
26
+ context: PlaywrightContext;
27
+ }
28
+ /**
29
+ * A single abort deadline composing the caller's signal with this provider's
30
+ * time budget. The timeout reason is kept apart from an outer abort so the
31
+ * error translation can pick `WEB_FETCH_TIMEOUT` over `WEB_ABORTED`.
32
+ */
33
+ declare class Deadline {
34
+ readonly signal: AbortSignal;
35
+ private readonly controller;
36
+ private readonly expiresAt;
37
+ private timedOut;
38
+ constructor(outer: AbortSignal | undefined, timeoutMs: number);
39
+ /** Whether OUR timer fired (vs an outer cancellation). */
40
+ get isTimeout(): boolean;
41
+ /** Milliseconds left on the budget, floored at 1 for Playwright options. */
42
+ remainingMs(): number;
43
+ }
44
+ /**
45
+ * The Playwright-backed fetch provider. Configuration is read through a thunk
46
+ * so committed settings-section changes apply to the next fetch with no
47
+ * re-registration.
48
+ */
49
+ export declare class PlaywrightFetchProvider implements WebFetchProvider {
50
+ private readonly configSource;
51
+ readonly id = "playwright";
52
+ private readonly semaphore;
53
+ /**
54
+ * @param configSource - thunk returning the currently authoritative config.
55
+ */
56
+ constructor(configSource: () => ResolvedConfig);
57
+ /** Cheap and side-effect free; backend problems surface per fetch instead. */
58
+ available(): boolean;
59
+ fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
60
+ /**
61
+ * Open the configured backend and its per-fetch context. Split out so the
62
+ * test suite can substitute a fake browser.
63
+ * @param config - the resolved settings section.
64
+ * @param deadline - the fetch budget, applied to launch/connect timeouts.
65
+ * @returns the browser session the fetch will use.
66
+ */
67
+ protected openSession(config: ResolvedConfig, deadline: Deadline): Promise<BrowserSession>;
68
+ /** Navigate, settle, and decode one URL inside an open session. */
69
+ private retrieve;
70
+ }
71
+ export {};