@proxyshard/shardx 0.1.1

package/README.md

@@ -0,0 +1,247 @@
+# @proxyshard/shardx (Node)
+
+Self-contained Node/TypeScript SDK for the **ShardX anti-detect
+browser** by the [ProxyShard](https://proxyshard.com) team.
+
+Does **not** depend on the desktop launcher. On first use it downloads
+the patched Chromium 148 engine, Widevine CDM, and the 170-profile
+fingerprint library from our CDN into a local cache, then launches
+isolated browser sessions on demand.
+
+Driven by [patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
+(stealth-patched Playwright) — `sdk.session()` returns a ready-to-use
+`Browser` instance, no manual `connectOverCDP` plumbing.
+
+## Install
+
+```bash
+npm install @proxyshard/shardx
+```
+
+Supported hosts: **macOS arm64**, **Windows x64**, **Linux x64**. Node ≥ 18.
+
+## Quick start
+
+```ts
+import { ShardX } from "@proxyshard/shardx";
+
+const sdk = new ShardX();
+// Engine + Widevine + fingerprint library auto-download from CDN on
+// the first session/launch/listProfiles call (~170 MB once, etag-cached
+// afterward).  No separate install step.
+
+// Launch + drive in one call. Returns the patchright Browser.
+const { browser, session, close } = await sdk.session({
+  fingerprint: "win-rtx4060",
+  proxy: "socks5://user:pass@host:port",
+});
+try {
+  const ctx = browser.contexts()[0];
+  const page = await ctx.newPage();
+  await page.goto("https://browserleaks.com/quic");
+  console.log(await page.title());
+
+  // Inspect what the SDK resolved before launch:
+  console.log(session.geo);             // { countryCode: 'DE', timezone: 'Europe/Berlin', ... }
+  console.log(session.proxyUdpMs,       // UDP RTT in ms or null
+              session.quicEnabled,      // boolean
+              session.webrtcMode);      // "auto" | "tcp_only" | "block"
+} finally {
+  await close();                        // tears down patchright + the engine
+}
+```
+
+### Random profile when none specified
+
+```ts
+const { browser, close } = await sdk.session({
+  platform: "Windows",
+  randomize: true,                      // re-rolls hw_concurrency / RAM / platform_version
+});
+try {
+  const page = await browser.contexts()[0].newPage();
+  // ...
+} finally {
+  await close();
+}
+```
+
+### Discover bundled profiles
+
+```ts
+console.log(sdk.listProfiles().slice(0, 5));
+// [ 'linux-gt1030', 'linux-gtx1050', 'mac-m1-air13', 'mac-m1-imac24', 'mac-m1-max-mbp14' ]
+
+console.log(sdk.listProfiles({ platform: "Windows" }).slice(0, 5));
+
+const profile = sdk.randomProfile({ platform: "macOS" });
+console.log(profile.id, profile.config.webgl.renderer);
+```
+
+### Validate a proxy before binding
+
+```ts
+console.log(await sdk.checkProxy("socks5://user:pass@host:port"));
+// {
+//   udpMs: 142,
+//   geo: { countryCode: 'DE', timezone: 'Europe/Berlin', ... },
+//   wouldEnableQuic: true,
+//   wouldSetWebrtc: 'auto',
+// }
+```
+
+## Pre-launch checks
+
+Every call to `sdk.session()` / `sdk.launch()` runs the same pre-spawn
+pipeline the desktop launcher uses:
+
+1. **`resolveAutoFields`** — if the profile has `"auto"` sentinels for
+   `timezone`, `navigator.language`, or `geolocation.mode`, the SDK
+   makes a live geo lookup through the bound proxy (`ip-api.com` by
+   default). Concrete values get written back: timezone (from the API,
+   never a static table), `accept_language` chain, `languages`,
+   `icu_locale` (always overwritten so `Intl.*` matches
+   `navigator.language`), and lat/lng. Proxy-via failure → direct geo
+   → host `Intl.DateTimeFormat().resolvedOptions().timeZone` as
+   last-resort fallback. The resolved geo is surfaced on
+   `session.geo`.
+2. **`applyScreenStrategy`** — see below.
+3. **`probeUdp`** — SOCKS5 UDP_ASSOCIATE round-trip. If it fails, QUIC
+   is force-disabled and WebRTC switches to `tcp_only` automatically.
+
+### Screen strategy
+
+`screenMode` option to `session()` / `launch()`:
+
+* **`"profile"`** — keep whatever the fingerprint claims.
+* **`"cap_to_host"`** — *macOS default.* If the host monitor is smaller
+  than the FP screen, scale `screen.*` + `window.*` down proportionally;
+  otherwise no-op.
+* **`"use_host"`** — *Windows / Linux default.* Overwrite `screen.*`
+  with the real monitor (minus a 40 px Windows taskbar) and recompute
+  `window.outer*` / `window.inner*`.
+
+Default mode is picked from `navigator.platform`. Override per launch:
+
+```ts
+await sdk.session({ fingerprint: "win-rtx4060", screenMode: "profile" });
+```
+
+### Host-aware hardware randomisation
+
+`randomize: true` re-picks `hardware_concurrency`, `device_memory`, and
+`platform_version` before the launch — using the same logic as the
+desktop launcher:
+
+* **macOS** profiles use the curated `MAC_HW_CONFIGS` table by id.
+* **Windows / Linux** profiles bracket the host's logical CPU count
+  within `[host − 4, host + 2]` from the real x86 set
+  `[4, 6, 8, 12, 16, 20, 24, 28, 32]`; `device_memory` is floored by
+  core count (≥ 12 → 16, else 8) and capped by `hostRamBucketGb()`
+  (8 / 16 / 32 GiB bucketed from `sysctl hw.memsize` / `/proc/meminfo`
+  / `Get-CimInstance Win32_ComputerSystem`).
+
+So a profile launched on an 8-core / 16 GB laptop will never claim
+32 cores / 128 GB of RAM.
+
+### Override fingerprint fields
+
+```ts
+const profile = sdk.library
+  .load("win-rtx4060")
+  .withOverride({
+    name: "my-account",
+    timezone: "Europe/Berlin",
+    navigator: { language: "de-DE" },
+  });
+
+const { browser, close } = await sdk.session({ fingerprint: profile, proxy: "socks5://..." });
+```
+
+### Use your own fingerprint JSON
+
+```ts
+import { Profile } from "@proxyshard/shardx";
+
+const profile = Profile.fromFile("/path/to/my-custom.json");
+const { browser, close } = await sdk.session({ fingerprint: profile });
+```
+
+### WebRTC policy
+
+```ts
+await sdk.session({
+  fingerprint: "win-rtx4060",
+  proxy: "socks5://...",
+  webrtc: "tcp_only",                // "auto" (default) | "block" | "tcp_only"
+  webrtcPublicIp: "203.0.113.42",    // advertised in ICE candidates
+});
+```
+
+### Progress callback during the first-run download
+
+The first `session`/`launch`/`listProfiles` triggers the download.  Hook
+it with a progress callback on the constructor:
+
+```ts
+const sdk = new ShardX({
+  progress: (label, received, total) => {
+    const pct = total ? Math.floor((received / total) * 100) : 0;
+    console.log(`${label}: ${pct}%`);
+  },
+});
+const { browser, close } = await sdk.session({ fingerprint: "win-rtx4060" });
+```
+
+## Advanced: raw launch without patchright
+
+If you'd rather drive the browser with a different CDP client (raw
+`chrome-remote-interface`, puppeteer-core's `connect`, your own
+WebSocket), skip `session()` and use `launch()` directly:
+
+```ts
+const sess = await sdk.launch("win-rtx4060", { proxy: "socks5://...", cdp: true });
+console.log(sess.cdpUrl);              // ws://127.0.0.1:54113/devtools/browser/...
+// ... drive it yourself ...
+await sess.stop();
+```
+
+`launch()` runs the same pre-launch pipeline (auto-resolve, screen
+strategy, UDP probe, hw randomisation) and returns a `BrowserSession`
+with `cdpUrl`, `geo`, `proxyUdpMs`, `quicEnabled`, `webrtcMode`,
+`userDataDir`, and `stop()`.
+
+## Cache layout
+
+```
+~/Library/Application Support/shardx-sdk/    (mac)
+%LOCALAPPDATA%\shardx-sdk\                   (win)
+~/.cache/shardx-sdk/                         (linux)
+├── manifest.json             ← etag cache
+├── ShardX-Mac-arm64/         ← extracted engine
+├── fingerprints/             ← 170 bundled .json profiles
+└── profiles/<profile-id>/    ← per-launch user-data-dir
+```
+
+Override:
+
+```ts
+const sdk = new ShardX({ cacheDir: "/data/shardx" });
+```
+
+## Update the runtime
+
+The SDK auto-checks remote etags on the first `session`/`launch`/`listProfiles`
+call of each process and re-downloads anything that changed.  To force a
+re-download mid-process:
+
+```ts
+await sdk.runtime.install({ force: true });
+```
+
+## License
+
+MIT (this SDK). The Chromium-fork engine binary it downloads at
+runtime is a closed-source product — see the
+[main repo](https://github.com/ProxyShard/ShardBrowser) for engine
+licensing.

package/dist/autoResolve.d.ts

@@ -0,0 +1,10 @@
+import { type GeoInfo } from "./geo.js";
+import type { ParsedProxy } from "./proxy.js";
+export declare function hasAutoFields(cfg: Record<string, unknown>): boolean;
+/**
+ * Apply the launcher's "auto" resolution. Returns the GeoInfo that fed the
+ * resolution, or null when both proxy + direct probes failed and the host
+ * fallback was used.
+ */
+export declare function resolveAutoFields(cfg: Record<string, unknown>, proxy: ParsedProxy | null): Promise<GeoInfo | null>;
+//# sourceMappingURL=autoResolve.d.ts.map

package/dist/autoResolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoResolve.d.ts","sourceRoot":"","sources":["../src/autoResolve.ts"],"names":[],"mappings":"AAQA,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAyD9C,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAOnE;AA4BD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,WAAW,GAAG,IAAI,GACxB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAmEzB"}

package/dist/autoResolve.js

@@ -0,0 +1,181 @@
+// Resolve `"auto"` sentinels in a profile config — port of
+// `resolve_auto_fields` in `src-tauri/src/launch.rs`. Reads the live geo
+// (through the bound proxy when present, direct otherwise), falls back to
+// the host TZ/locale on failure, then mutates `cfg` in place to write
+// concrete timezone / navigator.language / accept_language / languages /
+// icu_locale / geolocation values.
+import { readlinkSync } from "node:fs";
+import { geoCheckVia } from "./geo.js";
+/** ISO-3166 alpha-2 → BCP-47 locale.  Ported 1:1 from launcher's Rust
+ *  `country_to_locale` (src-tauri/src/proxy.rs).  Authoritative table the
+ *  desktop launcher uses — keep in sync if the Rust side ever changes. */
+function countryToLocale(cc) {
+    return CC_TO_LOCALE[(cc ?? "").toUpperCase()] ?? "en-US";
+}
+const CC_TO_LOCALE = {
+    US: "en-US", GB: "en-GB", UK: "en-GB", CA: "en-CA",
+    AU: "en-AU", NZ: "en-NZ", IE: "en-IE", ZA: "en-ZA", IN: "en-IN",
+    DE: "de-DE", AT: "de-AT", CH: "de-CH",
+    FR: "fr-FR", BE: "fr-BE",
+    ES: "es-ES", MX: "es-MX", AR: "es-AR", CO: "es-CO", CL: "es-CL",
+    IT: "it-IT", NL: "nl-NL", PL: "pl-PL",
+    BR: "pt-BR", PT: "pt-PT",
+    RO: "ro-RO", RU: "ru-RU", BY: "be-BY", UA: "uk-UA",
+    TR: "tr-TR", GR: "el-GR",
+    CZ: "cs-CZ", SK: "sk-SK", HU: "hu-HU",
+    SE: "sv-SE", FI: "fi-FI", NO: "nb-NO", DK: "da-DK",
+    BG: "bg-BG", HR: "hr-HR", SI: "sl-SI", RS: "sr-RS",
+    IL: "he-IL",
+    SA: "ar-SA", AE: "ar-SA", EG: "ar-SA",
+    ID: "id-ID", MY: "ms-MY", PH: "fil-PH", VN: "vi-VN", TH: "th-TH",
+    CN: "zh-CN", HK: "zh-HK", TW: "zh-TW",
+    JP: "ja-JP", KR: "ko-KR",
+};
+/** Country → IANA timezone fallback for providers that omit timezone.
+ *  Ported 1:1 from launcher's Rust `country_to_timezone`. */
+function countryToTimezone(cc) {
+    return CC_TO_TZ[(cc ?? "").toUpperCase()] ?? "UTC";
+}
+const CC_TO_TZ = {
+    US: "America/New_York", CA: "America/Toronto",
+    GB: "Europe/London", UK: "Europe/London",
+    DE: "Europe/Berlin", FR: "Europe/Paris", ES: "Europe/Madrid",
+    IT: "Europe/Rome", NL: "Europe/Amsterdam", PL: "Europe/Warsaw",
+    PT: "Europe/Lisbon", RO: "Europe/Bucharest", RU: "Europe/Moscow",
+    UA: "Europe/Kyiv", TR: "Europe/Istanbul", GR: "Europe/Athens",
+    CZ: "Europe/Prague", HU: "Europe/Budapest",
+    SE: "Europe/Stockholm", FI: "Europe/Helsinki",
+    NO: "Europe/Oslo", DK: "Europe/Copenhagen",
+    CH: "Europe/Zurich", AT: "Europe/Vienna",
+    BR: "America/Sao_Paulo", AR: "America/Argentina/Buenos_Aires",
+    MX: "America/Mexico_City",
+    AU: "Australia/Sydney", NZ: "Pacific/Auckland",
+    IN: "Asia/Kolkata", ID: "Asia/Jakarta", MY: "Asia/Kuala_Lumpur",
+    SG: "Asia/Singapore", TH: "Asia/Bangkok", VN: "Asia/Ho_Chi_Minh",
+    CN: "Asia/Shanghai", HK: "Asia/Hong_Kong", TW: "Asia/Taipei",
+    JP: "Asia/Tokyo", KR: "Asia/Seoul",
+    IL: "Asia/Jerusalem", SA: "Asia/Riyadh", AE: "Asia/Dubai",
+};
+export function hasAutoFields(cfg) {
+    if (cfg["timezone"] === "auto")
+        return true;
+    const nav = cfg["navigator"];
+    if (nav && nav["language"] === "auto")
+        return true;
+    const geo = cfg["geolocation"];
+    if (geo && typeof geo === "object" && geo["mode"] === "auto")
+        return true;
+    return false;
+}
+function hostTimezone() {
+    const tz = (process.env.TZ ?? "").trim();
+    if (tz && tz.includes("/"))
+        return tz;
+    try {
+        const target = readlinkSync("/etc/localtime");
+        for (const prefix of ["/usr/share/zoneinfo/", "/var/db/timezone/zoneinfo/"]) {
+            const i = target.indexOf(prefix);
+            if (i >= 0)
+                return target.slice(i + prefix.length);
+        }
+    }
+    catch { /* not a symlink / not unix */ }
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+    }
+    catch {
+        return null;
+    }
+}
+function hostLocale() {
+    for (const v of [process.env.LANG, process.env.LC_ALL, process.env.LC_MESSAGES]) {
+        if (!v)
+            continue;
+        const stripped = v.split(".", 1)[0].replace(/_/g, "-");
+        if (stripped.includes("-"))
+            return stripped;
+    }
+    return "en-US";
+}
+/**
+ * Apply the launcher's "auto" resolution. Returns the GeoInfo that fed the
+ * resolution, or null when both proxy + direct probes failed and the host
+ * fallback was used.
+ */
+export async function resolveAutoFields(cfg, proxy) {
+    const wantTz = cfg["timezone"] === "auto";
+    const nav = cfg["navigator"];
+    const wantLang = !!(nav && nav["language"] === "auto");
+    const geoCfg = cfg["geolocation"];
+    const wantGeo = !!(geoCfg && typeof geoCfg === "object" && geoCfg["mode"] === "auto");
+    if (!wantTz && !wantLang && !wantGeo)
+        return null;
+    let geo = null;
+    if (proxy) {
+        try {
+            geo = await geoCheckVia(proxy);
+        }
+        catch {
+            geo = null;
+        }
+    }
+    if (!geo) {
+        try {
+            geo = await geoCheckVia(null);
+        }
+        catch {
+            geo = null;
+        }
+    }
+    let resolvedTz;
+    let resolvedLocale;
+    let lat;
+    let lng;
+    if (geo) {
+        // Timezone: always from API. If the provider didn't return one,
+        // fall back to the country-code table — NOT the host TZ (would
+        // leak the launcher's real zone).
+        resolvedTz = geo.timezone || countryToTimezone(geo.countryCode);
+        resolvedLocale = countryToLocale(geo.countryCode);
+        lat = geo.latitude !== 0 ? geo.latitude : null;
+        lng = geo.longitude !== 0 ? geo.longitude : null;
+    }
+    else {
+        resolvedTz = hostTimezone() ?? "UTC";
+        resolvedLocale = hostLocale();
+        lat = null;
+        lng = null;
+    }
+    if (wantTz)
+        cfg["timezone"] = resolvedTz;
+    if (wantLang) {
+        const base = resolvedLocale.split("-", 1)[0];
+        const accept = resolvedLocale === "en-US"
+            ? "en-US,en;q=0.9"
+            : `${resolvedLocale},${base};q=0.9,en-US;q=0.8,en;q=0.7`;
+        const languages = resolvedLocale === "en-US"
+            ? ["en-US", "en"]
+            : [resolvedLocale, base, "en-US", "en"];
+        const navObj = (cfg["navigator"] ??= {});
+        navObj["language"] = resolvedLocale;
+        navObj["accept_language"] = accept;
+        navObj["languages"] = languages;
+        // Always overwrite — matches launch.rs (even hardcoded values are replaced).
+        cfg["icu_locale"] = resolvedLocale;
+    }
+    if (wantGeo) {
+        if (lat !== null && lng !== null) {
+            cfg["geolocation"] = {
+                mode: "manual",
+                latitude: lat,
+                longitude: lng,
+                accuracy: 50.0,
+            };
+        }
+        else {
+            delete cfg["geolocation"];
+        }
+    }
+    return geo;
+}
+//# sourceMappingURL=autoResolve.js.map

package/dist/autoResolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoResolve.js","sourceRoot":"","sources":["../src/autoResolve.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcess } from "node:child_process";
+import { type GeoInfo } from "./geo.js";
+import { Profile } from "./profile.js";
+import type { Runtime } from "./runtime.js";
+import { type ScreenStrategy } from "./screen.js";
+export type WebRtcMode = "auto" | "block" | "tcp_only";
+/** Legacy alias retained for back-compat; prefer `ScreenStrategy`. */
+export type ScreenMode = ScreenStrategy;
+export interface LaunchOptions {
+    proxy?: string;
+    cdp?: boolean;
+    headless?: boolean;
+    extraArgs?: string[];
+    env?: Record<string, string>;
+    webrtc?: WebRtcMode;
+    webrtcPublicIp?: string;
+    /** Override the UDP-probe auto-decision. */
+    quic?: boolean;
+    /** Defaults to "cap_to_host" on macOS, "use_host" on Win/Linux. */
+    screenMode?: ScreenStrategy;
+    probeTimeoutMs?: number;
+    /** Custom user-data-dir root. Defaults to ./shardx-profiles/<id>/. */
+    userDataDir?: string;
+}
+export declare class BrowserSession {
+    readonly pid: number;
+    readonly userDataDir: string;
+    readonly cdpUrl: string | null;
+    readonly process: ChildProcess;
+    readonly proxyUdpMs: number | null;
+    readonly quicEnabled: boolean;
+    readonly webrtcMode: WebRtcMode;
+    readonly geo: GeoInfo | null;
+    private _stopped;
+    constructor(pid: number, userDataDir: string, cdpUrl: string | null, process: ChildProcess, proxyUdpMs?: number | null, quicEnabled?: boolean, webrtcMode?: WebRtcMode, geo?: GeoInfo | null);
+    stop(timeoutMs?: number): Promise<void>;
+}
+export declare class Browser {
+    private readonly runtime;
+    constructor(runtime: Runtime);
+    launch(profile: Profile, opts?: LaunchOptions): Promise<BrowserSession>;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAUA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,OAAO,EAAe,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7F,MAAM,MAAM,UAAU,GAAK,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AACzD,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAK,cAAc,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,cAAc;IAIvB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAC9B,QAAQ,CAAC,OAAO,EAAE,YAAY;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAClC,QAAQ,CAAC,WAAW,EAAE,OAAO;IAC7B,QAAQ,CAAC,UAAU,EAAE,UAAU;IAC/B,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAV9B,OAAO,CAAC,QAAQ,CAAS;gBAGd,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,YAAY,EACrB,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,WAAW,GAAE,OAAe,EAC5B,UAAU,GAAE,UAAmB,EAC/B,GAAG,GAAE,OAAO,GAAG,IAAW;IAG/B,IAAI,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAa5C;AAED,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,OAAO;IAEvC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;CAuFlF"}

package/dist/browser.js

@@ -0,0 +1,172 @@
+// Browser launch + lifecycle. Spawns the ShardX engine with the same
+// spoofing flags the desktop launcher uses, plus pre-launch:
+//
+//   • resolveAutoFields    — fill timezone/language/geolocation from a
+//     live geo lookup through the bound proxy.
+//   • applyScreenStrategy — cap to host monitor (macOS) or replace with
+//     the host monitor (Win/Linux), matching the launcher's
+//     `clamp_screen_to_real_display` / `--shardx-real-screen` switch.
+//   • probeUdp             — decide QUIC + WebRTC policy from a live
+//     SOCKS5 UDP_ASSOCIATE probe.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hasAutoFields, resolveAutoFields } from "./autoResolve.js";
+import { geoCheckVia } from "./geo.js";
+import { userDataDir } from "./profile.js";
+import { parseProxy, probeUdp, proxyToArg } from "./proxy.js";
+import { applyScreenStrategy, defaultScreenModeFor } from "./screen.js";
+export class BrowserSession {
+    pid;
+    userDataDir;
+    cdpUrl;
+    process;
+    proxyUdpMs;
+    quicEnabled;
+    webrtcMode;
+    geo;
+    _stopped = false;
+    constructor(pid, userDataDir, cdpUrl, process, proxyUdpMs = null, quicEnabled = false, webrtcMode = "auto", geo = null) {
+        this.pid = pid;
+        this.userDataDir = userDataDir;
+        this.cdpUrl = cdpUrl;
+        this.process = process;
+        this.proxyUdpMs = proxyUdpMs;
+        this.quicEnabled = quicEnabled;
+        this.webrtcMode = webrtcMode;
+        this.geo = geo;
+    }
+    async stop(timeoutMs = 5000) {
+        if (this._stopped)
+            return;
+        this._stopped = true;
+        if (!this.process.pid)
+            return;
+        try {
+            this.process.kill("SIGTERM");
+        }
+        catch { /* already gone */ }
+        const exited = await new Promise((resolve) => {
+            const t = setTimeout(() => resolve(false), timeoutMs);
+            this.process.once("exit", () => { clearTimeout(t); resolve(true); });
+        });
+        if (!exited) {
+            try {
+                this.process.kill("SIGKILL");
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+export class Browser {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async launch(profile, opts = {}) {
+        // Auto-install on first use (high-level ShardX.launch already does
+        // this; the call is here too so low-level Browser.launch users
+        // don't have to remember).
+        await this.runtime.install();
+        const parsed = opts.proxy ? parseProxy(opts.proxy) : null;
+        // ---- pre-launch: auto-resolve, screen strategy, UDP probe ------
+        let geo = null;
+        if (hasAutoFields(profile.config)) {
+            geo = await resolveAutoFields(profile.config, parsed);
+        }
+        const mode = opts.screenMode ?? defaultScreenModeFor(profile.platform);
+        applyScreenStrategy(profile.config, mode);
+        let proxyUdpMs = null;
+        if (parsed && parsed.scheme === "socks5") {
+            proxyUdpMs = await probeUdp(parsed, opts.probeTimeoutMs ?? 6000);
+        }
+        const udpOk = proxyUdpMs !== null;
+        const quicEnabled = opts.quic ?? (parsed !== null && udpOk);
+        let webrtcMode = opts.webrtc ?? "auto";
+        if (webrtcMode === "auto" && parsed !== null && !udpOk)
+            webrtcMode = "tcp_only";
+        // ---- profile + udd ----------------------------------------------
+        const udd = userDataDir(this.runtime, profile.id, opts.userDataDir);
+        console.log(`[shardx] profile '${profile.id}' → ${udd}`);
+        const fpFile = join(udd, "fingerprint.json");
+        writeFileSync(fpFile, JSON.stringify(profile.config));
+        const argv = [
+            `--fingerprint-profile=${fpFile}`,
+            `--user-data-dir=${udd}`,
+            "--no-first-run",
+        ];
+        if (!profile.hasWebGPU)
+            argv.push("--disable-features=WebGPU");
+        if (!opts.headless && !opts.cdp) {
+            argv.push("--restore-last-session", "--hide-crash-restore-bubble");
+        }
+        // Engine-side real-screen switch only fires on use_host (where the SDK
+        // already rewrote screen.* — keep them in sync with the launcher).
+        if (mode === "use_host")
+            argv.push("--shardx-real-screen");
+        if (parsed) {
+            argv.push(`--proxy-server=${proxyToArg(parsed)}`);
+            argv.push(quicEnabled ? "--enable-quic" : "--disable-quic");
+        }
+        if (webrtcMode === "block") {
+            argv.push("--force-webrtc-ip-handling-policy=disable_non_proxied_udp", "--shardx-webrtc-policy=block");
+        }
+        else if (webrtcMode === "tcp_only") {
+            argv.push("--force-webrtc-ip-handling-policy=disable_non_proxied_udp", "--shardx-webrtc-policy=tcp_only");
+            // Engine spoofs the public side of ICE candidates with this IP.
+            // Match the launcher: ALWAYS resolve when proxy is bound — relying
+            // on `geo` from auto-resolve only works when the profile has auto
+            // sentinels, otherwise the engine falls back to the host IP.
+            let ip = opts.webrtcPublicIp ?? geo?.ip;
+            if (!ip && parsed) {
+                try {
+                    ip = (await geoCheckVia(parsed)).ip || undefined;
+                }
+                catch { /* leave undefined */ }
+            }
+            if (ip)
+                argv.push(`--shardx-webrtc-public-ip=${ip}`);
+        }
+        const cdpMarker = join(udd, "DevToolsActivePort");
+        if (opts.cdp) {
+            if (existsSync(cdpMarker))
+                rmSync(cdpMarker, { force: true });
+            argv.push("--remote-debugging-port=0", "--remote-allow-origins=*");
+        }
+        if (opts.headless)
+            argv.push("--headless=new");
+        if (opts.extraArgs)
+            argv.push(...opts.extraArgs);
+        const child = spawn(this.runtime.binaryPath, argv, {
+            env: { ...process.env, ...(opts.env ?? {}) },
+            stdio: "ignore",
+            detached: process.platform !== "win32",
+        });
+        const cdpUrl = opts.cdp ? await readCdpEndpoint(udd, 15_000) : null;
+        return new BrowserSession(child.pid, udd, cdpUrl, child, proxyUdpMs, quicEnabled, webrtcMode, geo);
+    }
+}
+async function readCdpEndpoint(udd, timeoutMs) {
+    const marker = join(udd, "DevToolsActivePort");
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(marker)) {
+            try {
+                const firstLine = readFileSync(marker, "utf8").split("\n")[0].trim();
+                const port = parseInt(firstLine, 10);
+                if (!Number.isNaN(port)) {
+                    const r = await fetch(`http://127.0.0.1:${port}/json/version`);
+                    if (r.ok) {
+                        const data = await r.json();
+                        if (data.webSocketDebuggerUrl)
+                            return data.webSocketDebuggerUrl;
+                    }
+                }
+            }
+            catch { /* keep polling */ }
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return null;
+}
+//# sourceMappingURL=browser.js.map