@floegence/flowersec-core 0.7.0 → 0.8.0

package/dist/proxy/index.d.ts

@@ -3,5 +3,6 @@ export * from "./types.js";
 export * from "./cookieJar.js";
 export * from "./runtime.js";
 export * from "./serviceWorker.js";
+export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
 export * from "./wsPatch.js";
 export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/index.js

@@ -3,5 +3,6 @@ export * from "./types.js";
 export * from "./cookieJar.js";
 export * from "./runtime.js";
 export * from "./serviceWorker.js";
+export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
 export * from "./wsPatch.js";
 export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/registerServiceWorker.d.ts

@@ -0,0 +1,17 @@
+export type RegisterServiceWorkerOptions = Readonly<{
+    scriptUrl: string;
+    scope?: string;
+    repairQueryKey?: string;
+    maxRepairAttempts?: number;
+    controllerTimeoutMs?: number;
+}>;
+declare function parseRepairAttemptFromHref(href: string, queryKey: string): number;
+declare function buildHrefWithRepairAttempt(href: string, queryKey: string, attempt: number): string;
+declare function buildHrefWithoutRepairQueryParam(href: string, queryKey: string): string;
+export declare function registerServiceWorkerAndEnsureControl(opts: RegisterServiceWorkerOptions): Promise<void>;
+export declare const __testOnly: {
+    parseRepairAttemptFromHref: typeof parseRepairAttemptFromHref;
+    buildHrefWithRepairAttempt: typeof buildHrefWithRepairAttempt;
+    buildHrefWithoutRepairQueryParam: typeof buildHrefWithoutRepairQueryParam;
+};
+export {};

package/dist/proxy/registerServiceWorker.js

@@ -0,0 +1,116 @@
+function parseRepairAttemptFromHref(href, queryKey) {
+    try {
+        const u = new URL(href);
+        const raw = String(u.searchParams.get(queryKey) ?? "").trim();
+        const n = raw ? Number(raw) : 0;
+        if (!Number.isFinite(n) || n < 0)
+            return 0;
+        return Math.min(9, Math.floor(n));
+    }
+    catch {
+        return 0;
+    }
+}
+function buildHrefWithRepairAttempt(href, queryKey, attempt) {
+    const u = new URL(href);
+    u.searchParams.set(queryKey, String(Math.max(0, Math.floor(attempt))));
+    return u.toString();
+}
+function buildHrefWithoutRepairQueryParam(href, queryKey) {
+    const u = new URL(href);
+    u.searchParams.delete(queryKey);
+    const search = u.searchParams.toString();
+    return u.pathname + (search ? `?${search}` : "") + u.hash;
+}
+function waitForController(timeoutMs) {
+    if (navigator.serviceWorker.controller)
+        return Promise.resolve(true);
+    const ms = Math.max(0, Math.floor(timeoutMs));
+    return new Promise((resolve) => {
+        let done = false;
+        let t = null;
+        function finish(ok) {
+            if (done)
+                return;
+            done = true;
+            if (t != null)
+                window.clearTimeout(t);
+            navigator.serviceWorker.removeEventListener("controllerchange", onChange);
+            resolve(ok);
+        }
+        function onChange() {
+            finish(true);
+        }
+        navigator.serviceWorker.addEventListener("controllerchange", onChange);
+        // Avoid race: controller can become available before/after the listener registration.
+        if (navigator.serviceWorker.controller) {
+            finish(true);
+            return;
+        }
+        if (ms > 0) {
+            t = window.setTimeout(() => finish(Boolean(navigator.serviceWorker.controller)), ms);
+        }
+    });
+}
+// registerServiceWorkerAndEnsureControl registers a Service Worker and ensures the current page load is controlled.
+//
+// In DevTools hard reload flows, the SW may be installed but not control the current page load.
+// When this happens, we perform a limited "soft navigation" repair to recover control.
+export async function registerServiceWorkerAndEnsureControl(opts) {
+    const scriptUrl = String(opts.scriptUrl ?? "").trim();
+    if (!scriptUrl)
+        throw new Error("scriptUrl is required");
+    if (globalThis.navigator?.serviceWorker == null) {
+        throw new Error("service worker is not available in this environment");
+    }
+    const scope = String(opts.scope ?? "/").trim() || "/";
+    const queryKey = String(opts.repairQueryKey ?? "_flowersec_sw_repair").trim() || "_flowersec_sw_repair";
+    const maxRepairAttempts = Math.max(0, Math.floor(opts.maxRepairAttempts ?? 2));
+    const controllerTimeoutMs = Math.max(0, Math.floor(opts.controllerTimeoutMs ?? 2_000));
+    await navigator.serviceWorker.register(scriptUrl, { scope });
+    await navigator.serviceWorker.ready;
+    const attempt = parseRepairAttemptFromHref(window.location.href, queryKey);
+    if (navigator.serviceWorker.controller) {
+        if (attempt > 0) {
+            try {
+                const next = buildHrefWithoutRepairQueryParam(window.location.href, queryKey);
+                history.replaceState(null, document.title, next);
+            }
+            catch {
+                // ignore
+            }
+        }
+        return;
+    }
+    const controlled = await waitForController(controllerTimeoutMs);
+    if (controlled) {
+        if (attempt > 0) {
+            try {
+                const next = buildHrefWithoutRepairQueryParam(window.location.href, queryKey);
+                history.replaceState(null, document.title, next);
+            }
+            catch {
+                // ignore
+            }
+        }
+        return;
+    }
+    if (attempt < maxRepairAttempts) {
+        try {
+            const next = buildHrefWithRepairAttempt(window.location.href, queryKey, attempt + 1);
+            window.location.replace(next);
+        }
+        catch {
+            window.location.reload();
+        }
+        // Navigation will interrupt JS; keep pending so callers don't proceed with dependent work.
+        await new Promise(() => { });
+    }
+    throw new Error("Service Worker is installed but not controlling this page");
+}
+// Test-only exports (not re-exported from the public proxy entrypoint).
+export const __testOnly = {
+    parseRepairAttemptFromHref,
+    buildHrefWithRepairAttempt,
+    buildHrefWithoutRepairQueryParam,
+};

package/dist/proxy/serviceWorker.d.ts

@@ -1,9 +1,32 @@
+export type ProxyServiceWorkerPassthroughOptions = Readonly<{
+    paths?: readonly string[];
+    prefixes?: readonly string[];
+}>;
+export type ProxyServiceWorkerInjectHTMLInlineModule = Readonly<{
+    mode?: "inline_module";
+    proxyModuleUrl: string;
+    runtimeGlobal?: string;
+}>;
+export type ProxyServiceWorkerInjectHTMLExternalScript = Readonly<{
+    mode: "external_script";
+    scriptUrl: string;
+    runtimeGlobal?: string;
+}>;
+export type ProxyServiceWorkerInjectHTMLExternalModule = Readonly<{
+    mode: "external_module";
+    scriptUrl: string;
+    runtimeGlobal?: string;
+}>;
+export type ProxyServiceWorkerInjectHTMLOptions = (ProxyServiceWorkerInjectHTMLInlineModule | ProxyServiceWorkerInjectHTMLExternalScript | ProxyServiceWorkerInjectHTMLExternalModule) & Readonly<{
+    excludePathPrefixes?: readonly string[];
+    stripValidatorHeaders?: boolean;
+    setNoStore?: boolean;
+}>;
 export type ProxyServiceWorkerScriptOptions = Readonly<{
+    sameOriginOnly?: boolean;
+    passthrough?: ProxyServiceWorkerPassthroughOptions;
     proxyPathPrefix?: string;
     stripProxyPathPrefix?: boolean;
-    injectHTML?: Readonly<{
-        proxyModuleUrl: string;
-        runtimeGlobal?: string;
-    }>;
+    injectHTML?: ProxyServiceWorkerInjectHTMLOptions;
 }>;
 export declare function createProxyServiceWorkerScript(opts?: ProxyServiceWorkerScriptOptions): string;

package/dist/proxy/serviceWorker.js

@@ -1,25 +1,103 @@
+function normalizePathPrefix(name, v) {
+    const s = typeof v === "string" ? v.trim() : "";
+    if (s === "")
+        return "";
+    if (!s.startsWith("/"))
+        throw new Error(`${name} must start with "/"`);
+    if (s.startsWith("//"))
+        throw new Error(`${name} must not start with "//"`);
+    if (/[ \t\r\n]/.test(s))
+        throw new Error(`${name} must not contain whitespace`);
+    if (s.includes("://"))
+        throw new Error(`${name} must not include scheme/host`);
+    return s;
+}
+function normalizePathList(name, input) {
+    const out = [];
+    if (input == null || input.length === 0)
+        return out;
+    for (const raw of input) {
+        const s = normalizePathPrefix(name, raw);
+        if (s === "")
+            continue;
+        out.push(s);
+    }
+    return Array.from(new Set(out));
+}
 // createProxyServiceWorkerScript returns a Service Worker script that forwards fetches to a runtime
 // in a controlled window via postMessage + MessageChannel.
 //
 // The runtime side is implemented by createProxyRuntime(...) in this package.
 export function createProxyServiceWorkerScript(opts = {}) {
-    const proxyPathPrefix = opts.proxyPathPrefix ?? "";
+    const sameOriginOnly = opts.sameOriginOnly ?? true;
+    if (typeof sameOriginOnly !== "boolean") {
+        throw new Error("sameOriginOnly must be a boolean");
+    }
+    const proxyPathPrefix = normalizePathPrefix("proxyPathPrefix", opts.proxyPathPrefix);
     const stripProxyPathPrefix = opts.stripProxyPathPrefix ?? false;
-    const injectHTML = opts.injectHTML ?? null;
-    const proxyModuleUrl = injectHTML?.proxyModuleUrl?.trim() ?? "";
-    const runtimeGlobal = injectHTML?.runtimeGlobal?.trim() ?? "__flowersecProxyRuntime";
-    if (injectHTML != null && proxyModuleUrl === "") {
-        throw new Error("injectHTML.proxyModuleUrl must be non-empty");
+    if (typeof stripProxyPathPrefix !== "boolean") {
+        throw new Error("stripProxyPathPrefix must be a boolean");
     }
+    const passthroughPaths = normalizePathList("passthrough.paths", opts.passthrough?.paths);
+    const passthroughPrefixes = normalizePathList("passthrough.prefixes", opts.passthrough?.prefixes);
+    const injectHTML = opts.injectHTML ?? null;
+    // Injection mode defaults to inline_module when injectHTML is provided.
+    const injectMode = injectHTML?.mode ?? "inline_module";
+    const runtimeGlobal = injectHTML != null ? (injectHTML.runtimeGlobal?.trim() ?? "__flowersecProxyRuntime") : "__flowersecProxyRuntime";
     if (injectHTML != null && runtimeGlobal === "") {
         throw new Error("injectHTML.runtimeGlobal must be non-empty");
     }
+    const excludeInjectPrefixes = normalizePathList("injectHTML.excludePathPrefixes", injectHTML?.excludePathPrefixes);
+    const stripValidatorHeaders = injectHTML?.stripValidatorHeaders ?? true;
+    if (typeof stripValidatorHeaders !== "boolean") {
+        throw new Error("injectHTML.stripValidatorHeaders must be a boolean");
+    }
+    const setNoStore = injectHTML?.setNoStore ?? true;
+    if (typeof setNoStore !== "boolean") {
+        throw new Error("injectHTML.setNoStore must be a boolean");
+    }
+    let proxyModuleUrl = "";
+    let injectScriptUrl = "";
+    if (injectHTML != null) {
+        if (injectMode === "inline_module") {
+            // Note: union type guarantees proxyModuleUrl exists, but keep a runtime check for JS callers.
+            proxyModuleUrl =
+                "proxyModuleUrl" in injectHTML && typeof injectHTML.proxyModuleUrl === "string"
+                    ? injectHTML.proxyModuleUrl.trim()
+                    : "";
+            if (proxyModuleUrl === "") {
+                throw new Error("injectHTML.proxyModuleUrl must be non-empty");
+            }
+        }
+        else {
+            injectScriptUrl =
+                "scriptUrl" in injectHTML && typeof injectHTML.scriptUrl === "string"
+                    ? injectHTML.scriptUrl.trim()
+                    : "";
+            if (injectScriptUrl === "") {
+                throw new Error("injectHTML.scriptUrl must be non-empty");
+            }
+        }
+    }
     return `// Generated by @floegence/flowersec-core/proxy
+const SAME_ORIGIN_ONLY = ${JSON.stringify(sameOriginOnly)};
 const PROXY_PATH_PREFIX = ${JSON.stringify(proxyPathPrefix)};
 const STRIP_PROXY_PATH_PREFIX = ${JSON.stringify(stripProxyPathPrefix)};
+
+const PASSTHROUGH_PATHS = new Set(${JSON.stringify(passthroughPaths)});
+const PASSTHROUGH_PREFIXES = ${JSON.stringify(passthroughPrefixes)};
+
 const INJECT_HTML = ${JSON.stringify(injectHTML != null)};
+const INJECT_MODE = ${JSON.stringify(injectMode)};
 const PROXY_MODULE_URL = ${JSON.stringify(proxyModuleUrl)};
+const INJECT_SCRIPT_URL = ${JSON.stringify(injectScriptUrl)};
 const RUNTIME_GLOBAL = ${JSON.stringify(runtimeGlobal)};
+const INJECT_EXCLUDE_PREFIXES = ${JSON.stringify(excludeInjectPrefixes)};
+const INJECT_STRIP_VALIDATOR_HEADERS = ${JSON.stringify(stripValidatorHeaders)};
+const INJECT_SET_NO_STORE = ${JSON.stringify(setNoStore)};
+
+const INJECT_STRIP_HEADER_NAMES = new Set(["content-length", "etag", "last-modified", "content-md5"]);
+
 let runtimeClientId = null;
 
 self.addEventListener("install", () => {
@@ -52,6 +130,21 @@ async function getRuntimeClient() {
   return null;
 }
 
+function shouldPassthrough(pathname) {
+  if (PASSTHROUGH_PATHS.has(pathname)) return true;
+  for (const p of PASSTHROUGH_PREFIXES) {
+    if (pathname.startsWith(p)) return true;
+  }
+  return false;
+}
+
+function shouldSkipInject(pathname) {
+  for (const p of INJECT_EXCLUDE_PREFIXES) {
+    if (pathname.startsWith(p)) return true;
+  }
+  return false;
+}
+
 function headersToPairs(headers) {
   const out = [];
   headers.forEach((value, name) => out.push({ name, value }));
@@ -71,12 +164,31 @@ function concatChunks(chunks) {
 }
 
 function injectBootstrap(html) {
-  const snippet =
-    '<script type="module">' +
-    'import { installWebSocketPatch, disableUpstreamServiceWorkerRegister } from ' + JSON.stringify(PROXY_MODULE_URL) + ';' +
-    'const rt = window.top && window.top[' + JSON.stringify(RUNTIME_GLOBAL) + '];' +
-    'if (rt) { disableUpstreamServiceWorkerRegister(); installWebSocketPatch({ runtime: rt }); }' +
-    '</script>';
+  let snippet = "";
+
+  if (INJECT_MODE === "inline_module") {
+    snippet =
+      '<script type="module">' +
+      'import { installWebSocketPatch, disableUpstreamServiceWorkerRegister } from ' + JSON.stringify(PROXY_MODULE_URL) + ';' +
+      'const rt = window.top && window.top[' + JSON.stringify(RUNTIME_GLOBAL) + '];' +
+      'if (rt) { disableUpstreamServiceWorkerRegister(); installWebSocketPatch({ runtime: rt }); }' +
+      '</script>';
+  } else if (INJECT_MODE === "external_module") {
+    snippet =
+      '<script type="module" src="' +
+      INJECT_SCRIPT_URL +
+      '"' +
+      (RUNTIME_GLOBAL ? ' data-flowersec-runtime-global="' + RUNTIME_GLOBAL + '"' : "") +
+      "></script>";
+  } else if (INJECT_MODE === "external_script") {
+    snippet =
+      '<script src="' +
+      INJECT_SCRIPT_URL +
+      '"' +
+      (RUNTIME_GLOBAL ? ' data-flowersec-runtime-global="' + RUNTIME_GLOBAL + '"' : "") +
+      "></script>";
+  }
+
   const lower = html.toLowerCase();
   const idx = lower.indexOf("<head");
   if (idx >= 0) {
@@ -88,7 +200,13 @@ function injectBootstrap(html) {
 
 self.addEventListener("fetch", (event) => {
   const url = new URL(event.request.url);
+
+  // Only proxy same-origin requests by default. The runtime proxy protocol forwards path+query only.
+  if (SAME_ORIGIN_ONLY && url.origin !== self.location.origin) return;
+
   if (PROXY_PATH_PREFIX && !url.pathname.startsWith(PROXY_PATH_PREFIX)) return;
+  if (shouldPassthrough(url.pathname)) return;
+
   event.respondWith(handleFetch(event));
 });
 
@@ -112,6 +230,7 @@ async function handleFetch(event) {
   const queued = [];
   const htmlChunks = [];
   let shouldInjectHTML = false;
+  const injectAllowed = INJECT_HTML && !shouldSkipInject(url.pathname);
 
   let doneResolve;
   let doneReject;
@@ -131,7 +250,7 @@ async function handleFetch(event) {
     const m = ev.data;
     if (!m || typeof m.type !== "string") return;
     if (m.type === "flowersec-proxy:response_meta") {
-      if (INJECT_HTML) {
+      if (injectAllowed) {
         const ct = String((m.headers || []).find((h) => (h.name || "").toLowerCase() === "content-type")?.value || "");
         shouldInjectHTML = ct.toLowerCase().includes("text/html");
       }
@@ -182,7 +301,17 @@ async function handleFetch(event) {
 
   const meta = await metaPromise;
   const headers = new Headers();
-  for (const h of (meta.headers || [])) headers.append(h.name, h.value);
+  for (const h of (meta.headers || [])) {
+    const name = String(h.name || "");
+    const lower = name.toLowerCase();
+    if (shouldInjectHTML && INJECT_STRIP_VALIDATOR_HEADERS && INJECT_STRIP_HEADER_NAMES.has(lower)) continue;
+    headers.append(name, String(h.value || ""));
+  }
+
+  if (shouldInjectHTML && INJECT_SET_NO_STORE && !headers.has("Cache-Control")) {
+    headers.set("Cache-Control", "no-store");
+  }
+
   if (shouldInjectHTML) {
     const chunks = await donePromise;
     const raw = concatChunks(chunks);

package/dist/reconnect/index.d.ts

@@ -0,0 +1,33 @@
+import type { Client } from "../client.js";
+import type { ClientObserverLike } from "../observability/observer.js";
+export type ConnectionStatus = "disconnected" | "connecting" | "connected" | "error";
+export type AutoReconnectConfig = Readonly<{
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+    jitterRatio?: number;
+}>;
+export type ReconnectState = Readonly<{
+    status: ConnectionStatus;
+    error: Error | null;
+    client: Client | null;
+}>;
+export type ReconnectListener = (state: ReconnectState) => void;
+export type ConnectOnce = (args: Readonly<{
+    signal: AbortSignal;
+    observer: ClientObserverLike;
+}>) => Promise<Client>;
+export type ConnectConfig = Readonly<{
+    connectOnce: ConnectOnce;
+    observer?: ClientObserverLike;
+    autoReconnect?: AutoReconnectConfig;
+}>;
+export type ReconnectManager = Readonly<{
+    state: () => ReconnectState;
+    subscribe: (listener: ReconnectListener) => () => void;
+    connect: (config: ConnectConfig) => Promise<void>;
+    disconnect: () => void;
+}>;
+export declare function createReconnectManager(): ReconnectManager;

package/dist/reconnect/index.js

@@ -0,0 +1,235 @@
+function normalizeAutoReconnect(cfg) {
+    if (!cfg?.enabled) {
+        return {
+            enabled: false,
+            maxAttempts: 1,
+            initialDelayMs: 500,
+            maxDelayMs: 10_000,
+            factor: 1.8,
+            jitterRatio: 0.2,
+        };
+    }
+    return {
+        enabled: true,
+        maxAttempts: Math.max(1, cfg.maxAttempts ?? 5),
+        initialDelayMs: Math.max(0, cfg.initialDelayMs ?? 500),
+        maxDelayMs: Math.max(0, cfg.maxDelayMs ?? 10_000),
+        factor: Math.max(1, cfg.factor ?? 1.8),
+        jitterRatio: Math.max(0, cfg.jitterRatio ?? 0.2),
+    };
+}
+function backoffDelayMs(attemptIndex, cfg) {
+    const base = Math.min(cfg.maxDelayMs, cfg.initialDelayMs * Math.pow(cfg.factor, attemptIndex));
+    const jitter = cfg.jitterRatio <= 0 ? 0 : base * cfg.jitterRatio * (Math.random() * 2 - 1);
+    return Math.max(0, Math.round(base + jitter));
+}
+export function createReconnectManager() {
+    let s = { status: "disconnected", error: null, client: null };
+    const listeners = new Set();
+    const setState = (next) => {
+        s = next;
+        for (const fn of listeners) {
+            try {
+                fn(s);
+            }
+            catch {
+                // ignore listener errors
+            }
+        }
+    };
+    let token = 0;
+    let active = null;
+    let retryTimer = null;
+    let retryResolve = null;
+    let attemptAbort = null;
+    const cancelRetrySleep = () => {
+        if (retryTimer) {
+            clearTimeout(retryTimer);
+            retryTimer = null;
+        }
+        retryResolve?.();
+        retryResolve = null;
+    };
+    const abortActiveAttempt = () => {
+        try {
+            attemptAbort?.abort("canceled");
+        }
+        catch {
+            // ignore
+        }
+        attemptAbort = null;
+    };
+    const sleep = (ms) => new Promise((resolve) => {
+        retryResolve = resolve;
+        retryTimer = setTimeout(() => {
+            retryTimer = null;
+            retryResolve = null;
+            resolve();
+        }, ms);
+    });
+    const disconnectInternal = () => {
+        cancelRetrySleep();
+        abortActiveAttempt();
+        active = null;
+        token += 1;
+        if (s.client) {
+            try {
+                s.client.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        setState({ status: "disconnected", error: null, client: null });
+    };
+    const startReconnect = (t, cfg, error) => {
+        if (t !== token)
+            return;
+        if (active !== cfg)
+            return;
+        if (s.status !== "connected")
+            return;
+        const ar = normalizeAutoReconnect(cfg.autoReconnect);
+        if (!ar.enabled) {
+            if (s.client) {
+                try {
+                    s.client.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            setState({ status: "error", error, client: null });
+            return;
+        }
+        // Restart the connection loop in the background.
+        cancelRetrySleep();
+        abortActiveAttempt();
+        if (s.client) {
+            try {
+                s.client.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        token += 1;
+        const nextToken = token;
+        setState({ status: "connecting", error, client: null });
+        void connectWithRetry(nextToken, cfg).catch(() => {
+            // connectWithRetry updates state; keep errors observable via state().
+        });
+    };
+    const createObserver = (t, cfg) => {
+        const user = cfg.observer;
+        return {
+            onConnect: (...args) => user?.onConnect?.(...args),
+            onAttach: (...args) => user?.onAttach?.(...args),
+            onHandshake: (...args) => user?.onHandshake?.(...args),
+            onWsClose: (kind, code) => {
+                user?.onWsClose?.(kind, code);
+                if (kind === "peer_or_error") {
+                    startReconnect(t, cfg, new Error(`WebSocket closed (${code ?? "unknown"})`));
+                }
+            },
+            onWsError: (reason) => {
+                user?.onWsError?.(reason);
+                startReconnect(t, cfg, new Error(`WebSocket error: ${reason}`));
+            },
+            onRpcCall: (...args) => user?.onRpcCall?.(...args),
+            onRpcNotify: (...args) => user?.onRpcNotify?.(...args),
+        };
+    };
+    const connectOnce = async (t, cfg) => {
+        abortActiveAttempt();
+        attemptAbort = new AbortController();
+        return await cfg.connectOnce({ signal: attemptAbort.signal, observer: createObserver(t, cfg) ?? {} });
+    };
+    const connectWithRetry = async (t, cfg) => {
+        const ar = normalizeAutoReconnect(cfg.autoReconnect);
+        let attempts = 0;
+        for (;;) {
+            if (t !== token)
+                return;
+            if (active !== cfg)
+                return;
+            attempts += 1;
+            try {
+                const client = await connectOnce(t, cfg);
+                if (t !== token) {
+                    try {
+                        client.close();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    return;
+                }
+                if (active !== cfg) {
+                    try {
+                        client.close();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    return;
+                }
+                setState({ status: "connected", client, error: null });
+                return;
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                if (t !== token)
+                    return;
+                if (active !== cfg)
+                    return;
+                const canRetry = ar.enabled && attempts < ar.maxAttempts;
+                if (!canRetry) {
+                    setState({ status: "error", error: e, client: null });
+                    throw e;
+                }
+                setState({ status: "connecting", error: e, client: null });
+                const delay = backoffDelayMs(attempts - 1, ar);
+                await sleep(delay);
+            }
+        }
+    };
+    const connect = async (cfg) => {
+        cancelRetrySleep();
+        abortActiveAttempt();
+        token += 1;
+        const t = token;
+        active = cfg;
+        if (s.client) {
+            try {
+                s.client.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        setState({ status: "connecting", error: null, client: null });
+        await connectWithRetry(t, cfg);
+    };
+    const disconnect = () => {
+        disconnectInternal();
+    };
+    return {
+        state: () => s,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            // Push the current state immediately for convenience.
+            try {
+                listener(s);
+            }
+            catch {
+                // ignore
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        connect,
+        disconnect,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,10 @@
       "types": "./dist/proxy/index.d.ts",
       "default": "./dist/proxy/index.js"
     },
+    "./reconnect": {
+      "types": "./dist/reconnect/index.d.ts",
+      "default": "./dist/reconnect/index.js"
+    },
     "./rpc": {
       "types": "./dist/rpc/index.d.ts",
       "default": "./dist/rpc/index.js"