@lynx-js/react 0.120.0 → 0.121.1

package/runtime/lib/element-template/background/instance.js

@@ -0,0 +1,347 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { prepareAttributeSlots as prepareRawAttributeSlots, queueRefAttributeSlotUpdates } from './attr-slots.js';
+import { globalCommitContext, markRemovedSubtreeForPostDispatchTeardown } from './commit-context.js';
+import { isElementTemplateHydrated } from './commit-hook.js';
+import { backgroundElementTemplateInstanceManager } from './manager.js';
+import { isDirectOrDeepEqual } from '../../utils.js';
+import { ElementTemplateUpdateOps } from '../protocol/opcodes.js';
+function pushOp(...items) {
+    globalCommitContext.ops.push(...items);
+}
+export const BUILTIN_RAW_TEXT_TEMPLATE_KEY = '_et_builtin_raw_text';
+function isBuiltinRawTextTemplateKey(type) {
+    return type === BUILTIN_RAW_TEXT_TEMPLATE_KEY;
+}
+function stringifyRawTextValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return '';
+}
+export class BackgroundElementTemplateInstance {
+    instanceId = 0; // Assigned by manager
+    type;
+    parent = null;
+    firstChild = null;
+    lastChild = null;
+    nextSibling = null;
+    previousSibling = null;
+    __slotIndex = 0;
+    // Shadow State for Hydration
+    attributeSlots;
+    rawAttributeSlots;
+    isMaterializedOnMainThread = false;
+    get parentNode() {
+        return this.parent;
+    }
+    get childNodes() {
+        const nodes = [];
+        let child = this.firstChild;
+        while (child) {
+            nodes.push(child);
+            child = child.nextSibling;
+        }
+        return nodes;
+    }
+    get elementSlots() {
+        const elementSlots = [];
+        let child = this.firstChild;
+        while (child) {
+            (elementSlots[child.__slotIndex] ??= []).push(child);
+            child = child.nextSibling;
+        }
+        return elementSlots;
+    }
+    nodeType;
+    constructor(type, initialAttributeSlots) {
+        this.type = type;
+        this.nodeType = isBuiltinRawTextTemplateKey(type) ? 3 : 1;
+        backgroundElementTemplateInstanceManager.register(this);
+        if (initialAttributeSlots) {
+            const preparedSlots = prepareRawAttributeSlots(this.type, this.instanceId, initialAttributeSlots);
+            this.attributeSlots = preparedSlots;
+            if (preparedSlots !== initialAttributeSlots) {
+                this.rawAttributeSlots = initialAttributeSlots;
+            }
+        }
+        else {
+            this.attributeSlots = [];
+        }
+    }
+    emitCreate() {
+        if (this.isMaterializedOnMainThread) {
+            return;
+        }
+        if (this.instanceId === 0 && __DEV__) {
+            lynx.reportError(new Error('ElementTemplate patch has illegal handleId 0.'));
+            return;
+        }
+        // Walk the linked-list children once to build the slot-indexed handle list
+        // for the createTemplate op. Going via `this.elementSlots` would allocate
+        // the full `Instance[][]` intermediate just to throw it away here.
+        const serializedSlots = [];
+        let child = this.firstChild;
+        while (child) {
+            (serializedSlots[child.__slotIndex] ??= []).push(child.instanceId);
+            child = child.nextSibling;
+        }
+        pushOp(ElementTemplateUpdateOps.createTemplate, this.instanceId, this.type, null, this.attributeSlots, serializedSlots);
+        this.isMaterializedOnMainThread = true;
+    }
+    needsMainThreadCreate() {
+        return this.instanceId > 0 && !this.isMaterializedOnMainThread;
+    }
+    emitMainThreadCreateIfNeeded() {
+        if (!this.needsMainThreadCreate()) {
+            return;
+        }
+        // An unmaterialized subtree may receive attr updates before it is inserted;
+        // prepare here so ref attach happens once, at the create boundary.
+        this.prepareAttributeSlotsForNative();
+        this.emitCreate();
+    }
+    canEmitUpdatePatch() {
+        // Background tree construction is local until hydrate binds it to main-thread
+        // instances. Only hydrated and materialized owners can emit update ops.
+        return isElementTemplateHydrated() && !this.needsMainThreadCreate();
+    }
+    // DOM API for Preact
+    appendChild(child) {
+        this.insertBefore(child, null);
+    }
+    insertBefore(child, beforeChild, silent) {
+        if (beforeChild === child) {
+            throw new Error('Cannot insert a node before itself');
+        }
+        if (beforeChild && beforeChild.parent !== this) {
+            throw new Error('Reference node is not a child of this parent');
+        }
+        if (child.parent) {
+            child.parent.removeChild(child, true);
+        }
+        child.parent = this;
+        if (beforeChild) {
+            child.nextSibling = beforeChild;
+            child.previousSibling = beforeChild.previousSibling;
+            if (beforeChild.previousSibling) {
+                beforeChild.previousSibling.nextSibling = child;
+            }
+            else {
+                this.firstChild = child;
+            }
+            beforeChild.previousSibling = child;
+        }
+        else {
+            if (this.lastChild) {
+                this.lastChild.nextSibling = child;
+                child.previousSibling = this.lastChild;
+            }
+            else {
+                this.firstChild = child;
+            }
+            this.lastChild = child;
+            child.nextSibling = null;
+        }
+        if (silent || !this.canEmitUpdatePatch()) {
+            return;
+        }
+        const beforeId = (beforeChild && beforeChild.__slotIndex === child.__slotIndex) ? beforeChild.instanceId : 0;
+        emitMainThreadCreateRecursive(child);
+        pushOp(ElementTemplateUpdateOps.insertNode, this.instanceId, child.__slotIndex, child.instanceId, beforeId);
+    }
+    removeChild(child, silent) {
+        if (child.parent !== this) {
+            throw new Error('Node is not a child of this parent');
+        }
+        if (child.previousSibling) {
+            child.previousSibling.nextSibling = child.nextSibling;
+        }
+        else {
+            this.firstChild = child.nextSibling;
+        }
+        if (child.nextSibling) {
+            child.nextSibling.previousSibling = child.previousSibling;
+        }
+        else {
+            this.lastChild = child.previousSibling;
+        }
+        child.parent = null;
+        child.nextSibling = null;
+        child.previousSibling = null;
+        const slotId = child.__slotIndex;
+        if (silent) {
+            return;
+        }
+        if (this.canEmitUpdatePatch()) {
+            pushOp(ElementTemplateUpdateOps.removeNode, this.instanceId, slotId, child.instanceId, collectElementTemplateSubtreeHandleIds(child));
+            // The removed JS object graph may outlive the detach until GC, so keep
+            // it pending and tear it down on the Snapshot-aligned delayed boundary.
+            markRemovedSubtreeForPostDispatchTeardown(child);
+            child.queueRefCleanupForSubtree();
+        }
+        else {
+            // Mirrors `shouldQueueRefEffects` in `setAttribute`: pre-hydration
+            // commits and post-hydration materialized children publish their refs
+            // to user effects. Post-hydration unmaterialized children defer attach
+            // to `emitCreate`, which never fires for a subtree torn down before
+            // insert — so cleaning up there would emit a spurious detach.
+            const refAttachWasPublished = !isElementTemplateHydrated()
+                || !child.needsMainThreadCreate();
+            if (refAttachWasPublished) {
+                // Run before any tearDown below: `tearDown` clears `rawAttributeSlots`,
+                // which `queueRefCleanupForSubtree` walks to enqueue the detach.
+                child.queueRefCleanupForSubtree();
+            }
+            if (child.needsMainThreadCreate()) {
+                // An unmaterialized subtree has no main-thread registry entry, so it
+                // can be released from the background manager without delayed cleanup.
+                child.tearDown();
+            }
+        }
+    }
+    tearDown() {
+        // Recursively tear down children first
+        let child = this.firstChild;
+        while (child) {
+            const next = child.nextSibling;
+            child.tearDown();
+            child = next;
+        }
+        // Clear references
+        this.parent = null;
+        this.firstChild = null;
+        this.lastChild = null;
+        this.previousSibling = null;
+        this.nextSibling = null;
+        this.attributeSlots = [];
+        this.rawAttributeSlots = undefined;
+        // Remove from manager
+        if (this.instanceId) {
+            backgroundElementTemplateInstanceManager.values.delete(this.instanceId);
+        }
+    }
+    queueRefCleanupForSubtree() {
+        if (this.rawAttributeSlots) {
+            queueRefAttributeSlotUpdates(this.type, this.instanceId, this.rawAttributeSlots);
+        }
+        let child = this.firstChild;
+        while (child) {
+            child.queueRefCleanupForSubtree();
+            child = child.nextSibling;
+        }
+    }
+    getRawAttributeSlot(attrSlotIndex) {
+        return this.rawAttributeSlots?.[attrSlotIndex] ?? this.attributeSlots[attrSlotIndex];
+    }
+    markMaterializedByHydration() {
+        // Hydration binds this object to a template that already exists on the main
+        // thread; future updates must treat it as materialized without emitting create.
+        this.isMaterializedOnMainThread = true;
+    }
+    prepareAttributeSlotsForNative(options) {
+        if (!this.rawAttributeSlots) {
+            return;
+        }
+        this.attributeSlots = prepareRawAttributeSlots(this.type, this.instanceId, this.rawAttributeSlots, {
+            queueRefEffects: options?.queueRefEffects ?? true,
+        });
+    }
+    prepareAttributeSlotsForHydration() {
+        // Hydrate only rebinds the selector marker to the stable handle. The ref was
+        // already made visible to user effects on the pre-hydration commit path.
+        this.prepareAttributeSlotsForNative({
+            queueRefEffects: false,
+        });
+    }
+    setAttribute(key, value) {
+        if (isBuiltinRawTextTemplateKey(this.type) && (key === '0' || key === 'data')) {
+            this.text = String(value);
+        }
+        else if (key === 'attributeSlots' && Array.isArray(value)) {
+            const previousSlots = this.attributeSlots;
+            const previousRawSlots = this.rawAttributeSlots ?? previousSlots;
+            const isHydrated = isElementTemplateHydrated();
+            const canEmitUpdatePatch = isHydrated && !this.needsMainThreadCreate();
+            // Pre-hydration commits must expose refs to effects, while post-hydration
+            // unmaterialized nodes defer ref attach to create emission to avoid dupes.
+            const shouldQueueRefEffects = !isHydrated || canEmitUpdatePatch;
+            const nextSlots = prepareRawAttributeSlots(this.type, this.instanceId, value, {
+                previousRawSlots,
+                queueRefEffects: shouldQueueRefEffects,
+            });
+            this.rawAttributeSlots = nextSlots === value ? undefined : value;
+            const maxLength = Math.max(previousSlots.length, nextSlots.length);
+            this.attributeSlots = nextSlots;
+            for (let slotIndex = 0; slotIndex < maxLength; slotIndex += 1) {
+                const previousValue = previousSlots[slotIndex];
+                const nextValue = nextSlots[slotIndex];
+                if (isDirectOrDeepEqual(previousValue, nextValue)) {
+                    continue;
+                }
+                if (!canEmitUpdatePatch) {
+                    continue;
+                }
+                pushOp(ElementTemplateUpdateOps.setAttribute, this.instanceId, slotIndex, nextValue ?? null);
+            }
+        }
+    }
+    get text() {
+        return stringifyRawTextValue(this.attributeSlots[0]);
+    }
+    set text(value) {
+        if (!isBuiltinRawTextTemplateKey(this.type)) {
+            return;
+        }
+        const text = String(value);
+        if (this.attributeSlots[0] === text) {
+            return;
+        }
+        this.rawAttributeSlots = undefined;
+        this.attributeSlots = [text];
+        if (!this.canEmitUpdatePatch()) {
+            return;
+        }
+        pushOp(ElementTemplateUpdateOps.setAttribute, this.instanceId, 0, text);
+    }
+    get data() {
+        return this.text;
+    }
+    set data(value) {
+        this.text = value;
+    }
+}
+export function collectElementTemplateSubtreeHandleIds(root) {
+    const handles = [];
+    collectElementTemplateSubtreeHandleIdsImpl(root, handles);
+    return handles;
+}
+function collectElementTemplateSubtreeHandleIdsImpl(instance, handles) {
+    if (instance.instanceId !== 0) {
+        handles.push(instance.instanceId);
+    }
+    let child = instance.firstChild;
+    while (child) {
+        collectElementTemplateSubtreeHandleIdsImpl(child, handles);
+        child = child.nextSibling;
+    }
+}
+function emitMainThreadCreateRecursive(instance) {
+    if (!isElementTemplateHydrated()
+        || instance.instanceId < 0) {
+        return;
+    }
+    // Walk children in linked-list order; the slot-grouped view would just be
+    // discarded here since we recurse into every child regardless of slot.
+    let child = instance.firstChild;
+    while (child) {
+        emitMainThreadCreateRecursive(child);
+        child = child.nextSibling;
+    }
+    instance.emitMainThreadCreateIfNeeded();
+}
+//# sourceMappingURL=instance.js.map

package/runtime/lib/element-template/background/instance.js.map

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

package/runtime/lib/element-template/background/manager.d.ts

@@ -0,0 +1,10 @@
+import type { BackgroundElementTemplateInstance } from './instance.js';
+export declare const backgroundElementTemplateInstanceManager: {
+    nextId: number;
+    values: Map<number, BackgroundElementTemplateInstance>;
+    register(instance: BackgroundElementTemplateInstance): void;
+    updateId(oldId: number, newId: number): void;
+    get(id: number): BackgroundElementTemplateInstance | undefined;
+    getRawAttributeValueByEventValue(eventValue: string): unknown;
+    clear(): void;
+};

package/runtime/lib/element-template/background/manager.js

@@ -0,0 +1,60 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export const backgroundElementTemplateInstanceManager = {
+    nextId: 0,
+    values: new Map(),
+    register(instance) {
+        instance.instanceId = this.nextId += 1;
+        this.values.set(instance.instanceId, instance);
+    },
+    updateId(oldId, newId) {
+        if (!Number.isInteger(newId) || newId === 0) {
+            throw new Error(`ElementTemplate handleId must be a non-zero integer, got ${String(newId)}.`);
+        }
+        const instance = this.values.get(oldId);
+        if (!instance) {
+            throw new Error(`ElementTemplate instance ${oldId} is not registered.`);
+        }
+        const existing = this.values.get(newId);
+        if (existing && existing !== instance) {
+            throw new Error(`ElementTemplate handleId ${newId} is already bound.`);
+        }
+        if (oldId === newId) {
+            return;
+        }
+        this.values.delete(oldId);
+        instance.instanceId = newId;
+        this.values.set(newId, instance);
+        // DevTools event emission can be added here later
+        // if (__DEV__) { ... }
+    },
+    get(id) {
+        return this.values.get(id);
+    },
+    getRawAttributeValueByEventValue(eventValue) {
+        const parts = eventValue?.split(':');
+        if (!parts || (parts.length !== 2 && parts.length !== 3)) {
+            throw new Error('Invalid ElementTemplate event value: ' + eventValue);
+        }
+        const instance = this.values.get(Number(parts[0]));
+        if (!instance) {
+            return null;
+        }
+        const value = instance.getRawAttributeSlot(Number(parts[1]));
+        const spreadKey = parts[2];
+        if (!spreadKey) {
+            return value;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return undefined;
+        }
+        return value[spreadKey];
+    },
+    clear() {
+        // Note: nextId is NOT reset to prevent ID collisions with potentially surviving instances
+        // or when the clear is partial/soft reset in some scenarios.
+        this.values.clear();
+    },
+};
+//# sourceMappingURL=manager.js.map

package/runtime/lib/element-template/background/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/element-template/background/manager.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAI1D,MAAM,CAAC,MAAM,wCAAwC,GAQjD;IACF,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,IAAI,GAAG,EAA6C;IAE5D,QAAQ,CAAC,QAA2C;QAClD,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,QAAQ,CAAC,KAAa,EAAE,KAAa;QACnC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,4DAA4D,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAChG,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,qBAAqB,CAAC,CAAC;QAC1E,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,QAAQ,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,oBAAoB,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,QAAQ,CAAC,UAAU,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAEjC,kDAAkD;QAClD,uBAAuB;IACzB,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,gCAAgC,CAAC,UAAkB;QACjD,MAAM,KAAK,GAAG,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,UAAU,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAQ,KAAiC,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,KAAK;QACH,0FAA0F;QAC1F,6DAA6D;QAC7D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF,CAAC"}

package/runtime/lib/element-template/client/root.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import type { DataProcessorDefinition } from '../../lynx-api.js';
+/**
+ * The default root exported by `@lynx-js/react` for you to render a JSX
+ * @public
+ */
+export interface Root {
+    /**
+     * Use this API to pass in your JSX to render
+     *
+     * @example
+     *
+     * ```ts
+     * import { root } from "@lynx-js/react"
+     *
+     * function App() {
+     *   // Your app
+     *   return <view>...</view>
+     * }
+     *
+     * root.render(<App/>);
+     * ```
+     *
+     * @public
+     */
+    render: (jsx: ReactNode) => void;
+    /**
+     * {@inheritDoc Lynx.registerDataProcessors}
+     * @deprecated use {@link Lynx.registerDataProcessors | lynx.registerDataProcessors} instead
+     * @public
+     */
+    registerDataProcessors: (dataProcessorDefinition?: DataProcessorDefinition) => void;
+}
+/**
+ * The default and only root of ReactLynx for you to render JSX
+ * @example
+ * ```ts
+ * import { root } from "@lynx-js/react"
+ * ```
+ *
+ * @public
+ */
+export declare const root: Root;

package/runtime/lib/element-template/client/root.js

@@ -0,0 +1,30 @@
+import { render } from 'preact';
+import { profileEnd, profileStart } from '../debug/profile.js';
+import { __root } from '../runtime/page/root-instance.js';
+/**
+ * The default and only root of ReactLynx for you to render JSX
+ * @example
+ * ```ts
+ * import { root } from "@lynx-js/react"
+ * ```
+ *
+ * @public
+ */
+export const root = {
+    render: (jsx) => {
+        __root.__jsx = jsx;
+        if (__BACKGROUND__) {
+            if (__PROFILE__) {
+                profileStart('ReactLynx::renderBackground');
+            }
+            render(jsx, __root);
+            if (__PROFILE__) {
+                profileEnd();
+            }
+        }
+    },
+    registerDataProcessors: (dataProcessorDefinition) => {
+        lynx.registerDataProcessors(dataProcessorDefinition);
+    },
+};
+//# sourceMappingURL=root.js.map

package/runtime/lib/element-template/client/root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../src/element-template/client/root.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAkC1D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,IAAI,GAAS;IACxB,MAAM,EAAE,CAAC,GAAc,EAAQ,EAAE;QAC/B,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC;QACnB,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,WAAW,EAAE,CAAC;gBAChB,YAAY,CAAC,6BAA6B,CAAC,CAAC;YAC9C,CAAC;YACD,MAAM,CAAC,GAAqB,EAAE,MAAkC,CAAC,CAAC;YAClE,IAAI,WAAW,EAAE,CAAC;gBAChB,UAAU,EAAE,CAAC;YACf,CAAC;QACH,CAAC;IACH,CAAC;IACD,sBAAsB,EAAE,CAAC,uBAAiD,EAAQ,EAAE;QAClF,IAAI,CAAC,sBAAsB,CAAC,uBAAuB,CAAC,CAAC;IACvD,CAAC;CACF,CAAC"}

package/runtime/lib/element-template/debug/alog.d.ts

@@ -0,0 +1,41 @@
+import type { BackgroundElementTemplateInstance } from '../background/instance.js';
+import type { ElementTemplateUpdateCommandStream } from '../protocol/types.js';
+export type FormattedElementTemplateUpdateCommand = {
+    op: 'createTemplate';
+    handleId: number;
+    templateKey: string;
+    bundleUrl: string | null | undefined;
+    attributeSlots: unknown;
+    elementSlots: unknown;
+} | {
+    op: 'createTypedElement';
+    handleId: number;
+    type: string;
+    attributes: unknown;
+    elementSlots: unknown;
+    options: unknown;
+} | {
+    op: 'setAttribute';
+    targetId: number;
+    attrSlotIndex: number;
+    value: unknown;
+} | {
+    op: 'insertNode';
+    targetId: number;
+    elementSlotIndex: number;
+    childId: number;
+    referenceId: number;
+} | {
+    op: 'removeNode';
+    targetId: number;
+    elementSlotIndex: number;
+    childId: number;
+    removedSubtreeHandleIds: number[];
+} | {
+    op: 'unknown';
+    opcode: unknown;
+    index: number;
+    remaining: unknown[];
+};
+export declare function formatElementTemplateUpdateCommands(stream: ElementTemplateUpdateCommandStream | undefined): FormattedElementTemplateUpdateCommand[];
+export declare function printElementTemplateTreeToString(root: BackgroundElementTemplateInstance | null | undefined): string;

package/runtime/lib/element-template/debug/alog.js

@@ -0,0 +1,103 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { ElementTemplateUpdateOps } from '../protocol/opcodes.js';
+export function formatElementTemplateUpdateCommands(stream) {
+    if (!Array.isArray(stream)) {
+        return [];
+    }
+    const result = [];
+    for (let index = 0; index < stream.length;) {
+        const opIndex = index;
+        const op = stream[index++];
+        switch (op) {
+            case ElementTemplateUpdateOps.createTemplate:
+                result.push({
+                    op: 'createTemplate',
+                    handleId: stream[index++],
+                    templateKey: stream[index++],
+                    bundleUrl: stream[index++],
+                    attributeSlots: stream[index++],
+                    elementSlots: stream[index++],
+                });
+                break;
+            case ElementTemplateUpdateOps.setAttribute:
+                result.push({
+                    op: 'setAttribute',
+                    targetId: stream[index++],
+                    attrSlotIndex: stream[index++],
+                    value: stream[index++],
+                });
+                break;
+            case ElementTemplateUpdateOps.createTypedElement:
+                result.push({
+                    op: 'createTypedElement',
+                    handleId: stream[index++],
+                    type: stream[index++],
+                    attributes: stream[index++],
+                    elementSlots: stream[index++],
+                    options: stream[index++],
+                });
+                break;
+            case ElementTemplateUpdateOps.insertNode:
+                result.push({
+                    op: 'insertNode',
+                    targetId: stream[index++],
+                    elementSlotIndex: stream[index++],
+                    childId: stream[index++],
+                    referenceId: stream[index++],
+                });
+                break;
+            case ElementTemplateUpdateOps.removeNode:
+                result.push({
+                    op: 'removeNode',
+                    targetId: stream[index++],
+                    elementSlotIndex: stream[index++],
+                    childId: stream[index++],
+                    removedSubtreeHandleIds: stream[index++],
+                });
+                break;
+            default:
+                result.push({
+                    op: 'unknown',
+                    opcode: op,
+                    index: opIndex,
+                    remaining: stream.slice(index),
+                });
+                index = stream.length;
+                break;
+        }
+    }
+    return result;
+}
+export function printElementTemplateTreeToString(root) {
+    if (!root) {
+        return '<empty>';
+    }
+    const lines = [];
+    appendInstance(lines, root, 0);
+    return lines.join('\n');
+}
+function appendInstance(lines, instance, depth) {
+    const indent = '  '.repeat(depth);
+    const type = instance.type ?? '<unknown>';
+    const instanceId = instance.instanceId ?? '<unknown>';
+    lines.push(`${indent}${type}#${instanceId}`);
+    if (Array.isArray(instance.attributeSlots) && instance.attributeSlots.length > 0) {
+        lines.push(`${indent}  attributeSlots: ${JSON.stringify(instance.attributeSlots)}`);
+    }
+    const elementSlots = Array.isArray(instance.elementSlots) ? instance.elementSlots : [];
+    for (let slotIndex = 0; slotIndex < elementSlots.length; slotIndex += 1) {
+        const children = elementSlots[slotIndex];
+        if (!children || children.length === 0) {
+            continue;
+        }
+        lines.push(`${indent}  elementSlots[${slotIndex}]: [${children.map(child => child.instanceId).join(', ')}]`);
+    }
+    let child = instance.firstChild;
+    while (child) {
+        appendInstance(lines, child, depth + 1);
+        child = child.nextSibling;
+    }
+}
+//# sourceMappingURL=alog.js.map