;
+ readonly AcodeWebView: new (
+ id: string,
+ options?: WebViewOptions,
+ capabilities?: WebViewCapabilities,
+ ) => AcodeWebView;
+ readonly events: AcodeWebViewEvents;
+ readonly modes: {
+ readonly FULLSCREEN: "fullscreen";
+ readonly HIDDEN: "hidden";
+ };
+ readonly cacheModes: {
+ readonly DEFAULT: "default";
+ readonly NO_CACHE: "no-cache";
+ readonly CACHE_ONLY: "cache-only";
+ readonly CACHE_ELSE_NETWORK: "cache-else-network";
+ };
+ readonly mixedContentModes: {
+ readonly NEVER_ALLOW: "never-allow";
+ readonly COMPATIBILITY: "compatibility";
+ readonly ALWAYS_ALLOW: "always-allow";
+ };
+ readonly userAgentModes: {
+ readonly DEFAULT: "default";
+ readonly MOBILE: "mobile";
+ readonly DESKTOP: "desktop";
+ };
+ readonly algorithmicDarkeningModes: {
+ readonly AUTO: "auto";
+ readonly ON: "on";
+ readonly OFF: "off";
+ };
}
interface AcodeFullscreenAPI {
diff --git a/src/lib/webview.js b/src/lib/webview.js
index 3df669e683..dae223d662 100644
--- a/src/lib/webview.js
+++ b/src/lib/webview.js
@@ -1,77 +1,376 @@
import nativeBridge from "../plugins/webview/www/webview";
-let initialized = false;
+/**
+ * Event names emitted by a WebView instance.
+ *
+ * Native events are asynchronous and carry a plain data object. The two
+ * JS-local events ("shown", "hidden") are emitted after show()/hide() resolve.
+ */
+export const WebViewEvents = Object.freeze({
+ // Page lifecycle
+ PAGE_STARTED: "pageStarted",
+ PAGE_COMMIT_VISIBLE: "pageCommitVisible",
+ PAGE_FINISHED: "pageFinished",
+ PROGRESS: "progressChanged",
+ TITLE_CHANGED: "titleChanged",
+ FAVICON_CHANGED: "faviconChanged",
+ HISTORY_CHANGED: "historyChanged",
+ SCROLL_CHANGED: "scrollChanged",
+ RENDER_PROCESS_GONE: "renderProcessGone",
+ READY: "ready",
+ CLOSED: "closed",
+ // Navigation
+ NAVIGATION_REQUESTED: "navigationRequested",
+ NAVIGATION_BLOCKED: "navigationBlocked",
+ // Errors
+ RESOURCE_ERROR: "resourceError",
+ HTTP_ERROR: "httpError",
+ SSL_ERROR: "sslError",
+ // Page interaction
+ CONSOLE_MESSAGE: "consoleMessage",
+ JS_ALERT: "jsAlert",
+ JS_CONFIRM: "jsConfirm",
+ JS_PROMPT: "jsPrompt",
+ JS_BEFORE_UNLOAD: "jsBeforeUnload",
+ PERMISSION_REQUEST: "permissionRequest",
+ GEOLOCATION_PERMISSION: "geolocationPermissionRequest",
+ FULLSCREEN_CHANGED: "fullscreenChanged",
+ WINDOW_REQUESTED: "windowRequested",
+ // Downloads
+ DOWNLOAD_REQUESTED: "downloadRequested",
+ DOWNLOAD_STARTED: "downloadStarted",
+ DOWNLOAD_FAILED: "downloadFailed",
+ // JS-local
+ SHOWN: "shown",
+ HIDDEN: "hidden",
+ DESTROYED: "destroyed",
+});
+
+export const WebViewModes = Object.freeze({
+ FULLSCREEN: "fullscreen",
+ HIDDEN: "hidden",
+});
+
+export const CacheModes = Object.freeze({
+ DEFAULT: "default",
+ NO_CACHE: "no-cache",
+ CACHE_ONLY: "cache-only",
+ CACHE_ELSE_NETWORK: "cache-else-network",
+});
+
+export const MixedContentModes = Object.freeze({
+ NEVER_ALLOW: "never-allow",
+ COMPATIBILITY: "compatibility",
+ ALWAYS_ALLOW: "always-allow",
+});
+
+export const UserAgentModes = Object.freeze({
+ DEFAULT: "default",
+ MOBILE: "mobile",
+ DESKTOP: "desktop",
+});
+
+export const AlgorithmicDarkeningModes = Object.freeze({
+ AUTO: "auto",
+ ON: "on",
+ OFF: "off",
+});
+
+/** Events after which the native instance is gone and cannot be reused. */
+const TERMINAL_EVENTS = new Set([
+ WebViewEvents.CLOSED,
+ WebViewEvents.RENDER_PROCESS_GONE,
+]);
+
+/** Settings accepted by create()/configure(). */
+const SETTING_KEYS = [
+ "userAgent",
+ "userAgentMode",
+ "javaScript",
+ "domStorage",
+ "databaseStorage",
+ "cacheMode",
+ "mediaPlaybackRequiresUserGesture",
+ "loadImages",
+ "mixedContentMode",
+ "textZoom",
+ "initialScale",
+ "useWideViewPort",
+ "loadWithOverviewMode",
+ "supportZoom",
+ "builtInZoomControls",
+ "displayZoomControls",
+ "geolocation",
+ "safeBrowsing",
+ "algorithmicDarkening",
+ "acceptThirdPartyCookies",
+ "backgroundColor",
+];
+
+/** Behavioural options accepted by create(). */
+const BEHAVIOUR_KEYS = [
+ "mode",
+ "title",
+ "visible",
+ "incognito",
+ "profileName",
+ "allowNavigation",
+ "allowDownloads",
+];
+
+const CREATE_KEYS = [...BEHAVIOUR_KEYS, ...SETTING_KEYS];
+
+const MODES = Object.values(WebViewModes);
+const CACHE_MODES = Object.values(CacheModes);
+const MIXED_CONTENT_MODES = Object.values(MixedContentModes);
+const USER_AGENT_MODES = Object.values(UserAgentModes);
+const DARKENING_MODES = Object.values(AlgorithmicDarkeningModes);
+
const instances = new Map();
+let messageCallbackRegistered = false;
+let cachedCapabilities = null;
function ensureInit() {
- if (!initialized) {
- nativeBridge.setMessageCallback((payload) => {
- const { id, message, event, data } = payload;
- const instance = instances.get(id);
- if (!instance) return;
-
- if (event) {
- // Iterate a copy so callbacks can unsubscribe during dispatch.
- for (const entry of instance._eventCallbacks.slice()) {
- if (entry.event === event) {
- try {
- entry.callback(event, data);
- } catch (e) {
- console.error("WebView event callback error:", e);
- }
- }
- }
+ if (messageCallbackRegistered) return;
+ messageCallbackRegistered = true;
+ nativeBridge.setMessageCallback(dispatchNativePayload);
+}
- // A fullscreen WebView closed by the user (or by hide()) is
- // gone natively; mark it destroyed so later calls fail fast
- // and its listeners can be garbage collected.
- if (event === "closed") {
- instance._destroyed = true;
- instances.delete(id);
- instance._messageCallbacks = [];
- instance._eventCallbacks = [];
- }
- return;
- }
+function dispatchNativePayload(payload) {
+ if (!payload || typeof payload !== "object") return;
- if (message !== undefined) {
- let parsed = message;
- try {
- parsed = JSON.parse(message);
- } catch (_) {}
- for (const cb of instance._messageCallbacks.slice()) {
- try {
- cb(parsed);
- } catch (e) {
- console.error("WebView message callback error:", e);
- }
- }
- }
- });
- initialized = true;
+ const instance = instances.get(payload.id);
+ if (!instance) return;
+
+ if (payload.event) {
+ instance._handleEvent(payload.event, payload.data);
+ return;
+ }
+
+ if (payload.message !== undefined) {
+ instance._handleMessage(payload.message);
+ }
+}
+
+function assertOneOf(value, allowed, label) {
+ if (allowed.includes(value)) return;
+ throw new Error(
+ `Unsupported WebView ${label}: "${value}". Use one of: ${allowed
+ .map((entry) => `"${entry}"`)
+ .join(", ")}.`,
+ );
+}
+
+function clamp(value, min, max) {
+ const number = Number(value);
+ if (!Number.isFinite(number)) return min;
+ return Math.min(max, Math.max(min, Math.round(number)));
+}
+
+/** Validates user input and keeps only options the native layer understands. */
+function normalizeOptions(options) {
+ if (options == null) return {};
+ if (typeof options !== "object") {
+ throw new TypeError("WebView options must be an object");
+ }
+
+ const normalized = {};
+ for (const key of CREATE_KEYS) {
+ if (options[key] !== undefined) normalized[key] = options[key];
+ }
+
+ if (normalized.mode !== undefined) {
+ assertOneOf(normalized.mode, MODES, "mode");
+ }
+ if (normalized.userAgentMode !== undefined) {
+ assertOneOf(normalized.userAgentMode, USER_AGENT_MODES, "userAgentMode");
+ }
+ if (normalized.cacheMode !== undefined) {
+ assertOneOf(normalized.cacheMode, CACHE_MODES, "cacheMode");
+ }
+ if (normalized.mixedContentMode !== undefined) {
+ assertOneOf(
+ normalized.mixedContentMode,
+ MIXED_CONTENT_MODES,
+ "mixedContentMode",
+ );
+ }
+ if (normalized.algorithmicDarkening !== undefined) {
+ assertOneOf(
+ normalized.algorithmicDarkening,
+ DARKENING_MODES,
+ "algorithmicDarkening",
+ );
+ }
+ if (normalized.textZoom !== undefined) {
+ normalized.textZoom = clamp(normalized.textZoom, 25, 500);
+ }
+ if (normalized.initialScale !== undefined) {
+ normalized.initialScale = clamp(normalized.initialScale, 0, 1000);
+ }
+ if (normalized.profileName !== undefined && normalized.profileName !== null) {
+ normalized.profileName = normalizeProfileName(normalized.profileName);
+ }
+
+ return normalized;
+}
+
+/**
+ * Profile names are passed to the WebView provider verbatim. Rewriting them
+ * would let distinct requests collide onto one shared profile, so invalid
+ * names are rejected instead.
+ */
+function normalizeProfileName(profileName) {
+ const name = String(profileName);
+ if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
+ throw new Error(
+ `Unsupported WebView profileName: "${name}". Use 1-64 characters from A-Z, a-z, 0-9, "_" or "-".`,
+ );
+ }
+ if (name.startsWith("acode_incognito_")) {
+ throw new Error(
+ `Unsupported WebView profileName: "${name}" uses the reserved "acode_incognito_" prefix.`,
+ );
+ }
+ return name;
+}
+
+/** Normalizes a partial settings update passed to configure(). */
+function normalizeSettings(settings) {
+ if (settings == null) return {};
+ if (typeof settings !== "object") {
+ throw new TypeError("WebView settings must be an object");
+ }
+
+ const normalized = {};
+ for (const key of SETTING_KEYS) {
+ if (settings[key] !== undefined) normalized[key] = settings[key];
+ }
+
+ if (normalized.userAgentMode !== undefined) {
+ assertOneOf(normalized.userAgentMode, USER_AGENT_MODES, "userAgentMode");
+ }
+ if (normalized.cacheMode !== undefined) {
+ assertOneOf(normalized.cacheMode, CACHE_MODES, "cacheMode");
+ }
+ if (normalized.mixedContentMode !== undefined) {
+ assertOneOf(
+ normalized.mixedContentMode,
+ MIXED_CONTENT_MODES,
+ "mixedContentMode",
+ );
+ }
+ if (normalized.algorithmicDarkening !== undefined) {
+ assertOneOf(
+ normalized.algorithmicDarkening,
+ DARKENING_MODES,
+ "algorithmicDarkening",
+ );
+ }
+ if (normalized.textZoom !== undefined) {
+ normalized.textZoom = clamp(normalized.textZoom, 25, 500);
+ }
+ if (normalized.initialScale !== undefined) {
+ normalized.initialScale = clamp(normalized.initialScale, 0, 1000);
+ }
+
+ return normalized;
+}
+
+function parseMessage(message) {
+ if (typeof message !== "string") return message;
+ try {
+ return JSON.parse(message);
+ } catch (_) {
+ return message;
}
}
-class WebView {
- constructor(id, options = {}) {
+export class AcodeWebView {
+ constructor(id, options = {}, capabilities = {}) {
this.id = id;
- this.options = options;
+ this.options = Object.freeze({ ...options });
+ this.capabilities = Object.freeze({ ...capabilities });
+
this._messageCallbacks = [];
this._eventCallbacks = [];
+ this._anyCallbacks = [];
this._destroyed = false;
this._destroyPromise = null;
+ this._ready = false;
+ this._settings = { ...options };
+ this._state = {
+ url: "",
+ title: "",
+ progress: 0,
+ loading: false,
+ canGoBack: false,
+ canGoForward: false,
+ isolated: options.isolated === true,
+ profileName: options.profileName ?? null,
+ };
instances.set(id, this);
}
- async loadURL(url) {
+ get isDestroyed() {
+ return this._destroyed;
+ }
+
+ /** True once the native WebView exists (see waitForReady). */
+ get ready() {
+ return this._ready;
+ }
+
+ get isIncognito() {
+ return this.options.incognito === true;
+ }
+
+ /** True when the instance runs in its own isolated WebView profile. */
+ get isIsolated() {
+ return this._state.isolated;
+ }
+
+ get profileName() {
+ return this._state.profileName;
+ }
+
+ get url() {
+ return this._state.url;
+ }
+
+ get title() {
+ return this._state.title;
+ }
+
+ get progress() {
+ return this._state.progress;
+ }
+
+ get loading() {
+ return this._state.loading;
+ }
+
+ get canGoBack() {
+ return this._state.canGoBack;
+ }
+
+ get canGoForward() {
+ return this._state.canGoForward;
+ }
+
+ // ------------------------------------------------------------------
+ // Navigation / content
+ // ------------------------------------------------------------------
+
+ async loadURL(url, headers) {
this._checkDestroyed();
- await nativeBridge.loadURL(this.id, url);
+ await nativeBridge.loadURL(this.id, url, headers);
}
- async loadHTML(html) {
+ async loadHTML(html, options) {
this._checkDestroyed();
- await nativeBridge.loadHTML(this.id, html);
+ await nativeBridge.loadHTML(this.id, html, options);
}
async evaluate(js) {
@@ -79,52 +378,350 @@ class WebView {
return await nativeBridge.evaluate(this.id, js);
}
- onMessage(callback) {
+ async postMessage(message) {
this._checkDestroyed();
- if (typeof callback === "function") {
- this._messageCallbacks.push(callback);
- }
+ await nativeBridge.postMessage(this.id, message);
}
- offMessage(callback) {
- this._messageCallbacks = this._messageCallbacks.filter(
- (cb) => cb !== callback,
- );
+ async reload() {
+ this._checkDestroyed();
+ await nativeBridge.reload(this.id);
}
- on(event, callback) {
+ async stopLoading() {
this._checkDestroyed();
- if (typeof callback === "function") {
- this._eventCallbacks.push({ event, callback });
- }
+ await nativeBridge.stopLoading(this.id);
}
- off(event, callback) {
- this._eventCallbacks = this._eventCallbacks.filter(
- (entry) => !(entry.event === event && entry.callback === callback),
- );
+ async goBack() {
+ this._checkDestroyed();
+ return await nativeBridge.goBack(this.id);
}
- async postMessage(message) {
+ async goForward() {
this._checkDestroyed();
- await nativeBridge.postMessage(this.id, message);
+ return await nativeBridge.goForward(this.id);
+ }
+
+ /** Re-reads history flags from the native WebView and updates state. */
+ async refreshHistory() {
+ this._checkDestroyed();
+ const [back, forward] = await Promise.all([
+ nativeBridge.canGoBack(this.id),
+ nativeBridge.canGoForward(this.id),
+ ]);
+ this._state.canGoBack = !!back;
+ this._state.canGoForward = !!forward;
+ return {
+ canGoBack: this._state.canGoBack,
+ canGoForward: this._state.canGoForward,
+ };
}
+ /**
+ * Resolves once the native WebView exists. Hidden instances are ready by
+ * the time create() resolves; fullscreen instances become ready when their
+ * activity builds the WebView (which may be after show()). Rejects on
+ * close/destroy or timeout.
+ */
+ async waitForReady(timeout = 15000) {
+ this._checkDestroyed();
+ if (this._ready) return;
+
+ return new Promise((resolve, reject) => {
+ let timer = null;
+
+ const cleanup = () => {
+ this.off(WebViewEvents.READY, onReady);
+ this.off(WebViewEvents.CLOSED, onClosed);
+ this.off(WebViewEvents.DESTROYED, onClosed);
+ if (timer) clearTimeout(timer);
+ };
+
+ const settle = (error) => {
+ cleanup();
+ if (error) reject(error);
+ else resolve();
+ };
+
+ const onReady = () => {
+ this._ready = true;
+ settle(null);
+ };
+ const onClosed = () =>
+ settle(new Error("WebView closed before it became ready"));
+
+ // Subscribe before the native probe: a "ready" event may already be
+ // in flight, and it must not be lost between the check and the wait.
+ this.on(WebViewEvents.READY, onReady);
+ this.on(WebViewEvents.CLOSED, onClosed);
+ this.on(WebViewEvents.DESTROYED, onClosed);
+
+ if (timeout > 0) {
+ timer = setTimeout(
+ () =>
+ settle(
+ new Error("Timed out waiting for the WebView to become ready"),
+ ),
+ timeout,
+ );
+ }
+
+ // Hidden instances emit "ready" before the JS instance exists, so
+ // the event above is not enough on its own.
+ this.getInfo()
+ .then((info) => {
+ if (info && info.ready) {
+ this._ready = true;
+ settle(null);
+ }
+ })
+ .catch(() => {
+ // Destroyed while probing; the CLOSED/DESTROYED listener or
+ // the timeout will settle the promise.
+ });
+ });
+ }
+
+ /**
+ * Resolves when the main frame finishes loading (the "pageFinished" event),
+ * or rejects on a main-frame load error, close/destroy, or timeout.
+ *
+ * Attach it *before* starting the navigation, because loadURL()/loadHTML()
+ * resolve as soon as the load is initiated:
+ *
+ * const loaded = wv.waitForLoad();
+ * await wv.loadURL("https://example.com");
+ * await loaded; // now evaluate() sees the real document
+ */
+ waitForLoad(timeout = 15000) {
+ this._checkDestroyed();
+
+ return new Promise((resolve, reject) => {
+ let timer = null;
+
+ const cleanup = () => {
+ this.off(WebViewEvents.PAGE_FINISHED, onFinished);
+ this.off(WebViewEvents.RESOURCE_ERROR, onError);
+ this.off(WebViewEvents.CLOSED, onClosed);
+ this.off(WebViewEvents.DESTROYED, onClosed);
+ this.off(WebViewEvents.RENDER_PROCESS_GONE, onRendererGone);
+ if (timer) clearTimeout(timer);
+ };
+
+ const settle = (error, value) => {
+ cleanup();
+ if (error) reject(error);
+ else resolve(value);
+ };
+
+ const onFinished = (data) => settle(null, data);
+ const onError = (data) => {
+ // Ignore subresource failures (images, scripts, …).
+ if (data && data.isForMainFrame === false) return;
+ const detail = data?.description ? `: ${data.description}` : "";
+ settle(new Error(`WebView failed to load${detail}`));
+ };
+ const onClosed = () =>
+ settle(new Error("WebView closed before it finished loading"));
+ const onRendererGone = () =>
+ settle(
+ new Error(
+ "WebView renderer process exited before it finished loading",
+ ),
+ );
+
+ this.on(WebViewEvents.PAGE_FINISHED, onFinished);
+ this.on(WebViewEvents.RESOURCE_ERROR, onError);
+ this.on(WebViewEvents.CLOSED, onClosed);
+ this.on(WebViewEvents.DESTROYED, onClosed);
+ this.on(WebViewEvents.RENDER_PROCESS_GONE, onRendererGone);
+
+ if (timeout > 0) {
+ timer = setTimeout(
+ () =>
+ settle(
+ new Error("Timed out waiting for the WebView to finish loading"),
+ ),
+ timeout,
+ );
+ }
+ });
+ }
+
+ // ------------------------------------------------------------------
+ // Visibility
+ // ------------------------------------------------------------------
+
async show() {
this._checkDestroyed();
await nativeBridge.show(this.id);
+ this._dispatch(WebViewEvents.SHOWN);
}
async hide() {
this._checkDestroyed();
await nativeBridge.hide(this.id);
+ this._dispatch(WebViewEvents.HIDDEN);
}
- async reload() {
+ // ------------------------------------------------------------------
+ // Data / settings
+ // ------------------------------------------------------------------
+
+ async clearCache(includeDiskFiles = true) {
this._checkDestroyed();
- await nativeBridge.reload(this.id);
+ await nativeBridge.clearCache(this.id, includeDiskFiles);
+ }
+
+ async clearHistory() {
+ this._checkDestroyed();
+ await nativeBridge.clearHistory(this.id);
+ this._state.canGoBack = false;
+ this._state.canGoForward = false;
+ }
+
+ async clearFormData() {
+ this._checkDestroyed();
+ await nativeBridge.clearFormData(this.id);
+ }
+
+ /** Sets a custom user agent, or a preset via userAgentMode. */
+ async setUserAgent(userAgent, mode) {
+ this._checkDestroyed();
+ this._settings = await nativeBridge.setUserAgent(this.id, userAgent, mode);
+ return this._settings;
+ }
+
+ async getUserAgent() {
+ this._checkDestroyed();
+ return await nativeBridge.getUserAgent(this.id);
+ }
+
+ /** Applies a partial batch of WebSettings and resolves to the result. */
+ async configure(settings) {
+ this._checkDestroyed();
+ this._settings = await nativeBridge.updateSettings(
+ this.id,
+ normalizeSettings(settings),
+ );
+ return this._settings;
+ }
+
+ async getSettings() {
+ this._checkDestroyed();
+ this._settings = await nativeBridge.getSettings(this.id);
+ return this._settings;
+ }
+
+ /** Live snapshot: url, title, progress, history, isolation, UA, … */
+ async getInfo() {
+ this._checkDestroyed();
+ const info = await nativeBridge.getInfo(this.id);
+ if (info && typeof info === "object") {
+ this._state.url = info.url ?? this._state.url;
+ this._state.title = info.title ?? this._state.title;
+ this._state.progress = info.progress ?? this._state.progress;
+ this._state.loading = info.loading ?? this._state.loading;
+ this._state.canGoBack = info.canGoBack ?? this._state.canGoBack;
+ this._state.canGoForward = info.canGoForward ?? this._state.canGoForward;
+ if (info.isolated !== undefined) {
+ this._state.isolated = info.isolated === true;
+ }
+ if (info.profileName !== undefined) {
+ this._state.profileName = info.profileName ?? null;
+ }
+ }
+ return info;
+ }
+
+ // ------------------------------------------------------------------
+ // Events
+ // ------------------------------------------------------------------
+
+ /**
+ * Subscribes to an event. The callback receives (data, eventName), and
+ * passing "*" subscribes to every event. Returns the instance for chaining.
+ */
+ on(event, callback) {
+ this._checkDestroyed();
+ if (typeof callback !== "function") {
+ throw new TypeError("WebView event callback must be a function");
+ }
+ this._eventCallbacks.push({ event, callback });
+ return this;
}
+ off(event, callback) {
+ this._eventCallbacks = this._eventCallbacks.filter(
+ (entry) =>
+ !(
+ entry.event === event &&
+ (entry.callback === callback || entry.callback._original === callback)
+ ),
+ );
+ return this;
+ }
+
+ /** Subscribes to a single dispatch of an event. */
+ once(event, callback) {
+ const wrapper = (data, name) => {
+ this.off(event, wrapper);
+ callback(data, name);
+ };
+ // Allow off(event, originalCallback) to remove a pending once listener.
+ wrapper._original = callback;
+ return this.on(event, wrapper);
+ }
+
+ /** Subscribes to every event; the callback receives (eventName, data). */
+ onAny(callback) {
+ this._checkDestroyed();
+ if (typeof callback !== "function") {
+ throw new TypeError("WebView event callback must be a function");
+ }
+ this._anyCallbacks.push(callback);
+ return this;
+ }
+
+ offAny(callback) {
+ this._anyCallbacks = this._anyCallbacks.filter((cb) => cb !== callback);
+ return this;
+ }
+
+ /** Removes listeners for one event, or every listener when omitted. */
+ removeAllListeners(event) {
+ if (event === undefined) {
+ this._eventCallbacks = [];
+ this._anyCallbacks = [];
+ } else {
+ this._eventCallbacks = this._eventCallbacks.filter(
+ (entry) => entry.event !== event,
+ );
+ }
+ return this;
+ }
+
+ /** Receives messages posted by the hosted page via window.webview.postMessage. */
+ onMessage(callback) {
+ this._checkDestroyed();
+ if (typeof callback === "function") {
+ this._messageCallbacks.push(callback);
+ }
+ return this;
+ }
+
+ offMessage(callback) {
+ this._messageCallbacks = this._messageCallbacks.filter(
+ (cb) => cb !== callback,
+ );
+ return this;
+ }
+
+ // ------------------------------------------------------------------
+ // Teardown
+ // ------------------------------------------------------------------
+
async destroy() {
this._checkDestroyed();
if (!this._destroyPromise) {
@@ -132,8 +729,8 @@ class WebView {
await nativeBridge.destroy(this.id);
this._destroyed = true;
instances.delete(this.id);
- this._messageCallbacks = [];
- this._eventCallbacks = [];
+ this._dispatch(WebViewEvents.DESTROYED);
+ this._clearListeners();
})();
}
@@ -144,6 +741,115 @@ class WebView {
}
}
+ // ------------------------------------------------------------------
+ // Internals
+ // ------------------------------------------------------------------
+
+ _handleEvent(event, data) {
+ if (event === WebViewEvents.READY) {
+ this._ready = true;
+ }
+ this._applyState(event, data);
+ this._dispatch(event, data);
+
+ if (TERMINAL_EVENTS.has(event)) {
+ this._destroyed = true;
+ instances.delete(this.id);
+ this._clearListeners();
+ }
+ }
+
+ _handleMessage(message) {
+ const parsed = parseMessage(message);
+ for (const callback of this._messageCallbacks.slice()) {
+ try {
+ callback(parsed);
+ } catch (error) {
+ console.error("WebView message callback error:", error);
+ }
+ }
+ }
+
+ _applyState(event, data) {
+ const payload = data && typeof data === "object" ? data : {};
+ switch (event) {
+ case WebViewEvents.READY:
+ // Isolation metadata is only final once the native WebView exists
+ // and the profile has been bound (deferred fullscreen instances).
+ if (payload.isolated !== undefined) {
+ this._state.isolated = payload.isolated === true;
+ }
+ if (payload.profileName !== undefined) {
+ this._state.profileName = payload.profileName ?? null;
+ }
+ break;
+ case WebViewEvents.PAGE_STARTED:
+ if (payload.url !== undefined) this._state.url = payload.url;
+ this._state.loading = true;
+ break;
+ case WebViewEvents.PAGE_COMMIT_VISIBLE:
+ if (payload.url !== undefined) this._state.url = payload.url;
+ break;
+ case WebViewEvents.PAGE_FINISHED:
+ if (payload.url !== undefined) this._state.url = payload.url;
+ if (payload.title !== undefined) this._state.title = payload.title;
+ this._state.loading = false;
+ this._state.progress = 100;
+ break;
+ case WebViewEvents.PROGRESS: {
+ const progress = Number(payload.progress);
+ if (Number.isFinite(progress)) {
+ this._state.progress = progress;
+ this._state.loading = progress < 100;
+ }
+ break;
+ }
+ case WebViewEvents.TITLE_CHANGED:
+ if (payload.title !== undefined) this._state.title = payload.title;
+ break;
+ case WebViewEvents.HISTORY_CHANGED:
+ if (payload.canGoBack !== undefined) {
+ this._state.canGoBack = !!payload.canGoBack;
+ }
+ if (payload.canGoForward !== undefined) {
+ this._state.canGoForward = !!payload.canGoForward;
+ }
+ break;
+ case WebViewEvents.NAVIGATION_REQUESTED:
+ if (payload.allowed && payload.url !== undefined) {
+ this._state.url = payload.url;
+ }
+ break;
+ default:
+ break;
+ }
+ }
+
+ _dispatch(event, data) {
+ for (const entry of this._eventCallbacks.slice()) {
+ if (entry.event !== event && entry.event !== "*") continue;
+ try {
+ entry.callback(data, event);
+ } catch (error) {
+ console.error("WebView event callback error:", error);
+ }
+ }
+
+ for (const callback of this._anyCallbacks.slice()) {
+ try {
+ callback(event, data);
+ } catch (error) {
+ console.error("WebView event callback error:", error);
+ }
+ }
+ }
+
+ _clearListeners() {
+ this._messageCallbacks = [];
+ this._eventCallbacks = [];
+ this._anyCallbacks = [];
+ }
+
_checkDestroyed() {
if (this._destroyed) {
throw new Error("WebView has been destroyed");
@@ -151,27 +857,78 @@ class WebView {
}
}
-const webviewAPI = {
- async create(options = {}) {
- ensureInit();
+/**
+ * Creates a WebView. Options are validated up front; the resolved set of
+ * options (including native defaults) is available as instance.options.
+ */
+async function create(options = {}) {
+ ensureInit();
- const mode = options.mode || "hidden";
- if (mode !== "fullscreen" && mode !== "hidden") {
- throw new Error(
- `Unsupported WebView mode: "${mode}". Use "fullscreen" or "hidden".`,
- );
- }
+ const normalized = normalizeOptions(options);
+ const result = await nativeBridge.create(normalized);
+ const resolved = typeof result === "string" ? { id: result } : result || {};
+ const id = resolved.id;
+ if (!id) {
+ throw new Error("Native WebView creation did not return an id");
+ }
- const id = await nativeBridge.create({
- title: options.title || "",
- mode,
- allowNavigation: options.allowNavigation !== false,
- allowDownloads: options.allowDownloads === true,
- visible: options.visible !== false,
- });
+ const nativeOptions = { ...normalized, ...(resolved.options || {}) };
+ if (resolved.isolated !== undefined) {
+ nativeOptions.isolated = resolved.isolated;
+ }
+ if (resolved.profileName) {
+ nativeOptions.profileName = resolved.profileName;
+ }
+
+ const instance = new AcodeWebView(
+ id,
+ nativeOptions,
+ resolved.capabilities || {},
+ );
+ if (resolved.isolated !== undefined) {
+ // Trust the native isolation result over any requested profile name.
+ instance._state.isolated = resolved.isolated === true;
+ instance._state.profileName = resolved.profileName ?? null;
+ } else if (resolved.profileName !== undefined) {
+ instance._state.profileName = resolved.profileName ?? null;
+ }
+ instance._ready = resolved.ready === true;
+ return instance;
+}
- return new WebView(id, options);
+/** Resolves the plugin's feature support (multi-profile, document-start, …). */
+async function getCapabilities() {
+ ensureInit();
+ if (!cachedCapabilities) {
+ cachedCapabilities = await nativeBridge.capabilities();
+ }
+ return cachedCapabilities;
+}
+
+const webviewAPI = {
+ create,
+ getCapabilities,
+ /** Live instance for an id, or null when it no longer exists. */
+ get(id) {
+ return instances.get(id) || null;
+ },
+ /** Ids of all live instances. */
+ list() {
+ return Array.from(instances.keys());
+ },
+ /** Destroys every live instance, ignoring individual failures. */
+ async destroyAll() {
+ await Promise.allSettled(
+ Array.from(instances.values()).map((instance) => instance.destroy()),
+ );
},
+ AcodeWebView,
+ events: WebViewEvents,
+ modes: WebViewModes,
+ cacheModes: CacheModes,
+ mixedContentModes: MixedContentModes,
+ userAgentModes: UserAgentModes,
+ algorithmicDarkeningModes: AlgorithmicDarkeningModes,
};
export default webviewAPI;
diff --git a/src/plugins/webview/package.json b/src/plugins/webview/package.json
index 673be361cb..67641909fa 100644
--- a/src/plugins/webview/package.json
+++ b/src/plugins/webview/package.json
@@ -1,7 +1,7 @@
{
"name": "cordova-plugin-acode-webview",
- "version": "1.0.0",
- "description": "Acode WebView Plugin API",
+ "version": "2.0.0",
+ "description": "Acode WebView Plugin API - Create and manage isolated WebView instances",
"main": "",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
diff --git a/src/plugins/webview/plugin.xml b/src/plugins/webview/plugin.xml
index c7a6ff773d..e12862da9c 100644
--- a/src/plugins/webview/plugin.xml
+++ b/src/plugins/webview/plugin.xml
@@ -1,6 +1,6 @@
+ xmlns:android="http://schemas.android.com/apk/res/android" id="cordova-plugin-acode-webview" version="2.0.0">
cordova-plugin-acode-webview
Acode WebView Plugin API - Create and manage isolated WebView instances
Apache 2.0
@@ -18,9 +18,16 @@
+
+
+
+
+
diff --git a/src/plugins/webview/src/android/com/foxdebug/webview/ProfileManager.java b/src/plugins/webview/src/android/com/foxdebug/webview/ProfileManager.java
new file mode 100644
index 0000000000..1968d6aebd
--- /dev/null
+++ b/src/plugins/webview/src/android/com/foxdebug/webview/ProfileManager.java
@@ -0,0 +1,252 @@
+package com.foxdebug.webview;
+
+import android.util.Log;
+import android.webkit.CookieManager;
+import android.webkit.WebStorage;
+import android.webkit.WebView;
+import androidx.webkit.Profile;
+import androidx.webkit.ProfileStore;
+import androidx.webkit.WebStorageCompat;
+import androidx.webkit.WebViewCompat;
+import androidx.webkit.WebViewFeature;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+/**
+ * Incognito / profile isolation built on AndroidX WebKit's multi-profile API.
+ *
+ * WebView profiles provide a genuinely separate cookie jar and web-storage
+ * area, which is what "incognito" needs. Support depends on the installed
+ * WebView provider ({@link WebViewFeature#MULTI_PROFILE}); when it is missing
+ * {@link #acquire} returns {@code null} and the instance falls back to the
+ * best-effort behaviour documented on {@code WebViewInstance}.
+ *
+ *
A profile is acquired when the instance is created (so its isolation state
+ * is known before the lazily created fullscreen WebView exists) and bound to
+ * the WebView once it is constructed. Profiles are reference counted so several
+ * instances can share one. Data is cleared when the last instance goes away,
+ * and auto-generated incognito profiles are also deleted.
+ */
+final class ProfileManager {
+
+ private static final String TAG = "AcodeWebView";
+ private static final String EPHEMERAL_PREFIX = "acode_incognito_";
+ private static final int MAX_NAME_LENGTH = 64;
+
+ /**
+ * Profile names are passed to the WebView provider verbatim, so they must be
+ * canonical. Anything else is rejected instead of being rewritten, which
+ * would let two different requested names collide onto one shared profile.
+ */
+ private static final Pattern VALID_NAME = Pattern.compile("[A-Za-z0-9_-]{1," + MAX_NAME_LENGTH + "}");
+
+ private static final Map refCounts = new HashMap<>();
+
+ private ProfileManager() {}
+
+ static boolean isSupported() {
+ try {
+ return WebViewFeature.isFeatureSupported(WebViewFeature.MULTI_PROFILE);
+ } catch (Throwable t) {
+ return false;
+ }
+ }
+
+ static boolean canDeleteBrowsingData() {
+ try {
+ return WebViewFeature.isFeatureSupported(WebViewFeature.DELETE_BROWSING_DATA);
+ } catch (Throwable t) {
+ return false;
+ }
+ }
+
+ /** True when {@code name} can be used verbatim as a WebView profile name. */
+ static boolean isValidName(String name) {
+ return name != null && VALID_NAME.matcher(name).matches();
+ }
+
+ /** True for the reserved namespace used by auto-generated incognito profiles. */
+ static boolean isReservedName(String name) {
+ return name != null && name.startsWith(EPHEMERAL_PREFIX);
+ }
+
+ /**
+ * Validates a caller-supplied profile name. Rejecting (rather than rewriting)
+ * guarantees distinct requested names never select the same profile.
+ */
+ static void requireValidUserName(String name) {
+ if (!isValidName(name)) {
+ throw new IllegalArgumentException(
+ "Unsupported profileName: \"" + name
+ + "\". Use 1-" + MAX_NAME_LENGTH + " characters from A-Z, a-z, 0-9, \"_\" or \"-\"."
+ );
+ }
+ if (isReservedName(name)) {
+ throw new IllegalArgumentException(
+ "Unsupported profileName: \"" + name + "\" uses the reserved \""
+ + EPHEMERAL_PREFIX + "\" prefix."
+ );
+ }
+ }
+
+ /** Name for an auto-generated, ephemeral incognito profile. */
+ static String ephemeralName(String id) {
+ StringBuilder builder = new StringBuilder(EPHEMERAL_PREFIX);
+ String source = id != null ? id : "";
+ for (int i = 0; i < source.length() && builder.length() < MAX_NAME_LENGTH; i++) {
+ char c = source.charAt(i);
+ if (Character.isLetterOrDigit(c) || c == '_' || c == '-') {
+ builder.append(c);
+ }
+ }
+ return builder.toString();
+ }
+
+ /**
+ * Creates (or joins) the named profile and takes a reference. Runs on the UI
+ * thread, before the WebView exists. Returns null when isolation is not
+ * available; callers then use the documented fallback.
+ */
+ static Profile acquire(String profileName) {
+ if (profileName == null || !isSupported()) return null;
+ try {
+ ProfileStore store = ProfileStore.getInstance();
+ Profile profile = store.getOrCreateProfile(profileName);
+ if (profile == null) return null;
+
+ CookieManager cookies = profile.getCookieManager();
+ if (cookies != null) {
+ cookies.setAcceptCookie(true);
+ }
+
+ refCounts.merge(profileName, 1, Integer::sum);
+ return profile;
+ } catch (Throwable t) {
+ // Any provider-side failure degrades to the non-isolated fallback rather
+ // than failing instance creation.
+ Log.w(TAG, "Profile isolation unavailable for \"" + profileName + "\"", t);
+ return null;
+ }
+ }
+
+ /**
+ * Binds an acquired profile to a freshly constructed WebView. Must run on the
+ * UI thread and before the WebView loads any content.
+ */
+ static boolean bind(WebView view, Profile profile) {
+ if (view == null || profile == null) return false;
+ try {
+ WebViewCompat.setProfile(view, profile.getName());
+ return true;
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not bind profile \"" + profile.getName() + "\"", t);
+ return false;
+ }
+ }
+
+ /**
+ * Releases one reference to a profile. When the last reference is gone the
+ * profile's browsing data is cleared and, if it was auto-generated for
+ * incognito, the profile itself is deleted.
+ */
+ static void release(String profileName, boolean ephemeral, boolean clearData) {
+ if (profileName == null) return;
+
+ Integer count = refCounts.get(profileName);
+ if (count == null) return;
+ if (count > 1) {
+ refCounts.put(profileName, count - 1);
+ return;
+ }
+ refCounts.remove(profileName);
+
+ if (!clearData && !ephemeral) return;
+
+ try {
+ ProfileStore store = ProfileStore.getInstance();
+ Profile profile = store.getProfile(profileName);
+ if (profile == null) {
+ if (ephemeral) deleteQuietly(profileName);
+ return;
+ }
+ clearProfile(profile, () -> {
+ if (ephemeral) deleteQuietly(profileName);
+ });
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not release profile \"" + profileName + "\"", t);
+ }
+ }
+
+ /**
+ * Deletes auto-generated incognito profiles left behind by a previous
+ * process (for example when the app was killed before cleanup ran).
+ */
+ static void cleanupEphemeralProfiles() {
+ if (!isSupported()) return;
+ try {
+ ProfileStore store = ProfileStore.getInstance();
+ List names = new ArrayList<>(store.getAllProfileNames());
+ for (String name : names) {
+ if (name == null || !name.startsWith(EPHEMERAL_PREFIX)) continue;
+ Profile profile = store.getProfile(name);
+ if (profile == null) {
+ deleteQuietly(name);
+ } else {
+ clearProfile(profile, () -> deleteQuietly(name));
+ }
+ }
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not clean up ephemeral profiles", t);
+ }
+ }
+
+ private static void clearProfile(Profile profile, Runnable onDone) {
+ try {
+ CookieManager cookies = profile.getCookieManager();
+ if (cookies != null) {
+ cookies.removeAllCookies(null);
+ }
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not clear profile cookies", t);
+ }
+
+ WebStorage storage = null;
+ try {
+ storage = profile.getWebStorage();
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not access profile web storage", t);
+ }
+
+ if (storage == null) {
+ if (onDone != null) onDone.run();
+ return;
+ }
+
+ if (canDeleteBrowsingData()) {
+ try {
+ WebStorageCompat.deleteBrowsingData(storage, onDone);
+ return;
+ } catch (Throwable t) {
+ Log.w(TAG, "deleteBrowsingData failed; falling back to deleteAllData", t);
+ }
+ }
+
+ try {
+ storage.deleteAllData();
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not clear profile web storage", t);
+ }
+ if (onDone != null) onDone.run();
+ }
+
+ private static void deleteQuietly(String profileName) {
+ try {
+ ProfileStore.getInstance().deleteProfile(profileName);
+ } catch (Throwable t) {
+ Log.w(TAG, "Could not delete profile \"" + profileName + "\"", t);
+ }
+ }
+}
diff --git a/src/plugins/webview/src/android/com/foxdebug/webview/WebViewActivity.java b/src/plugins/webview/src/android/com/foxdebug/webview/WebViewActivity.java
index 6090979a7d..849eaea57f 100644
--- a/src/plugins/webview/src/android/com/foxdebug/webview/WebViewActivity.java
+++ b/src/plugins/webview/src/android/com/foxdebug/webview/WebViewActivity.java
@@ -3,14 +3,21 @@
import android.app.Activity;
import android.os.Build;
import android.os.Bundle;
+import android.view.View;
import android.view.ViewGroup;
import android.webkit.WebView;
import android.widget.FrameLayout;
+/**
+ * Hosts a "fullscreen" {@link WebViewInstance}: it shows the instance's WebView
+ * and renders fullscreen custom views (video, canvas, …) on top of it.
+ */
public class WebViewActivity extends Activity {
private WebView webView;
private String webviewId;
+ private FrameLayout container;
+ private View customView;
@Override
public void onCreate(Bundle savedInstanceState) {
@@ -19,9 +26,7 @@ public void onCreate(Bundle savedInstanceState) {
webviewId = getIntent().getStringExtra("webviewId");
// The plugin registers itself in pluginInitialize(), so the singleton is
- // always available while the app is alive. Previously this read a static
- // field that was never set, which made every fullscreen WebView close
- // instantly because the instance lookup returned null.
+ // always available while the app is alive.
WebViewPlugin plugin = WebViewPlugin.getInstance();
WebViewInstance instance = plugin != null ? plugin.getInstance(webviewId) : null;
if (instance == null) {
@@ -45,7 +50,7 @@ public void onCreate(Bundle savedInstanceState) {
if (webView.getParent() != null) {
((ViewGroup) webView.getParent()).removeView(webView);
}
- FrameLayout container = new FrameLayout(this);
+ container = new FrameLayout(this);
// Edge-to-edge is enforced on newer Android versions, so pad the content
// out from under the status and navigation bars.
WebViewInstance.applySystemBarInsets(container);
@@ -60,8 +65,48 @@ public void onCreate(Bundle savedInstanceState) {
}
}
+ /** Renders a fullscreen custom view (e.g. a