@sigx/lynx-runtime 0.2.6 → 0.4.1

package/dist/op-queue.js

@@ -0,0 +1,213 @@
+/**
+ * Op queue — accumulates renderer ops on the Background Thread and flushes
+ * them to the Main Thread via the Lynx host bridge.
+ *
+ * The bridge identifiers `lynx` and `lynxCoreInject` are NOT on globalThis.
+ * They are injected as closure parameters by RuntimeWrapperWebpackPlugin
+ * (peer dep `@lynx-js/runtime-wrapper-webpack-plugin`), which wraps the BG
+ * bundle in `__init_card_bundle__(lynxCoreInject, lynx, ...)`. Once wrapped,
+ * any module in the bundle can reference them as bare identifiers.
+ *
+ */
+export { OP } from '@sigx/lynx-runtime-internal';
+// ---------------------------------------------------------------------------
+// Ambient declarations for the closure-injected host bridge identifiers
+// ---------------------------------------------------------------------------
+// `lynx` and `lynxCoreInject` are declared in src/shims.d.ts as the
+// single source of truth for closure-injected identifiers from
+// runtime-wrapper-webpack-plugin. Both are typed as `any` since their
+// shape varies by host — call sites guard with typeof checks.
+// ---------------------------------------------------------------------------
+// Op buffer
+// ---------------------------------------------------------------------------
+let buffer = [];
+/**
+ * Push one op (opcode + arguments) into the buffer as a flat sequence.
+ * Example: pushOp(OP.CREATE, id, type) → buffer gets [0, id, type].
+ */
+export function pushOp(...args) {
+    for (const arg of args) {
+        buffer.push(arg);
+    }
+}
+/** Take all buffered ops and reset the buffer. */
+export function takeOps() {
+    const b = buffer;
+    buffer = [];
+    return b;
+}
+// ---------------------------------------------------------------------------
+// Scheduling
+// ---------------------------------------------------------------------------
+let scheduled = false;
+/**
+ * Schedule a flush of the ops buffer at the end of the current microtask.
+ * Multiple calls within one tick are coalesced into one cross-thread call.
+ */
+export function scheduleFlush() {
+    if (scheduled)
+        return;
+    scheduled = true;
+    Promise.resolve().then(doFlush);
+}
+/**
+ * Immediately flush all buffered ops — used on initial mount so the first
+ * frame is committed synchronously.
+ */
+export function flushNow() {
+    scheduled = false;
+    const ops = takeOps();
+    if (ops.length === 0)
+        return;
+    sendOps(ops);
+}
+/** Reset module state — for testing only. */
+export function resetOpQueue() {
+    buffer = [];
+    scheduled = false;
+    pendingAckResolve = null;
+    pendingAckPromise = null;
+}
+function doFlush() {
+    scheduled = false;
+    const ops = takeOps();
+    if (ops.length === 0)
+        return;
+    sendOps(ops);
+}
+// ---------------------------------------------------------------------------
+// Main-thread ack tracking
+//
+// callLepusMethod is asynchronous: by the time the BG flush cycle finishes,
+// the MT has not yet applied the ops. Track a promise that resolves when the
+// MT acks via the callback so callers can `await waitForFlush()` if they need
+// to coordinate with the next-tick UI state.
+// ---------------------------------------------------------------------------
+let pendingAckResolve = null;
+let pendingAckPromise = null;
+/**
+ * Resolves once the most recent ops batch has been applied on the main
+ * thread. If no ops are in flight, resolves immediately.
+ */
+export function waitForFlush() {
+    return pendingAckPromise ?? Promise.resolve();
+}
+// ---------------------------------------------------------------------------
+// Transport (BG → MT)
+// ---------------------------------------------------------------------------
+function sendOps(ops) {
+    const data = JSON.stringify(ops);
+    // Create the ack promise BEFORE sending so any waitForFlush() chained
+    // immediately after this call observes the in-flight batch.
+    pendingAckPromise = new Promise((resolve) => {
+        pendingAckResolve = resolve;
+    });
+    // Primary path: closure-injected `lynx` from RuntimeWrapperWebpackPlugin.
+    if (typeof lynx !== 'undefined') {
+        const app = lynx?.getNativeApp?.();
+        if (app && typeof app.callLepusMethod === 'function') {
+            app.callLepusMethod('sigxPatchUpdate', { data }, () => {
+                pendingAckResolve?.();
+                pendingAckResolve = null;
+                pendingAckPromise = null;
+            });
+            return;
+        }
+    }
+    // Same-thread fallback for unit tests where BG and MT share globalThis.
+    const g = globalThis;
+    if (typeof g['sigxPatchUpdate'] === 'function') {
+        g['sigxPatchUpdate']({ data });
+        pendingAckResolve?.();
+        pendingAckResolve = null;
+        pendingAckPromise = null;
+        return;
+    }
+    // No bridge available — drop and resolve so callers don't hang. This path
+    // indicates the bundle wasn't wrapped by RuntimeWrapperWebpackPlugin.
+    console.log('[sigx-bg] sendOps: no `lynx` global injected — bundle is missing RuntimeWrapperWebpackPlugin');
+    pendingAckResolve?.();
+    pendingAckResolve = null;
+    pendingAckPromise = null;
+}
+// ---------------------------------------------------------------------------
+// Hot reload signal (BG → MT)
+//
+// Sent before a webpack HMR update replaces the BG module, so the MT resets
+// its element registry and page root before the new ops batch arrives.
+// ---------------------------------------------------------------------------
+/**
+ * Tell the Main Thread to reset its element tree in preparation for a hot
+ * reload. The MT handler (`sigxHotReload`) calls `resetMainThreadState()`,
+ * re-creates the page root, and flushes — so the next `sigxPatchUpdate`
+ * batch builds on a clean tree.
+ *
+ * This is fire-and-forget: callLepusMethod messages are ordered, so
+ * sigxHotReload will be processed before any subsequent sigxPatchUpdate.
+ */
+export function sendHotReloadSignal() {
+    // Primary path: closure-injected `lynx` from RuntimeWrapperWebpackPlugin.
+    if (typeof lynx !== 'undefined') {
+        const app = lynx?.getNativeApp?.();
+        if (app && typeof app.callLepusMethod === 'function') {
+            app.callLepusMethod('sigxHotReload', {}, () => { });
+            return;
+        }
+    }
+    // Same-thread fallback for testing where BG and MT share globalThis.
+    const g = globalThis;
+    if (typeof g['sigxHotReload'] === 'function') {
+        g['sigxHotReload']();
+    }
+}
+// ---------------------------------------------------------------------------
+// Event dispatch (MT → BG)
+//
+// The Lynx host calls `lynxCoreInject.tt.publishEvent(sign, data)` (and
+// `publicComponentEvent(cid, sign, data)`) when an event fires on the
+// Main Thread. We install our dispatcher there once at module load.
+// ---------------------------------------------------------------------------
+/**
+ * Look up a sign in __SIGX_LYNX_EVENT_REGISTRY__ and invoke the registered
+ * handler. The registry is populated by lynx-runtime's patchProp branch
+ * whenever the renderer sees a `bindtap` / `onTap` / etc. prop.
+ */
+function dispatchEvent(sign, evt) {
+    try {
+        const registry = globalThis.__SIGX_LYNX_EVENT_REGISTRY__;
+        if (!registry?.handlers || sign == null)
+            return;
+        const handlers = registry.handlers;
+        const fn = handlers instanceof Map
+            ? handlers.get(String(sign))
+            : handlers[String(sign)];
+        if (typeof fn === 'function')
+            fn(evt);
+    }
+    catch (e) {
+        console.log('[sigx-bg] event dispatch threw:', String(e));
+    }
+}
+/**
+ * Install our event dispatcher on `lynxCoreInject.tt` — the official place
+ * the Lynx host calls when it forwards Main Thread events to the BG.
+ *
+ * Idempotent. Called from render.ts on module load and from lynxMount() as
+ * a defensive re-install in case the host swaps the tt namespace between
+ * card loads.
+ */
+export function installEventPublisher() {
+    // Primary install path — the canonical Lynx integration point.
+    if (typeof lynxCoreInject !== 'undefined' && lynxCoreInject?.tt) {
+        lynxCoreInject.tt.publishEvent = dispatchEvent;
+        lynxCoreInject.tt.publicComponentEvent = (_cid, sign, data) => dispatchEvent(sign, data);
+    }
+    // Fallback for older Lynx SDKs that look at globalThis.publishEvent.
+    const g = globalThis;
+    if (typeof g['publishEvent'] !== 'function') {
+        g['publishEvent'] = dispatchEvent;
+    }
+    if (typeof g['publicComponentEvent'] !== 'function') {
+        g['publicComponentEvent'] = ((_cid, sign, data) => dispatchEvent(sign, data));
+    }
+}

package/dist/render.js

@@ -0,0 +1,125 @@
+/**
+ * Lynx renderer entry -- creates the renderer, defines lynxMount, and
+ * registers it as the default mount via setDefaultMount.
+ *
+ * Ported pattern from packages/runtime-terminal/src/index.ts
+ */
+import { createRenderer, setDefaultMount } from '@sigx/runtime-core/internals';
+import { nodeOps } from './nodeOps.js';
+import { flushNow } from './flush.js';
+import { installEventPublisher } from './op-queue.js';
+import { createPageRoot } from './shadow-element.js';
+// Install host-required event stubs (publishEvent / publicComponentEvent)
+// before sigx mounts anything so the first MT → BG dispatch doesn't crash.
+installEventPublisher();
+// ---------------------------------------------------------------------------
+// Renderer
+// ---------------------------------------------------------------------------
+const renderer = createRenderer(nodeOps);
+export const { render } = renderer;
+// ---------------------------------------------------------------------------
+// lynxMount -- MountFn for Lynx environments
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// HMR mount state — tracked so hot reloads can tear down and re-mount
+// ---------------------------------------------------------------------------
+let _hmrMounted = false;
+let _hmrRoot = null;
+let _hmrAppContext = undefined;
+/**
+ * Mount function for Lynx environments.
+ *
+ * The page root is a ShadowElement with id=1 — the Main Thread creates the
+ * real page element in renderPage() before the BG thread runs. All subsequent
+ * ops reference this root by id so the MT can resolve it.
+ *
+ * On subsequent calls (hot reload), the previous tree is torn down and the
+ * Main Thread is signalled to reset before the new tree is mounted.
+ *
+ * @example
+ * ```tsx
+ * import '@sigx/lynx-runtime'; // side-effect: registers lynxMount
+ * import { defineApp } from '@sigx/sigx';
+ *
+ * defineApp(<App />).mount();
+ * ```
+ */
+export const lynxMount = (element, _container, appContext) => {
+    // Re-install in case the per-card app instance only became available
+    // after this module's top-level executed (timing varies by Lynx host).
+    installEventPublisher();
+    // Hot-reload fallback: if lynxMount is called again (e.g., main.tsx
+    // re-executed because a non-component module change bubbled up), the
+    // Lynx native engine cannot handle structural tree mutations. Fall
+    // back to a full card reload. With component-level HMR active, this
+    // path is only reached for non-component changes.
+    // See docs/hmr-investigation.md for details.
+    if (_hmrMounted && _hmrRoot) {
+        console.log('[sigx-hmr] Non-component change — triggering full card reload');
+        triggerLiveReload();
+        return () => { };
+    }
+    _hmrMounted = true;
+    const root = createPageRoot();
+    _hmrRoot = root;
+    _hmrAppContext = appContext;
+    render(element, root, appContext);
+    flushNow();
+    return () => {
+        render(null, root, appContext);
+        flushNow();
+        _hmrMounted = false;
+        _hmrRoot = null;
+    };
+};
+// ---------------------------------------------------------------------------
+// Register as the default mount -- activated only when this module is imported
+// ---------------------------------------------------------------------------
+setDefaultMount(lynxMount);
+// ---------------------------------------------------------------------------
+// Live-reload fallback
+//
+// When a webpack HMR update cannot be applied (module shape changed too
+// drastically), fall back to reloading the entire card bundle — the Lynx
+// equivalent of a browser full-page refresh.
+// ---------------------------------------------------------------------------
+/**
+ * Trigger a full card reload via the Lynx host. Tries several host APIs
+ * in order of preference:
+ * 1. `lynxCoreInject.tt.reloadCard()` — standard Lynx host reload
+ * 2. `lynx.getNativeApp().callLepusMethod('sigxReloadCard', ...)` — custom
+ *    reload signal the host can implement
+ * If none are available, logs a warning — the developer must manually reload.
+ */
+function triggerLiveReload() {
+    try {
+        // Option 1: lynxCoreInject.tt.reloadCard (available in some Lynx hosts)
+        if (typeof lynxCoreInject !== 'undefined' && lynxCoreInject?.tt) {
+            const reloadCard = lynxCoreInject.tt['reloadCard'];
+            if (typeof reloadCard === 'function') {
+                reloadCard();
+                return;
+            }
+        }
+        // Option 2: signal via callLepusMethod so the MT can trigger a reload
+        if (typeof lynx !== 'undefined') {
+            const app = lynx?.getNativeApp?.();
+            if (app && typeof app.callLepusMethod === 'function') {
+                app.callLepusMethod('sigxReloadCard', {}, () => { });
+                return;
+            }
+        }
+        console.log('[sigx-hmr] No reload API available. Please manually reload the card.');
+    }
+    catch (e) {
+        console.log('[sigx-hmr] triggerLiveReload error:', String(e));
+    }
+}
+if (typeof module !== 'undefined' && module?.hot) {
+    module.hot.accept((err) => {
+        if (err) {
+            console.log('[sigx-hmr] Hot update failed, falling back to live reload:', String(err));
+            triggerLiveReload();
+        }
+    });
+}

package/dist/run-on-background.d.ts

@@ -32,6 +32,6 @@ interface WorkletCtx {
 }
 export declare function transformToWorklet(fn: (...args: unknown[]) => unknown): JsFnHandle;
 export declare function registerWorkletCtx(ctx: WorkletCtx): void;
-export declare function runOnBackground<R, Fn extends (...args: never[]) => R>(_fn: Fn): (...args: Parameters<Fn>) => Promise<R>;
+export declare function runOnBackground<R, Fn extends (...args: never[]) => R>(fn: Fn): (...args: Parameters<Fn>) => Promise<R>;
 export declare function resetRunOnBackgroundState(): void;
 export {};

package/dist/run-on-background.js

@@ -0,0 +1,201 @@
+/**
+ * runOnBackground — BG-side wiring for the MT→BG cross-thread call channel.
+ *
+ * Two responsibilities:
+ *  1. `transformToWorklet(fn)` — wraps a BG function as a `JsFnHandle`
+ *     `{ _jsFnId, _fn }` so the SWC transform can serialise it into the
+ *     `_jsFn` slot of a worklet ctx. The BG worklet-loader emits inline
+ *     `transformToWorklet(...)` calls when the user writes `runOnBackground(fn)`
+ *     inside a `'main thread'` body.
+ *  2. `Lynx.Sigx.RunOnBackground` listener — when the MT-side dispatcher
+ *     fires, finds the matching JsFnHandle by `(execId, fnId)` from the
+ *     registered worklet ctxs, runs `_fn(...params)`, dispatches
+ *     `Lynx.Sigx.FunctionCallRet` back with `{resolveId, returnValue}`.
+ *
+ * Mirrors @lynx-js/react/runtime/lib/worklet/call/runOnBackground +
+ * vue-lynx's run-on-background.ts (same protocol shape, sigx-namespaced
+ * event types).
+ */
+const RUN_ON_BACKGROUND = 'Lynx.Sigx.RunOnBackground';
+const FUNCTION_CALL_RET = 'Lynx.Sigx.FunctionCallRet';
+// ---------------------------------------------------------------------------
+// transformToWorklet — mint a JsFnHandle for cross-thread dispatch
+//
+// The SWC JS pass emits inline `transformToWorklet(fn)` calls in the BG bundle
+// when it sees `runOnBackground(fn)` inside a `'main thread'` body. The handle
+// flows into the worklet ctx's `_jsFn` slot; MT extracts it and dispatches via
+// `runOnBackground(handle)(...args)`.
+// ---------------------------------------------------------------------------
+let lastJsFnId = 0;
+export function transformToWorklet(fn) {
+    const id = ++lastJsFnId;
+    if (typeof fn !== 'function') {
+        return {
+            _jsFnId: id,
+            _error: `Argument of runOnBackground should be a function, got [${typeof fn}]`,
+        };
+    }
+    // Stamp toJSON so JSON.stringify of the worklet ctx replaces the function
+    // body with a placeholder string — MT only needs `_jsFnId`/`_execId`.
+    fn.toJSON ??= () => '[BackgroundFunction]';
+    return { _jsFnId: id, _fn: fn };
+}
+// ---------------------------------------------------------------------------
+// IndexMap — auto-incrementing Map (worklet exec-id allocator)
+// ---------------------------------------------------------------------------
+class IndexMap {
+    lastIndex = 0;
+    map = new Map();
+    add(value) {
+        const id = ++this.lastIndex;
+        this.map.set(id, value);
+        return id;
+    }
+    get(index) {
+        return this.map.get(index);
+    }
+    remove(index) {
+        this.map.delete(index);
+    }
+}
+class WorkletExecIdMap extends IndexMap {
+    add(worklet) {
+        const execId = super.add(worklet);
+        worklet._execId = execId;
+        return execId;
+    }
+    findJsFnHandle(execId, fnId) {
+        const worklet = this.get(execId);
+        if (!worklet)
+            return undefined;
+        const visited = new Set();
+        const search = (value) => {
+            if (value === null || typeof value !== 'object')
+                return undefined;
+            const obj = value;
+            if (visited.has(obj))
+                return undefined;
+            visited.add(obj);
+            if ('_jsFnId' in obj && obj['_jsFnId'] === fnId) {
+                return obj;
+            }
+            for (const key in obj) {
+                const result = search(obj[key]);
+                if (result)
+                    return result;
+            }
+            return undefined;
+        };
+        return search(worklet);
+    }
+}
+// ---------------------------------------------------------------------------
+// Module state — lazy-init so SSR / tests don't pay for the listener wiring
+// ---------------------------------------------------------------------------
+let execIdMap;
+function getCoreContext() {
+    if (typeof lynx === 'undefined')
+        return undefined;
+    const obj = lynx;
+    return typeof obj.getCoreContext === 'function' ? obj.getCoreContext() : undefined;
+}
+function init() {
+    execIdMap = new WorkletExecIdMap();
+    const ctx = getCoreContext();
+    ctx?.addEventListener?.(RUN_ON_BACKGROUND, runJSFunction);
+}
+// ---------------------------------------------------------------------------
+// registerWorkletCtx — stamp _execId on outgoing worklet ctxs
+//
+// Called from nodeOps.patchProp (SET_WORKLET_EVENT path) and from
+// runOnMainThread before shipping a ctx across threads. Must run BEFORE
+// JSON.stringify so the ctx carries `_execId` to MT.
+// ---------------------------------------------------------------------------
+export function registerWorkletCtx(ctx) {
+    if (!execIdMap)
+        init();
+    execIdMap.add(ctx);
+}
+function runJSFunction(event) {
+    let data;
+    try {
+        data = JSON.parse(event.data);
+    }
+    catch {
+        return; // malformed bridge message — drop
+    }
+    const handle = execIdMap?.findJsFnHandle(data.obj._execId, data.obj._jsFnId);
+    if (!handle?._fn) {
+        // Fn is gone — likely the owning worklet ctx was unregistered. Resolve
+        // with undefined so the MT promise doesn't hang.
+        dispatchReturn(data.resolveId, undefined);
+        return;
+    }
+    let returnValue;
+    try {
+        returnValue = handle._fn(...data.params);
+    }
+    catch (e) {
+        dispatchReturn(data.resolveId, undefined);
+        throw e;
+    }
+    // Promise return values are not transferable across the JSON bridge — caller
+    // must await on the BG fn body itself if they need async results.
+    dispatchReturn(data.resolveId, returnValue);
+}
+function dispatchReturn(resolveId, returnValue) {
+    const ctx = getCoreContext();
+    ctx?.dispatchEvent?.({
+        type: FUNCTION_CALL_RET,
+        data: JSON.stringify({ resolveId, returnValue }),
+    });
+}
+// ---------------------------------------------------------------------------
+// User-facing entry point.
+//
+// SWC's BG-target worklet pass replaces every `runOnBackground(fn)` call
+// inside a `'main thread'` body with a `transformToWorklet(fn)` placeholder
+// at build time, so on the Background Thread bundle this function is normally
+// only reached from outside a worklet (a misuse) and throws.
+//
+// On the Main Thread bundle the LEPUS pass *also* emits a bare
+// `runOnBackground(handle)` call inside the registered worklet body. The
+// `handle` there is a `JsFnHandle` (an object with `_jsFnId` / `_execId`
+// stamped by `transformToWorklet` on the BG side and ferried across the
+// SET_WORKLET_EVENT bridge). The call resolves to the module-level import
+// of `runOnBackground` (this function), NOT to the MT-side dispatcher
+// that `@sigx/lynx-runtime-main` installs on `globalThis.runOnBackground`
+// during bootstrap. Without a hand-off, MT worklets would always hit the
+// throw.
+//
+// Bridge: when the argument is handle-shaped AND `globalThis.runOnBackground`
+// exists and is a different function (the MT-side dispatcher installed by
+// `entry-main.ts`), delegate to it. Raw functions (real misuse — calling
+// `runOnBackground(someFn)` outside a worklet body) still throw, so the
+// API contract surfaces a useful error instead of silently resolving to
+// `undefined`. On BG the global is never installed, so the throw remains
+// the fallback path. Upstream `@lynx-js/react` achieves the same split
+// via a build-time `__JS__` define; the runtime check here keeps us off
+// that machinery while producing identical end-state behaviour.
+// ---------------------------------------------------------------------------
+function isJsFnHandle(value) {
+    return typeof value === 'object' && value !== null && '_jsFnId' in value;
+}
+export function runOnBackground(fn) {
+    if (isJsFnHandle(fn)) {
+        const g = globalThis;
+        if (typeof g.runOnBackground === 'function' && g.runOnBackground !== runOnBackground) {
+            return g.runOnBackground(fn);
+        }
+    }
+    throw new Error('runOnBackground() can only be used inside \'main thread\' functions. '
+        + 'The SWC worklet transform should replace this call at build time — '
+        + 'verify @sigx/lynx-plugin\'s worklet-loader is wired into your bundler.');
+}
+// ---------------------------------------------------------------------------
+// Reset — for testing only
+// ---------------------------------------------------------------------------
+export function resetRunOnBackgroundState() {
+    execIdMap = undefined;
+    lastJsFnId = 0;
+}

package/dist/shadow-element.js

@@ -0,0 +1,91 @@
+/**
+ * ShadowElement: a lightweight doubly-linked tree node that lives entirely in
+ * the Background Thread. It lets the renderer call parentNode() / nextSibling()
+ * synchronously, while the real Lynx elements exist only on the Main Thread.
+ *
+ * id=1 is reserved for the page root (created via __CreatePage on Main Thread).
+ * Regular elements start from id=2.
+ */
+export class ShadowElement {
+    static nextId = 2; // 1 is reserved for the page root
+    id;
+    type;
+    parent = null;
+    firstChild = null;
+    lastChild = null;
+    prev = null;
+    next = null;
+    // Cached style object (last value passed to patchProp 'style').
+    // Used by vShow to merge display:none without losing the original styles.
+    _style = {};
+    // Set to true by vShow when the element should be hidden.
+    _vShowHidden = false;
+    // Class management for Transition support.
+    _baseClass = '';
+    _transitionClasses = new Set();
+    constructor(type, forceId) {
+        this.id = forceId !== undefined ? forceId : ShadowElement.nextId++;
+        this.type = type;
+    }
+    insertBefore(child, anchor) {
+        // Detach from current parent first
+        if (child.parent) {
+            child.parent.removeChild(child);
+        }
+        child.parent = this;
+        if (anchor) {
+            // Insert before anchor
+            const prev = anchor.prev;
+            child.next = anchor;
+            child.prev = prev;
+            anchor.prev = child;
+            if (prev) {
+                prev.next = child;
+            }
+            else {
+                this.firstChild = child;
+            }
+        }
+        else {
+            // Append at end
+            if (this.lastChild) {
+                this.lastChild.next = child;
+                child.prev = this.lastChild;
+            }
+            else {
+                this.firstChild = child;
+                child.prev = null;
+            }
+            this.lastChild = child;
+            child.next = null;
+        }
+    }
+    removeChild(child) {
+        const prev = child.prev;
+        const next = child.next;
+        if (prev) {
+            prev.next = next;
+        }
+        else {
+            this.firstChild = next;
+        }
+        if (next) {
+            next.prev = prev;
+        }
+        else {
+            this.lastChild = prev;
+        }
+        child.parent = null;
+        child.prev = null;
+        child.next = null;
+    }
+}
+export const PAGE_ROOT_ID = 1;
+/** Create the page root shadow element with the reserved id=1. */
+export function createPageRoot() {
+    return new ShadowElement('page', PAGE_ROOT_ID);
+}
+/** Reset the ID counter — for testing only. */
+export function resetShadowState() {
+    ShadowElement.nextId = 2;
+}