frida-ui-runtime 2.0.0

package/lib/java-runtime.js

@@ -0,0 +1,2 @@
+import Java from "frida-java-bridge";
+export default Java;

package/lib/logger.d.ts

@@ -0,0 +1,43 @@
+export declare function log(message: string): void;
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+type LogItem = {
+    ts: number;
+    level: LogLevel;
+    message: string;
+};
+type LogListener = (items: LogItem[]) => void;
+export declare class Logger {
+    on(event: string, listener: (level: LogLevel, message: string) => void): () => void;
+    private static _instance;
+    static get instance(): Logger;
+    private levelPriority;
+    private currentLevel;
+    private maxBuffer;
+    private buffer;
+    private head;
+    private size;
+    private flushIntervalMs;
+    private pending;
+    private flushTimer;
+    private listeners;
+    constructor(level?: LogLevel, options?: {
+        maxBuffer?: number;
+        flushIntervalMs?: number;
+    });
+    setLevel(level: LogLevel): void;
+    setMaxBuffer(max: number): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    onLog(listener: LogListener, replay?: boolean): () => void;
+    getRecent(limit?: number): LogItem[];
+    clear(): void;
+    private safeStringify;
+    private formatArgs;
+    private _log;
+    private pushToBuffer;
+    private scheduleFlush;
+    private emitBatch;
+}
+export {};

package/lib/logger.js

@@ -0,0 +1,200 @@
+import { ConstantConfig } from "./constant-config.js";
+export function log(message) {
+    console.log(message);
+}
+export class Logger {
+    on(event, listener) {
+        if (event !== "log")
+            throw new Error(`Unsupported logger event: ${event}`);
+        return this.onLog((items) => {
+            for (const item of items)
+                listener(item.level, item.message);
+        }, false);
+    }
+    static get instance() {
+        if (!Logger._instance)
+            Logger._instance = new Logger(ConstantConfig.isDev ? "debug" : "info");
+        return Logger._instance;
+    }
+    constructor(level = "info", options) {
+        this.levelPriority = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3,
+            none: 4,
+        };
+        this.head = 0;
+        this.size = 0;
+        this.pending = [];
+        this.flushTimer = null;
+        this.listeners = [];
+        this.currentLevel = level;
+        this.maxBuffer = Math.max(50, options?.maxBuffer ?? 300);
+        this.flushIntervalMs = Math.max(8, options?.flushIntervalMs ?? 16);
+        this.buffer = new Array(this.maxBuffer);
+    }
+    setLevel(level) {
+        this.currentLevel = level;
+    }
+    setMaxBuffer(max) {
+        const newMax = Math.max(50, max | 0);
+        if (newMax === this.maxBuffer)
+            return;
+        const items = this.getRecent(newMax);
+        this.maxBuffer = newMax;
+        this.buffer = new Array(this.maxBuffer);
+        this.head = 0;
+        this.size = 0;
+        for (const it of items)
+            this.pushToBuffer(it);
+    }
+    debug(...args) {
+        this._log("debug", ...args);
+    }
+    info(...args) {
+        this._log("info", ...args);
+    }
+    warn(...args) {
+        this._log("warn", ...args);
+    }
+    error(...args) {
+        this._log("error", ...args);
+    }
+    onLog(listener, replay = true) {
+        this.listeners.push(listener);
+        if (replay) {
+            const recent = this.getRecent(this.maxBuffer);
+            if (recent.length)
+                listener(recent);
+        }
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    getRecent(limit = 200) {
+        const n = Math.min(Math.max(1, limit | 0), this.size);
+        const out = [];
+        if (n <= 0)
+            return out;
+        const start = (this.head - this.size + this.maxBuffer) % this.maxBuffer;
+        const begin = (this.head - n + this.maxBuffer) % this.maxBuffer;
+        let i = begin;
+        for (let k = 0; k < n; k++) {
+            const it = this.buffer[i];
+            if (it)
+                out.push(it);
+            i = (i + 1) % this.maxBuffer;
+        }
+        return out;
+    }
+    clear() {
+        this.buffer = new Array(this.maxBuffer);
+        this.head = 0;
+        this.size = 0;
+        this.pending.length = 0;
+        this.emitBatch([]);
+    }
+    safeStringify(v) {
+        try {
+            return JSON.stringify(v);
+        }
+        catch {
+            try {
+                return String(v);
+            }
+            catch {
+                return "[Unstringifiable]";
+            }
+        }
+    }
+    formatArgs(args) {
+        if (!args || args.length === 0)
+            return "";
+        if (args.length === 1 && typeof args[0] === "string")
+            return args[0];
+        let out = "";
+        for (let i = 0; i < args.length; i++) {
+            const a = args[i];
+            let s;
+            if (typeof a === "string")
+                s = a;
+            else if (a == null)
+                s = String(a);
+            else if (typeof a === "number" ||
+                typeof a === "boolean" ||
+                typeof a === "bigint")
+                s = String(a);
+            else if (a instanceof Error)
+                s = a.stack || a.message || String(a);
+            else
+                s = this.safeStringify(a);
+            if (i === 0)
+                out = s;
+            else
+                out += " " + s;
+        }
+        return out;
+    }
+    _log(level, ...args) {
+        if (this.levelPriority[level] < this.levelPriority[this.currentLevel])
+            return;
+        const msg = this.formatArgs(args);
+        const item = {
+            ts: Date.now(),
+            level,
+            message: msg,
+        };
+        switch (level) {
+            case "debug":
+                console.debug(msg);
+                break;
+            case "info":
+                console.info(msg);
+                break;
+            case "warn":
+                console.warn(msg);
+                break;
+            case "error":
+                console.error(msg);
+                break;
+        }
+        this.pushToBuffer(item);
+        this.pending.push(item);
+        const pendingLimit = this.maxBuffer * 2;
+        if (this.pending.length > pendingLimit) {
+            this.pending.splice(0, this.pending.length - pendingLimit);
+        }
+        this.scheduleFlush();
+    }
+    pushToBuffer(item) {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.maxBuffer;
+        if (this.size < this.maxBuffer)
+            this.size++;
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            const batch = this.pending;
+            this.pending = [];
+            this.emitBatch(batch);
+        }, this.flushIntervalMs);
+    }
+    emitBatch(items) {
+        if (!this.listeners.length)
+            return;
+        for (let i = 0; i < this.listeners.length; i++) {
+            const fn = this.listeners[i];
+            try {
+                fn(items);
+            }
+            catch { }
+        }
+    }
+}
+Logger._instance = null;

package/lib/runtime/component-registry.d.ts

@@ -0,0 +1,24 @@
+export interface RegisteredComponent {
+    getId(): string;
+    getValue?(): unknown;
+    captureState?(): unknown;
+    dispose?(): void | Promise<void>;
+}
+export interface ComponentEntry<T extends RegisteredComponent> {
+    component: T;
+    tabId: string;
+    ownerId?: string;
+    container?: unknown;
+}
+export declare class ComponentRegistry<T extends RegisteredComponent = RegisteredComponent> {
+    private readonly components;
+    add(component: T, tabId: string, ownerId?: string): void;
+    get(id: string): T | undefined;
+    getEntry(id: string): ComponentEntry<T> | undefined;
+    remove(id: string): ComponentEntry<T> | undefined;
+    attach(id: string, container: unknown): void;
+    childrenOf(ownerId: string): ComponentEntry<T>[];
+    values(): IterableIterator<ComponentEntry<T>>;
+    captureState(): Record<string, unknown>;
+    clear(): void;
+}

package/lib/runtime/component-registry.js

@@ -0,0 +1,48 @@
+export class ComponentRegistry {
+    constructor() {
+        this.components = new Map();
+    }
+    add(component, tabId, ownerId) {
+        const id = component.getId();
+        if (!id)
+            throw new Error("Component identifier cannot be empty");
+        if (this.components.has(id)) {
+            throw new Error(`Component ${id} is already registered`);
+        }
+        this.components.set(id, { component, tabId, ownerId });
+    }
+    get(id) {
+        return this.components.get(id)?.component;
+    }
+    getEntry(id) {
+        return this.components.get(id);
+    }
+    remove(id) {
+        const entry = this.components.get(id);
+        if (entry)
+            this.components.delete(id);
+        return entry;
+    }
+    attach(id, container) {
+        const entry = this.components.get(id);
+        if (!entry)
+            throw new Error(`Component ${id} is not registered`);
+        entry.container = container;
+    }
+    childrenOf(ownerId) {
+        return Array.from(this.components.values()).filter(entry => entry.ownerId === ownerId);
+    }
+    values() {
+        return this.components.values();
+    }
+    captureState() {
+        const state = {};
+        for (const [id, { component }] of this.components) {
+            state[id] = component.captureState?.() ?? component.getValue?.();
+        }
+        return state;
+    }
+    clear() {
+        this.components.clear();
+    }
+}

package/lib/runtime/launch-sequence.d.ts

@@ -0,0 +1,5 @@
+export interface LaunchableOverlay {
+    present(mode: "icon"): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function runLaunchSequence<T extends LaunchableOverlay>(create: () => Promise<T>, setup: (overlay: T) => void | Promise<void>, onCleanupError?: (error: unknown) => void): Promise<T>;

package/lib/runtime/launch-sequence.js

@@ -0,0 +1,20 @@
+export async function runLaunchSequence(create, setup, onCleanupError) {
+    let overlay;
+    try {
+        overlay = await create();
+        await setup(overlay);
+        await overlay.present("icon");
+        return overlay;
+    }
+    catch (error) {
+        if (overlay) {
+            try {
+                await overlay.dispose();
+            }
+            catch (cleanupError) {
+                onCleanupError?.(cleanupError);
+            }
+        }
+        throw error;
+    }
+}

package/lib/runtime/lifecycle-controller.d.ts

@@ -0,0 +1,9 @@
+export type LifecycleState = "created" | "mounted" | "icon-visible" | "menu-visible" | "hidden" | "disposing" | "disposed";
+export declare class LifecycleController {
+    private queue;
+    private currentState;
+    get state(): LifecycleState;
+    get disposed(): boolean;
+    transition(next: LifecycleState): void;
+    run<T>(name: string, operation: () => T | Promise<T>): Promise<T>;
+}

package/lib/runtime/lifecycle-controller.js

@@ -0,0 +1,31 @@
+export class LifecycleController {
+    constructor() {
+        this.queue = Promise.resolve();
+        this.currentState = "created";
+    }
+    get state() {
+        return this.currentState;
+    }
+    get disposed() {
+        return this.currentState === "disposed";
+    }
+    transition(next) {
+        if (this.currentState === "disposed" && next !== "disposed") {
+            throw new Error(`Cannot transition disposed lifecycle to ${next}`);
+        }
+        if (this.currentState === "disposing" && next !== "disposed") {
+            throw new Error(`Cannot transition disposing lifecycle to ${next}`);
+        }
+        this.currentState = next;
+    }
+    run(name, operation) {
+        const result = this.queue.then(async () => {
+            if (this.disposed && name !== "dispose") {
+                throw new Error(`Cannot run ${name}: lifecycle is disposed`);
+            }
+            return operation();
+        });
+        this.queue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}

package/lib/runtime/listener-registry.d.ts

@@ -0,0 +1,7 @@
+export type Unsubscribe = () => void;
+export declare class ListenerRegistry {
+    private readonly listeners;
+    add(owner: string, unsubscribe: Unsubscribe): Unsubscribe;
+    clear(owner: string): void;
+    clearAll(): void;
+}

package/lib/runtime/listener-registry.js

@@ -0,0 +1,40 @@
+export class ListenerRegistry {
+    constructor() {
+        this.listeners = new Map();
+    }
+    add(owner, unsubscribe) {
+        let owned = this.listeners.get(owner);
+        if (!owned) {
+            owned = new Set();
+            this.listeners.set(owner, owned);
+        }
+        owned.add(unsubscribe);
+        return () => {
+            if (!owned.delete(unsubscribe))
+                return;
+            try {
+                unsubscribe();
+            }
+            finally {
+                if (owned.size === 0)
+                    this.listeners.delete(owner);
+            }
+        };
+    }
+    clear(owner) {
+        const owned = this.listeners.get(owner);
+        if (!owned)
+            return;
+        this.listeners.delete(owner);
+        for (const unsubscribe of owned) {
+            try {
+                unsubscribe();
+            }
+            catch { }
+        }
+    }
+    clearAll() {
+        for (const owner of Array.from(this.listeners.keys()))
+            this.clear(owner);
+    }
+}

package/lib/runtime/overlay-options.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_PERMISSION_DENIED_MESSAGE = "\u8BF7\u5148\u6388\u4E88\u60AC\u6D6E\u7A97\u6743\u9650";
+export declare class OverlayPermissionError extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidOverlayIconError extends Error {
+    constructor(message: string);
+}
+export declare function normalizeIconBase64(input: string): string;
+export declare function requireOverlayPermission(granted: boolean, message: string, showToast: (message: string) => void, onToastError?: (error: unknown) => void): void;

package/lib/runtime/overlay-options.js

@@ -0,0 +1,42 @@
+export const DEFAULT_PERMISSION_DENIED_MESSAGE = "请先授予悬浮窗权限";
+export class OverlayPermissionError extends Error {
+    constructor(message = DEFAULT_PERMISSION_DENIED_MESSAGE) {
+        super(message);
+        this.name = "OverlayPermissionError";
+    }
+}
+export class InvalidOverlayIconError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidOverlayIconError";
+    }
+}
+export function normalizeIconBase64(input) {
+    if (typeof input !== "string") {
+        throw new InvalidOverlayIconError("Overlay icon Base64 must be a string");
+    }
+    const trimmed = input.trim();
+    const marker = ";base64,";
+    const markerIndex = trimmed.toLowerCase().indexOf(marker);
+    const payload = markerIndex >= 0
+        ? trimmed.slice(markerIndex + marker.length)
+        : trimmed;
+    const normalized = payload.replace(/\s+/g, "");
+    if (normalized.length === 0
+        || normalized.length % 4 === 1
+        || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+        throw new InvalidOverlayIconError("Overlay icon contains invalid Base64 data");
+    }
+    return normalized;
+}
+export function requireOverlayPermission(granted, message, showToast, onToastError) {
+    if (granted)
+        return;
+    try {
+        showToast(message);
+    }
+    catch (error) {
+        onToastError?.(error);
+    }
+    throw new OverlayPermissionError(message);
+}

package/lib/runtime/safe-runtime.d.ts

@@ -0,0 +1,3 @@
+export type ErrorReporter = (error: Error) => void;
+export declare function safeInvoke<T>(label: string, callback: () => T, report?: ErrorReporter): T | undefined;
+export declare function deferSafe(label: string, callback: () => void, report?: ErrorReporter): void;

package/lib/runtime/safe-runtime.js

@@ -0,0 +1,20 @@
+import { Logger } from "../logger.js";
+function contextualError(label, cause) {
+    const detail = cause instanceof Error ? cause.stack || cause.message : String(cause);
+    return new Error(`${label}: ${detail}`);
+}
+function defaultReporter(error) {
+    Logger.instance.error(error);
+}
+export function safeInvoke(label, callback, report = defaultReporter) {
+    try {
+        return callback();
+    }
+    catch (cause) {
+        report(contextualError(label, cause));
+        return undefined;
+    }
+}
+export function deferSafe(label, callback, report = defaultReporter) {
+    setTimeout(() => safeInvoke(label, callback, report), 0);
+}

package/lib/utils.d.ts

@@ -0,0 +1,8 @@
+export declare function windowToLogical(wx: number, wy: number, w: number, h: number): {
+    x: number;
+    y: number;
+};
+export declare function logicalToWindow(lx: number, ly: number, w: number, h: number): {
+    x: number;
+    y: number;
+};

package/lib/utils.js

@@ -0,0 +1,13 @@
+import { ConstantConfig } from "./constant-config.js";
+export function windowToLogical(wx, wy, w, h) {
+    return {
+        x: Math.round(wx + (ConstantConfig.screenWidth - w) / 2),
+        y: Math.round(wy + (ConstantConfig.screenHeight - h) / 2),
+    };
+}
+export function logicalToWindow(lx, ly, w, h) {
+    return {
+        x: Math.round(lx - (ConstantConfig.screenWidth - w) / 2),
+        y: Math.round(ly - (ConstantConfig.screenHeight - h) / 2),
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "frida-ui-runtime",
+  "version": "2.0.0",
+  "description": "Lifecycle-safe Android UI runtime for Frida scripts",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "frida-compile example.ts -o example.js -w",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "tsc --noEmit && node --test tests/*.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Matchman33/frida-ui-runtime"
+  },
+  "keywords": [
+    "frida",
+    "android",
+    "ui",
+    "floating-window",
+    "overlay",
+    "hooking"
+  ],
+  "peerDependencies": {
+    "frida-java-bridge": "*"
+  },
+  "devDependencies": {
+    "@types/frida-gum": "^19.0.1",
+    "@types/node": "^24.0.10",
+    "frida-compile": "^19.0.4",
+    "frida-java-bridge": "7.0.4",
+    "typescript": "^5.0.0"
+  }
+}