react-native-webview-stream-chunks 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# react-native-webview-stream-chunks
+
+Stream large payloads into a React Native WebView by chunking, inject them as `<script>` tags, and optionally re-execute scripts — through a high-level sender API.
+
+## Features
+
+- High-level sender (`WebViewStreamSender`) instead of manual low-level events.
+- Per-injection script options on `finalizePayload(options)`.
+- Supports injecting multiple different script tags in one session.
+- Optional script re-execution (`all` via default selector, or specific selector).
+
+## Install
+
+```bash
+npm install react-native-webview-stream-chunks
+# or
+pnpm add react-native-webview-stream-chunks
+```
+
+## Quick Start
+
+### 1) Generate the preload script (receiver side)
+
+```ts
+import { getWebViewStreamChunksPreloadScript } from 'react-native-webview-stream-chunks';
+
+const preloadScript = getWebViewStreamChunksPreloadScript({
+  receiverReadyCallbackPath: 'myApp.onReady', // Optional
+});
+```
+
+Inject `preloadScript` into your WebView (for example with `injectedJavaScript`).
+
+### 2) Send data from React Native (sender side)
+
+```ts
+import { WebViewStreamSender } from 'react-native-webview-stream-chunks';
+
+const sender = new WebViewStreamSender((type, data) => {
+  const message = JSON.stringify({ type, data });
+  webViewRef.current?.injectJavaScript(`window.onStreamChunksToWebView(${message});`);
+});
+
+sender.checkReceiverReady();
+sender.setContent(skeletonHtml);
+
+for (const chunk of chunks) {
+  sender.appendChunk(chunk);
+}
+
+sender.finalizePayload({
+  scriptType: 'application/json',
+  scriptClassName: 'my-payload-store',
+  scriptTagName: 'main-store',
+  anchorSelector: '#styleArea',
+});
+
+sender.reexecuteScripts();
+// sender.reexecuteScripts('script[data-boot]');
+```
+
+### 3) Inject multiple script tags
+
+```ts
+// First payload
+for (const chunk of firstChunks) sender.appendChunk(chunk);
+sender.finalizePayload({
+  scriptType: 'application/json',
+  scriptClassName: 'store-a',
+  scriptTagName: 'users',
+  anchorSelector: '#styleArea',
+});
+
+// Second payload
+for (const chunk of secondChunks) sender.appendChunk(chunk);
+sender.finalizePayload({
+  scriptType: 'text/javascript',
+  scriptClassName: 'boot-script',
+  scriptTagName: 'runtime',
+  anchorSelector: '#styleArea',
+});
+```
+
+## API
+
+### `WebViewStreamSender`
+
+| Method                        | Description                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `checkReceiverReady()`        | Ping receiver and trigger its configured ready callback path.           |
+| `setContent(html)`            | Replace `document.body.innerHTML` and reset buffered chunks.            |
+| `appendChunk(chunk)`          | Append one payload chunk to the receiver buffer.                        |
+| `finalizePayload(options?)`   | Join buffered chunks and inject one `<script>` with per-call options.   |
+| `reexecuteScripts(selector?)` | Re-execute matching script tags by clone-replace. Defaults to `script`. |
+
+### `finalizePayload(options)`
+
+| Option            | Default                  | Description                                                                     |
+| ----------------- | ------------------------ | ------------------------------------------------------------------------------- |
+| `scriptType`      | `application/json`       | `type` attribute of injected `<script>`.                                        |
+| `scriptClassName` | `webview-stream-payload` | Class used for this payload script (also used to exclude it from re-execution). |
+| `scriptTagName`   | `default-payload`        | Extra class/name tag for easier identification.                                 |
+| `anchorSelector`  | `#styleArea`             | Inject payload script after this element.                                       |
+
+### Preload options
+
+| Option                      | Default | Description                                                        |
+| --------------------------- | ------- | ------------------------------------------------------------------ |
+| `receiverReadyCallbackPath` | `''`    | (Optional) Dot-path on `window` invoked by `checkReceiverReady()`. |

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { WebViewStreamSender } from './sender';
+export type { WebViewStreamTransport } from './sender';
+export { createWebViewStreamChunksPreloadScript, getWebViewStreamChunksPreloadScript } from './streamChunksPreloadScript';
+export type { PayloadScriptInjectionOptions, WebViewStreamPreloadScriptOptions } from './streamChunksPreloadScript';
+export { WebViewStreamEventTypes } from './streamChunksPreloadScript';
+export type { WebViewStreamEventType, WebViewStreamReceiverEvent } from './streamChunksPreloadScript';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGvD,OAAO,EAAE,sCAAsC,EAAE,mCAAmC,EAAE,MAAM,6BAA6B,CAAC;AAC1H,YAAY,EAAE,6BAA6B,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAGpH,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,YAAY,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// High-level API (preferred)
+export { WebViewStreamSender } from './sender';
+// Preload script generators
+export { createWebViewStreamChunksPreloadScript, getWebViewStreamChunksPreloadScript } from './streamChunksPreloadScript';
+// Low-level event protocol (advanced usage)
+export { WebViewStreamEventTypes } from './streamChunksPreloadScript';

package/dist/sender.d.ts

@@ -0,0 +1,64 @@
+import { type PayloadScriptInjectionOptions, type WebViewStreamEventType } from './streamChunksPreloadScript';
+/**
+ * Transport function that delivers a message to the WebView.
+ * The user is responsible for implementing the actual delivery mechanism
+ * (e.g. `webViewRef.current.injectJavaScript()`).
+ */
+export type WebViewStreamTransport = (eventType: WebViewStreamEventType, data?: string) => void;
+/**
+ * High-level API for streaming content into a WebView.
+ *
+ * Wraps the low-level event protocol so callers never need to deal with
+ * event type constants, message serialisation, or sequencing concerns.
+ *
+ * @example
+ * ```ts
+ * const sender = new WebViewStreamSender((type, data) => {
+ *   webViewRef.current.injectJavaScript(
+ *     `window.onStreamChunksToWebView(${JSON.stringify({ type, data })});`
+ *   );
+ * });
+ *
+ * sender.checkReceiverReady();
+ * sender.setContent(html);
+ * sender.appendChunk(chunk);
+ * sender.finalizePayload();
+ * sender.reexecuteScripts();
+ * ```
+ */
+export declare class WebViewStreamSender {
+    private readonly transport;
+    constructor(transport: WebViewStreamTransport);
+    /**
+     * Ask the receiver whether it is ready. The receiver will invoke its
+     * configured `receiverReadyCallbackPath` when it handles this event.
+     */
+    checkReceiverReady(): void;
+    /**
+     * Replace the WebView's `document.body.innerHTML` with the provided HTML.
+     * This also resets any previously buffered chunks.
+     */
+    setContent(html: string): void;
+    /**
+     * Buffer a chunk in the receiver. Call this as many times as needed.
+     */
+    appendChunk(chunk: string): void;
+    /**
+     * Join all buffered chunks and inject them as a single `<script>` tag
+     * into the DOM.
+     *
+     * This does NOT re-execute existing scripts — call `reexecuteScripts()`
+     * separately when needed.
+     */
+    finalizePayload(options?: PayloadScriptInjectionOptions): void;
+    /**
+     * Re-execute `<script>` tags in the DOM by replacing them with clones.
+     *
+     * @param selector - optional CSS selector to limit which scripts are
+     *   re-executed. Defaults to `'script'` (all scripts).
+     *   The payload `<script>` injected by `finalizePayload()` is always
+     *   excluded automatically.
+     */
+    reexecuteScripts(selector?: string): void;
+}
+//# sourceMappingURL=sender.d.ts.map

package/dist/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../src/sender.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,6BAA6B,EAAE,KAAK,sBAAsB,EAA2B,MAAM,6BAA6B,CAAC;AAEvI;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,sBAAsB,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEvC,SAAS,EAAE,sBAAsB;IAI7C;;;OAGG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,6BAA6B,GAAG,IAAI;IAI9D;;;;;;;OAOG;IACH,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;CAG1C"}

package/dist/sender.js

@@ -0,0 +1,68 @@
+import { WebViewStreamEventTypes } from './streamChunksPreloadScript';
+/**
+ * High-level API for streaming content into a WebView.
+ *
+ * Wraps the low-level event protocol so callers never need to deal with
+ * event type constants, message serialisation, or sequencing concerns.
+ *
+ * @example
+ * ```ts
+ * const sender = new WebViewStreamSender((type, data) => {
+ *   webViewRef.current.injectJavaScript(
+ *     `window.onStreamChunksToWebView(${JSON.stringify({ type, data })});`
+ *   );
+ * });
+ *
+ * sender.checkReceiverReady();
+ * sender.setContent(html);
+ * sender.appendChunk(chunk);
+ * sender.finalizePayload();
+ * sender.reexecuteScripts();
+ * ```
+ */
+export class WebViewStreamSender {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Ask the receiver whether it is ready. The receiver will invoke its
+     * configured `receiverReadyCallbackPath` when it handles this event.
+     */
+    checkReceiverReady() {
+        this.transport(WebViewStreamEventTypes.CHECK_RECEIVER_READY);
+    }
+    /**
+     * Replace the WebView's `document.body.innerHTML` with the provided HTML.
+     * This also resets any previously buffered chunks.
+     */
+    setContent(html) {
+        this.transport(WebViewStreamEventTypes.SET_CONTENT, html);
+    }
+    /**
+     * Buffer a chunk in the receiver. Call this as many times as needed.
+     */
+    appendChunk(chunk) {
+        this.transport(WebViewStreamEventTypes.APPEND_CHUNK, chunk);
+    }
+    /**
+     * Join all buffered chunks and inject them as a single `<script>` tag
+     * into the DOM.
+     *
+     * This does NOT re-execute existing scripts — call `reexecuteScripts()`
+     * separately when needed.
+     */
+    finalizePayload(options) {
+        this.transport(WebViewStreamEventTypes.FINALIZE_PAYLOAD, options ? JSON.stringify(options) : undefined);
+    }
+    /**
+     * Re-execute `<script>` tags in the DOM by replacing them with clones.
+     *
+     * @param selector - optional CSS selector to limit which scripts are
+     *   re-executed. Defaults to `'script'` (all scripts).
+     *   The payload `<script>` injected by `finalizePayload()` is always
+     *   excluded automatically.
+     */
+    reexecuteScripts(selector) {
+        this.transport(WebViewStreamEventTypes.REEXECUTE_SCRIPTS, selector);
+    }
+}

package/dist/streamChunksPreloadScript.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal event types for the sender–receiver protocol.
+ * Prefer the high-level `WebViewStreamSender` API over using these directly.
+ */
+export declare const WebViewStreamEventTypes: {
+    readonly CHECK_RECEIVER_READY: "CHECK_RECEIVER_READY";
+    readonly SET_CONTENT: "SET_CONTENT";
+    readonly APPEND_CHUNK: "APPEND_CHUNK";
+    readonly FINALIZE_PAYLOAD: "FINALIZE_PAYLOAD";
+    readonly REEXECUTE_SCRIPTS: "REEXECUTE_SCRIPTS";
+};
+export type WebViewStreamEventType = (typeof WebViewStreamEventTypes)[keyof typeof WebViewStreamEventTypes];
+export type WebViewStreamReceiverEvent = {
+    type: WebViewStreamEventType;
+    data?: string;
+};
+export interface WebViewStreamPreloadScriptOptions {
+    /** Dot-separated path on `window` to call when CHECK_RECEIVER_READY fires, e.g. `'myService.onReady'` */
+    receiverReadyCallbackPath?: string;
+}
+export interface PayloadScriptInjectionOptions {
+    scriptType?: string;
+    scriptClassName?: string;
+    scriptTagName?: string;
+    anchorSelector?: string;
+}
+export declare const createWebViewStreamChunksPreloadScript: (options?: WebViewStreamPreloadScriptOptions) => string;
+export declare const getWebViewStreamChunksPreloadScript: (options?: WebViewStreamPreloadScriptOptions) => string;
+//# sourceMappingURL=streamChunksPreloadScript.d.ts.map

package/dist/streamChunksPreloadScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamChunksPreloadScript.d.ts","sourceRoot":"","sources":["../src/streamChunksPreloadScript.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;CAM1B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAE5G,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,WAAW,iCAAiC;IAChD,yGAAyG;IACzG,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,6BAA6B;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAoMD,eAAO,MAAM,sCAAsC,GAAI,UAAS,iCAAsC,WAGrG,CAAC;AAEF,eAAO,MAAM,mCAAmC,GAAI,UAAU,iCAAiC,WAE9F,CAAC"}

package/dist/streamChunksPreloadScript.js

@@ -0,0 +1,191 @@
+/**
+ * Internal event types for the sender–receiver protocol.
+ * Prefer the high-level `WebViewStreamSender` API over using these directly.
+ */
+export const WebViewStreamEventTypes = {
+    CHECK_RECEIVER_READY: 'CHECK_RECEIVER_READY',
+    SET_CONTENT: 'SET_CONTENT',
+    APPEND_CHUNK: 'APPEND_CHUNK',
+    FINALIZE_PAYLOAD: 'FINALIZE_PAYLOAD',
+    REEXECUTE_SCRIPTS: 'REEXECUTE_SCRIPTS',
+};
+// ---------------------------------------------------------------------------
+// Receiver IIFE — serialised via `.toString()` and injected into the WebView.
+// ---------------------------------------------------------------------------
+function webViewStreamReceiverIIFE(options, eventTypes) {
+    let payloadChunks = [];
+    let contentMutationObserved = false;
+    const injectedPayloadScriptClasses = new Set();
+    function resetState() {
+        payloadChunks = [];
+        contentMutationObserved = false;
+    }
+    const targetWindow = window;
+    // -- receiver-ready callback resolver -------------------------------------
+    function runReceiverReadyCallback() {
+        if (!options.receiverReadyCallbackPath.trim())
+            return;
+        const segments = options.receiverReadyCallbackPath.split('.').filter(Boolean);
+        let current = targetWindow;
+        for (const segment of segments) {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                current = undefined;
+                break;
+            }
+            current = current[segment];
+        }
+        if (typeof current === 'function') {
+            current();
+        }
+    }
+    // -- event dispatcher -----------------------------------------------------
+    targetWindow.onStreamChunksToWebView = function (event) {
+        switch (event.type) {
+            case eventTypes.SET_CONTENT: {
+                resetState();
+                replaceBodyContent(event.data ?? '');
+                break;
+            }
+            case eventTypes.APPEND_CHUNK: {
+                if (event.data)
+                    payloadChunks.push(event.data);
+                break;
+            }
+            case eventTypes.FINALIZE_PAYLOAD: {
+                const waitAndInject = () => {
+                    if (contentMutationObserved) {
+                        injectPayloadScript(event.data);
+                    }
+                    else {
+                        setTimeout(waitAndInject, 100);
+                    }
+                };
+                waitAndInject();
+                break;
+            }
+            case eventTypes.REEXECUTE_SCRIPTS: {
+                const waitAndExec = () => {
+                    if (contentMutationObserved) {
+                        reexecuteScripts(event.data);
+                    }
+                    else {
+                        setTimeout(waitAndExec, 100);
+                    }
+                };
+                waitAndExec();
+                break;
+            }
+            case eventTypes.CHECK_RECEIVER_READY: {
+                runReceiverReadyCallback();
+                break;
+            }
+        }
+    };
+    // -- DOM helpers ----------------------------------------------------------
+    function replaceBodyContent(newInnerHTML) {
+        const observer = new MutationObserver((mutationsList, currentObserver) => {
+            for (const mutation of mutationsList) {
+                if (mutation.type === 'childList') {
+                    currentObserver.disconnect();
+                    contentMutationObserved = true;
+                    return;
+                }
+            }
+        });
+        observer.observe(document.body, { childList: true });
+        document.body.innerHTML = newInnerHTML;
+    }
+    const defaultInjectionOptions = {
+        scriptType: 'application/json',
+        scriptClassName: 'webview-stream-payload',
+        scriptTagName: 'default-payload',
+        anchorSelector: '#styleArea',
+    };
+    function resolveInjectionOptions(rawData) {
+        if (!rawData) {
+            return defaultInjectionOptions;
+        }
+        try {
+            const parsed = JSON.parse(rawData);
+            return {
+                scriptType: parsed.scriptType ?? defaultInjectionOptions.scriptType,
+                scriptClassName: parsed.scriptClassName ?? defaultInjectionOptions.scriptClassName,
+                scriptTagName: parsed.scriptTagName ?? defaultInjectionOptions.scriptTagName,
+                anchorSelector: parsed.anchorSelector ?? defaultInjectionOptions.anchorSelector,
+            };
+        }
+        catch {
+            return defaultInjectionOptions;
+        }
+    }
+    function injectPayloadScript(rawData) {
+        try {
+            const injectionOptions = resolveInjectionOptions(rawData);
+            const fullPayload = payloadChunks.join('');
+            const scriptElement = document.createElement('script');
+            scriptElement.type = injectionOptions.scriptType;
+            scriptElement.classList.add(injectionOptions.scriptClassName, injectionOptions.scriptTagName);
+            scriptElement.textContent = fullPayload;
+            const anchor = document.querySelector(injectionOptions.anchorSelector);
+            anchor?.insertAdjacentElement('afterend', scriptElement);
+            injectedPayloadScriptClasses.add(injectionOptions.scriptClassName);
+        }
+        catch (error) {
+            console.error('[webview-stream] injectPayloadScript error', error);
+        }
+        payloadChunks = [];
+    }
+    function reexecuteScripts(selector) {
+        try {
+            const query = selector?.trim() || 'script';
+            const elements = Array.from(document.querySelectorAll(query));
+            for (const element of elements) {
+                if (!(element instanceof HTMLScriptElement))
+                    continue;
+                let isInjectedPayloadScript = false;
+                for (const payloadClassName of injectedPayloadScriptClasses) {
+                    if (element.classList.contains(payloadClassName)) {
+                        isInjectedPayloadScript = true;
+                        break;
+                    }
+                }
+                if (isInjectedPayloadScript)
+                    continue;
+                const replacement = document.createElement('script');
+                for (const { name, value } of Array.from(element.attributes)) {
+                    replacement.setAttribute(name, value);
+                }
+                if (element.src) {
+                    replacement.src = element.src;
+                }
+                else {
+                    replacement.textContent = element.textContent;
+                }
+                if (element.parentNode !== null) {
+                    try {
+                        element.parentNode.replaceChild(replacement, element);
+                    }
+                    catch (error) {
+                        console.error('[webview-stream] Failed to re-execute script tag', replacement, element, error);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error('[webview-stream] reexecuteScripts error', error);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Preload script generators
+// ---------------------------------------------------------------------------
+const defaultOptions = {
+    receiverReadyCallbackPath: '',
+};
+export const createWebViewStreamChunksPreloadScript = (options = {}) => {
+    const resolved = { ...defaultOptions, ...options };
+    return `(${webViewStreamReceiverIIFE.toString()})(${JSON.stringify(resolved)}, ${JSON.stringify(WebViewStreamEventTypes)});`;
+};
+export const getWebViewStreamChunksPreloadScript = (options) => {
+    return createWebViewStreamChunksPreloadScript(options);
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "react-native-webview-stream-chunks",
+  "version": "0.1.0",
+  "description": "Reusable preload script and event types for streaming large HTML/chunks into WebView",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "lint": "eslint ./src --ext ts",
+    "lint:fix": "eslint ./src --ext ts --fix",
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "webview",
+    "preload",
+    "stream",
+    "tiddlywiki"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^9.39.0",
+    "eslint-config-tidgi": "^2.2.0",
+    "typescript": "^5.9.3"
+  }
+}