mithril-lynx 0.0.9 → 2.0.0

package/internal/virtual-node.js

@@ -1,388 +0,0 @@
-// internal/virtual-node.js
-//
-// Background-thread-only "virtual" mirror of LynxNodeWrapper/LynxStyleProxy
-// (src/lynx-mithril-shim.js). Implements the EXACT SAME duck-typed DOM
-// surface Mithril's render.js needs (per ../CONTRACT.md) — createElement,
-// appendChild, style, addEventListener, etc — but backed by a plain-JS
-// shadow tree instead of real Element PAPI calls, since the background
-// thread has no PAPI access at all.
-//
-// Every node gets a unique `vid` (vid 0 is reserved for the page root, by
-// convention shared with renderer/main-thread.js — no handshake needed).
-// Every WRITE emits a serializable op addressed by vid; ops describe the
-// SAME method calls a real LynxNodeWrapper would receive (createElement,
-// appendChild, setProp, setAttribute, setStyleProps, ...), so
-// renderer/main-thread.js's applyPatch() can replay them by calling those
-// exact methods on real LynxNodeWrapper instances — no PAPI-mapping logic
-// is duplicated here; the real wrapper's own (already-tested) setters do
-// that mapping on replay.
-//
-// Because the render algorithm (factory() in the shim) is UNMODIFIED and
-// only ever talks to `dom.*` methods generically, this file is a complete,
-// independent implementation of the wrapper contract — it does not import
-// or extend the real LynxNodeWrapper.
-
-"use strict"
-
-var DIRECT_PROPS = ["value", "checked", "selectedIndex", "className", "id", "type"]
-
-function camelize(str) {
-	return str.replace(/-([a-z])/g, function (m, c) { return c.toUpperCase() })
-}
-
-// Mirrors the real LynxStyleProxy's registry exactly: render.js sometimes
-// writes a style property via plain camelCase assignment
-// (`element.style.fontSize = "20px"`) with no prior setProperty() call, so
-// no accessor exists yet to trigger a flush on write. Flushing every
-// registered proxy at the end of a render/redraw pass (mirroring the real
-// shim's flushTree(), see createVirtualDocument's returned flushStyleProxies)
-// is the safety net that catches those. The registry is scoped to one
-// createVirtualDocument() call (passed in as `register`), not module-level —
-// a real app only ever creates one document, but this keeps independent
-// virtual trees (as in tests) from leaking proxies into each other.
-function VirtualStyleProxy(wrapper, register) {
-	this._wrapper = wrapper
-	this._props = {}
-	register(this)
-}
-
-VirtualStyleProxy.prototype._flush = function () {
-	var styles = {}
-	var keys = Object.keys(this)
-	for (var i = 0; i < keys.length; i++) {
-		var key = keys[i]
-		if (key === "_wrapper" || key === "_props") continue
-		var value = this[key]
-		if (value == null) continue
-		styles[camelize(key)] = String(value)
-	}
-	this._wrapper._emit({ op: "setStyleProps", vid: this._wrapper._vid, styles: styles })
-}
-
-VirtualStyleProxy.prototype.setProperty = function (name, value) {
-	var key = camelize(name)
-	if (value == null || value === "") {
-		this.removeProperty(name)
-		return
-	}
-	var self = this
-	if (!Object.prototype.hasOwnProperty.call(this, key)) {
-		Object.defineProperty(this, key, {
-			configurable: true,
-			enumerable: true,
-			get: function () { return self._props[key] },
-			set: function (v) {
-				if (v == null || v === "") delete self._props[key]
-				else self._props[key] = String(v)
-				self._flush()
-			}
-		})
-	}
-	this._props[key] = String(value)
-	this._flush()
-}
-
-VirtualStyleProxy.prototype.removeProperty = function (name) {
-	var key = camelize(name)
-	delete this._props[key]
-	if (Object.prototype.hasOwnProperty.call(this, key)) delete this[key]
-	this._flush()
-}
-
-Object.defineProperty(VirtualStyleProxy.prototype, "cssText", {
-	get: function () {
-		var out = []
-		for (var key in this._props) out.push(key + ":" + this._props[key])
-		return out.join(";")
-	},
-	set: function (value) {
-		var self = this
-		Object.keys(this).forEach(function (key) {
-			if (key !== "_wrapper" && key !== "_props") delete self[key]
-		})
-		this._props = {}
-		if (value) {
-			// Only used for the shim's first-render `dom.style = ""` clear path
-			// in practice — a non-empty string assignment isn't exercised by
-			// render.js itself (see CONTRACT.md §f), so no parsing is needed here.
-			this._flush()
-		}
-	}
-})
-
-function VirtualNodeWrapper(vid, emit, registerStyleProxy) {
-	this._vid = vid
-	this._emit = emit
-	this._style = new VirtualStyleProxy(this, registerStyleProxy)
-	this._directProps = {}
-	this._listeners = Object.create(null)
-	this._isRawText = false
-	this._text = null
-	this._document = null
-	this._tag = null
-	this._parent = null
-	this._children = []
-	this.vnodes = null
-}
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "nodeType", {
-	get: function () { return this._isRawText ? 3 : 1 }
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "ownerDocument", {
-	get: function () { return this._document }
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "namespaceURI", {
-	get: function () { return undefined }
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "parentNode", {
-	get: function () { return this._parent }
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "firstChild", {
-	get: function () { return this._children.length > 0 ? this._children[0] : null }
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "nextSibling", {
-	get: function () {
-		if (this._parent == null) return null
-		var siblings = this._parent._children
-		var index = siblings.indexOf(this)
-		return index >= 0 && index + 1 < siblings.length ? siblings[index + 1] : null
-	}
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "textContent", {
-	get: function () {
-		if (this._isRawText) return this._text
-		var out = ""
-		for (var i = 0; i < this._children.length; i++) out += this._children[i].textContent
-		return out
-	},
-	set: function (value) {
-		if (this._isRawText) {
-			this.nodeValue = value
-			return
-		}
-		// Mirrors the real wrapper: only ever called with "" (first-render
-		// clear). A genuinely non-empty assignment isn't exercised by
-		// render.js (see CONTRACT.md) so it's intentionally not implemented.
-		if (this._children.length > 0) {
-			var removed = this._children.slice()
-			for (var i = 0; i < removed.length; i++) this.removeChild(removed[i])
-		}
-	}
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "nodeValue", {
-	get: function () { return this._isRawText ? this._text : null },
-	set: function (value) {
-		if (this._isRawText) {
-			this._text = String(value)
-			this._emit({ op: "setText", vid: this._vid, value: this._text })
-		}
-	}
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "innerHTML", {
-	get: function () { return this.textContent },
-	set: function () {
-		throw new Error("m.trust / innerHTML is not supported by the Lynx shim (renderer mode).")
-	}
-})
-
-Object.defineProperty(VirtualNodeWrapper.prototype, "style", {
-	get: function () { return this._style },
-	set: function (value) {
-		if (value == null) this._style.cssText = ""
-		else if (typeof value === "string") this._style.cssText = value
-	}
-})
-
-DIRECT_PROPS.forEach(function (p) {
-	Object.defineProperty(VirtualNodeWrapper.prototype, p, {
-		configurable: true,
-		enumerable: true,
-		get: function () { return this._directProps[p] },
-		set: function (v) {
-			this._directProps[p] = v
-			this._emit({ op: "setProp", vid: this._vid, key: p, value: v })
-		}
-	})
-})
-
-VirtualNodeWrapper.prototype.setAttribute = function (key, value) {
-	this._emit({ op: "setAttribute", vid: this._vid, key: key, value: value == null ? null : String(value) })
-}
-
-VirtualNodeWrapper.prototype.removeAttribute = function (key) {
-	this._emit({ op: "removeAttribute", vid: this._vid, key: key })
-}
-
-VirtualNodeWrapper.prototype.setAttributeNS = function (ns, key, value) {
-	this.setAttribute(key, value)
-}
-
-VirtualNodeWrapper.prototype.appendChild = function (child) {
-	if (child == null) return child
-	if (child.nodeType === 11) return child // inert fragment
-	if (child._parent != null) {
-		var oldSiblings = child._parent._children
-		var oldIndex = oldSiblings.indexOf(child)
-		if (oldIndex >= 0) oldSiblings.splice(oldIndex, 1)
-	}
-	this._children.push(child)
-	child._parent = this
-	this._emit({ op: "appendChild", parentVid: this._vid, childVid: child._vid })
-	return child
-}
-
-VirtualNodeWrapper.prototype.insertBefore = function (child, ref) {
-	if (child == null) return child
-	if (child.nodeType === 11) return child
-	if (ref == null) return this.appendChild(child)
-	if (child._parent != null) {
-		var oldSiblings = child._parent._children
-		var oldIndex = oldSiblings.indexOf(child)
-		if (oldIndex >= 0) oldSiblings.splice(oldIndex, 1)
-	}
-	var refIndex = this._children.indexOf(ref)
-	this._children.splice(refIndex >= 0 ? refIndex : this._children.length, 0, child)
-	child._parent = this
-	this._emit({ op: "insertBefore", parentVid: this._vid, childVid: child._vid, refVid: ref._vid })
-	return child
-}
-
-VirtualNodeWrapper.prototype.removeChild = function (child) {
-	if (child == null) return child
-	if (child.nodeType === 11) return child
-	var index = this._children.indexOf(child)
-	if (index >= 0) this._children.splice(index, 1)
-	child._parent = null
-	this._emit({ op: "removeChild", parentVid: this._vid, childVid: child._vid })
-	return child
-}
-
-VirtualNodeWrapper.prototype.contains = function (other) {
-	if (other == null) return false
-	var node = other
-	while (node != null) {
-		if (node === this) return true
-		node = node._parent
-	}
-	return false
-}
-
-VirtualNodeWrapper.prototype.focus = function () {}
-
-// Events: unlike the real wrapper (which wraps + registers a real PAPI
-// listener per type), this only needs to know WHETHER a type transitions
-// between "has a handler" and "has none" — that's what the main thread
-// needs to know to attach/detach its forwarding listener. The actual
-// listener function/object is resolved by dispatchEvent() at CALL time, not
-// registration time, so Mithril swapping vnode.events' handlers across
-// redraws (a very common pattern) never needs a new op.
-VirtualNodeWrapper.prototype.addEventListener = function (type, listener) {
-	var hadListener = this._listeners[type] != null
-	this._listeners[type] = listener
-	if (!hadListener) this._emit({ op: "addEvent", vid: this._vid, type: type })
-}
-
-VirtualNodeWrapper.prototype.removeEventListener = function (type, listener) {
-	if (this._listeners[type] !== listener) return
-	delete this._listeners[type]
-	this._emit({ op: "removeEvent", vid: this._vid, type: type })
-}
-
-// Invoked when renderer/background.js receives a forwarded real-PAPI event.
-VirtualNodeWrapper.prototype.dispatchEvent = function (ev) {
-	var listener = this._listeners[ev.type]
-	if (listener == null) return
-	if (typeof listener === "function") listener.call(ev.currentTarget, ev)
-	else if (typeof listener.handleEvent === "function") listener.handleEvent(ev)
-}
-
-function createRawTextNode(vid, emit, registerStyleProxy, value) {
-	var wrapper = new VirtualNodeWrapper(vid, emit, registerStyleProxy)
-	wrapper._isRawText = true
-	wrapper._text = String(value)
-	emit({ op: "createText", vid: vid, value: wrapper._text })
-	return wrapper
-}
-
-function createElementWrapper(vid, emit, registerStyleProxy, tag) {
-	var wrapper = new VirtualNodeWrapper(vid, emit, registerStyleProxy)
-	wrapper._tag = tag
-	emit({ op: "createElement", vid: vid, tag: tag })
-	return wrapper
-}
-
-// Inert fragment — same "never attached, children go straight to the real
-// parent" contract as the real shim's createFragment().
-function createFragment(document) {
-	return {
-		nodeType: 11,
-		ownerDocument: document,
-		appendChild: function () {},
-		insertBefore: function () {},
-		removeChild: function () {}
-	}
-}
-
-// createVirtualDocument(emit, onCreateNode) — emit(op) is called
-// synchronously for every mutation; the caller (renderer/background.js) is
-// responsible for batching and flushing the accumulated ops across the
-// thread boundary. onCreateNode(wrapper) is called for every node created
-// (root included) so the caller can index wrappers by vid. Each call gets
-// its own independent style-proxy registry and vid counter — see
-// VirtualStyleProxy's comment for why this isn't module-level.
-function createVirtualDocument(emit, onCreateNode) {
-	var nextVid = 1 // vid 0 is reserved for the page root.
-	var notify = onCreateNode || function () {}
-	var styleProxies = []
-	var registerStyleProxy = function (proxy) { styleProxies.push(proxy) }
-
-	var document = {
-		createElement: function (tag) {
-			var wrapper = createElementWrapper(nextVid++, emit, registerStyleProxy, tag)
-			wrapper._document = document
-			notify(wrapper)
-			return wrapper
-		},
-		createElementNS: function (ns, tag) {
-			return document.createElement(tag)
-		},
-		createTextNode: function (value) {
-			var wrapper = createRawTextNode(nextVid++, emit, registerStyleProxy, value)
-			wrapper._document = document
-			notify(wrapper)
-			return wrapper
-		},
-		createDocumentFragment: function () {
-			return createFragment(document)
-		}
-	}
-	Object.defineProperty(document, "activeElement", {
-		get: function () { return null }
-	})
-
-	function createRootWrapper() {
-		var root = new VirtualNodeWrapper(0, emit, registerStyleProxy)
-		root._document = document
-		root._tag = "page"
-		notify(root)
-		return root
-	}
-
-	function flushStyleProxies() {
-		for (var i = 0; i < styleProxies.length; i++) {
-			try { styleProxies[i]._flush() } catch (e) { /* ignore */ }
-		}
-	}
-
-	return { document: document, createRootWrapper: createRootWrapper, flushStyleProxies: flushStyleProxies }
-}
-
-export { createVirtualDocument, VirtualNodeWrapper, VirtualStyleProxy }

package/list.d.ts

@@ -1,31 +0,0 @@
-// Ambient declaration for the ESM list.js (the file itself is not
-// type-checked; this describes its runtime export shape for TS consumers).
-
-export interface CreateListOptions {
-  itemCount: number;
-  /** Must return a fresh vnode for the cell's content; may be called more than once for the same index (recycling). */
-  renderItem(index: number): unknown;
-  /** Defaults to String(index). Set on every item's "item-key" attribute — required by native, not just an identity hint. */
-  itemKey?(index: number): string;
-  className?: string;
-  /** Defaults to "vertical". */
-  scrollOrientation?: "vertical" | "horizontal";
-  /** Defaults to "single". */
-  listType?: "single" | "flow";
-  /** Defaults to 1. */
-  spanCount?: number;
-}
-
-export interface ListHandle {
-  _handle: unknown;
-  nodeType: 1;
-  /** Call after mutating the underlying data so a subsequently-scrolled-into-view cell reflects the new count. */
-  setItemCount(nextCount: number): void;
-}
-
-/**
- * Creates a native-recycled `<list>` element (project plan, Phase 8, Tier
- * 2). Imperative escape hatch — call from oncreate(vnode) and attach the
- * result yourself (parentNode.appendChild(list)).
- */
-export function createList(parentNode: { ownerDocument: unknown }, options: CreateListOptions): ListHandle;

package/list.js

@@ -1,185 +0,0 @@
-// list.js
-//
-// List virtualization/recycling (project plan, Phase 8, Tier 2), main-thread
-// only. __CreateList's componentAtIndex/enqueueComponent callbacks are a
-// native-driven recycler: native owns scroll position and cell lifecycle,
-// calling back into JS to fetch or recycle a cell's content by TYPE
-// (matching RecyclerView/UICollectionView semantics), not a JS-side
-// windowing calculation.
-//
-// The sign/recycle map design and the exact __FlushElementTree({triggerLayout,
-// operationID, elementID, listID}) call shape are ported from
-// @lynx-js/react's OWN shipped runtime/lib/snapshot/list/list.js — real,
-// proven code, not guesswork (unlike gesture.js's callback-shape question,
-// this part IS verified against a real implementation). What list.js narrows
-// down for v1, deliberately:
-//   - No deferred list items (ReactLynx's `defer`/`isReady` promise dance —
-//     ties into a whole separate lifecycle-event protocol not otherwise
-//     needed here).
-//   - No componentAtIndexes batching — native's single-cell componentAtIndex
-//     callback only.
-//   - No independent per-item redraw after the initial bind/recycle — a list
-//     item's content is (re)computed fresh from renderItem(index) every time
-//     native calls componentAtIndex for it (on scroll-driven reuse), not
-//     whenever the app's own state changes. An app wanting a currently-bound
-//     visible item to reflect a data change needs its OWN mechanism to ask
-//     native to re-request that cell; list.js does not provide one in v1.
-//
-// This is an imperative escape hatch, like element.js/gesture.js — call it
-// from oncreate(vnode) and attach the result yourself
-// (parentNode.appendChild(list)), rather than mounting it through m().
-// Tier 1 (no code here at all — just m("list", ...)/m("list-item", ...) as
-// ordinary tags through the existing shim, relying on its already-tested
-// keyed/LIS diff) covers the common case and should be preferred unless the
-// app specifically needs native-driven recycling for very large lists.
-
-import shim from "./src/lynx-mithril-shim.js";
-
-// A render function dedicated to list-item content, independent of
-// shim.render()/redraw()'s own single-root convenience-API state (which a
-// main-thread-owned or data-channel-mode app may already be using for the
-// rest of the page). Each item wrapper carries its own `.vnodes`, so reusing
-// one render function sequentially across many items/lists is safe — Mithril
-// diffs against whatever `.vnodes` is already on the target wrapper.
-const renderItemContent = shim();
-
-function typeKeyOf(vnode) {
-	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
-}
-
-/**
- * Creates a native-recycled `<list>` element, scoped to the same component
- * as `parentNode` (anything with an `ownerDocument`, e.g. a real
- * LynxNodeWrapper). `renderItem(index)` must return a fresh Mithril vnode
- * for that cell's content every time it's called — it may be called more
- * than once for the same index (recycling).
- *
- * `scrollOrientation`/`listType`/`spanCount` and each item's `item-key` are
- * NOT optional in practice, even though native's __CreateList/componentAtIndex
- * types don't require them: every real @lynx-js/react list example sets all
- * of these unconditionally (verified by reading lynx-examples/examples/list's
- * base/recyclable/async-rendering demos — see ../LIST_INVESTIGATION.md), and
- * a real device never called componentAtIndex at all without them. Defaults
- * here match what those examples use for the simple single-column case.
- */
-export function createList(parentNode, options) {
-	const {
-		itemCount,
-		renderItem,
-		itemKey,
-		className,
-		scrollOrientation = "vertical",
-		listType = "single",
-		spanCount = 1,
-	} = options;
-	let count = itemCount;
-	const pageId = parentNode.ownerDocument._pageId;
-	const keyOf = typeof itemKey === "function" ? itemKey : (index) => String(index);
-
-	// itemType -> Map<sign, ItemEntry>, the reuse pool.
-	const recycleMap = new Map();
-	// sign -> ItemEntry, currently-bound (visible) items.
-	const signMap = new Map();
-
-	function bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey) {
-		const itemWrapper = parentNode.ownerDocument.createElement("list-item");
-		__SetAttribute(itemWrapper._handle, "item-key", keyOf(cellIndex));
-		__AppendElement(listHandle, itemWrapper._handle);
-		renderItemContent(itemWrapper, vnode);
-
-		const sign = __GetElementUniqueID(itemWrapper._handle);
-		signMap.set(sign, { wrapper: itemWrapper, typeKey });
-		__FlushElementTree(itemWrapper._handle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
-		return sign;
-	}
-
-	function bindRecycledItem(listId, cellIndex, opId, vnode, pool) {
-		const [sign, entry] = pool.entries().next().value;
-		pool.delete(sign);
-		// The recycled wrapper is now bound to a DIFFERENT index — its
-		// item-key must be updated to match, the same way its content does.
-		__SetAttribute(entry.wrapper._handle, "item-key", keyOf(cellIndex));
-		renderItemContent(entry.wrapper, vnode);
-		signMap.set(sign, entry);
-		__FlushElementTree(entry.wrapper._handle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
-		return sign;
-	}
-
-	function componentAtIndex(listHandle, listId, cellIndex, opId) {
-		if (cellIndex < 0 || cellIndex >= count) {
-			throw new Error(`mithril-lynx list: cellIndex ${cellIndex} out of range (itemCount=${count})`);
-		}
-		const vnode = renderItem(cellIndex);
-		const typeKey = typeKeyOf(vnode);
-		const pool = recycleMap.get(typeKey);
-		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, vnode, pool);
-		return bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey);
-	}
-
-	function enqueueComponent(_listHandle, _listId, sign) {
-		const entry = signMap.get(sign);
-		if (entry == null) return;
-		signMap.delete(sign);
-		if (!recycleMap.has(entry.typeKey)) recycleMap.set(entry.typeKey, new Map());
-		recycleMap.get(entry.typeKey).set(sign, entry);
-	}
-
-	// THE missing piece (see LIST_INVESTIGATION.md): __CreateList + attributes
-	// alone never triggers componentAtIndex — native only starts requesting
-	// cells once it's told, via a special "update-list-info" attribute, which
-	// positions currently exist. Ported from @lynx-js/react's OWN
-	// runtime/lib/snapshot/list/listUpdateInfo.js (ListUpdateInfoRecording.flush()),
-	// which sends this on every list-children change, alongside a matching
-	// __UpdateListCallbacks call. Each insertAction entry needs an "item-key"
-	// (dash-case — confirmed by a real device rejecting the first attempt,
-	// which omitted it, with "Error for illegal list item-key in parse
-	// insertAction"; the exact key name matches ReactLynx's own
-	// `__listItemPlatformInfo['item-key']`, a raw JSX-prop-shaped bag it
-	// spreads into each entry). `type` per entry is still UNCONFIRMED —
-	// ReactLynx's version uses its own component-type reference there
-	// (meaningful only to its own recycling, not to native, as far as this
-	// file's reading of the source can tell); a constant string is used
-	// here since this port's own type-based recycling (typeKeyOf(), above)
-	// is tracked independently, in this module, not through native's copy
-	// of `type`.
-	function sendListInfo(insertAction, removeAction, updateAction) {
-		__SetAttribute(listHandle, "update-list-info", { insertAction, removeAction, updateAction });
-		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent);
-	}
-
-	function insertEntry(position) {
-		return { position, type: "cell", "item-key": keyOf(position) };
-	}
-
-	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {});
-	__SetAttribute(listHandle, "scroll-orientation", scrollOrientation);
-	__SetAttribute(listHandle, "list-type", listType);
-	__SetAttribute(listHandle, "span-count", String(spanCount));
-	if (className != null) __SetClasses(listHandle, className);
-
-	sendListInfo(
-		Array.from({ length: count }, (_, position) => insertEntry(position)),
-		[],
-		[],
-	);
-
-	return {
-		_handle: listHandle,
-		nodeType: 1,
-		/** Call after mutating the underlying data so a subsequently-scrolled-into-view cell reflects the new count. */
-		setItemCount(nextCount) {
-			if (nextCount === count) return;
-			if (nextCount > count) {
-				sendListInfo(
-					Array.from({ length: nextCount - count }, (_, i) => insertEntry(count + i)),
-					[],
-					[],
-				);
-			} else {
-				const removed = Array.from({ length: count - nextCount }, (_, i) => nextCount + i);
-				sendListInfo([], removed, []);
-			}
-			count = nextCount;
-		},
-	};
-}

package/main-thread.d.ts

@@ -1,43 +0,0 @@
-// Ambient declaration for the ESM main-thread.js (the file itself is not
-// type-checked; this describes its runtime export shape for TS consumers).
-
-/** Returns the most recently received data (from __RenderPage/__UpdatePage or a background push). */
-export function getData<T = unknown>(): T | undefined;
-
-/** Sends a named action to the background thread's setBackgroundEventHandler. */
-export function dispatchToBackground(handlerName: string, data?: unknown): void;
-
-export interface SetupAppOptions<TInput = unknown, TData = TInput> {
-  /** Called exactly once, on the first __RenderPage, to build the root Mithril vnode. */
-  root(): unknown;
-  /** Optional transform applied to raw engine/background data before storing it. */
-  processData?(data: TInput): TData;
-  /**
-   * When true (default), pushes processed data to the background thread on
-   * every __RenderPage/__UpdatePage, and listens for background-pushed
-   * updates, redrawing via Mithril's own shim.redraw().
-   */
-  enableBackgroundSync?: boolean;
-}
-
-/**
- * Wires the Lynx engine's page lifecycle (__RenderPage/__UpdatePage/
- * __DestroyLifetime) to a Mithril app: renders `root()` once, then calls
- * the shim's redraw() on every subsequent data push. See the project plan,
- * Phase 3 ("data-channel mode").
- */
-export function setupApp<TInput = unknown, TData = TInput>(
-  options: SetupAppOptions<TInput, TData>,
-): void;
-
-/**
- * Registers a handler background.js's runOnMainThread(key, ...args) can
- * call by name. See the project plan, Phase 6.
- */
-export function registerHandler(key: string, fn: (...args: unknown[]) => unknown): void;
-
-/**
- * Calls a handler background.js registered via registerHandler(key, fn).
- * Args and the resolved value must be JSON-serializable.
- */
-export function runOnBackground<T = unknown>(key: string, ...args: unknown[]): Promise<T>;