@sigx/lynx-runtime 0.2.4

package/dist/main-thread-ref.d.ts

@@ -0,0 +1,88 @@
+/**
+ * MainThreadRef — a ref whose `.current` value lives on the Main Thread.
+ *
+ * On the Background Thread, `.current` is always the initial value (typically
+ * `null`). On the Main Thread, `.current` is set to the real Lynx element
+ * handle when the ref is bound via `main-thread:ref={ref}`.
+ *
+ * This is the sigx equivalent of react-lynx's `useMainThreadRef()` and
+ * vue-lynx's `useMainThreadRef()`. It enables zero-latency style updates
+ * and animations by giving main-thread event handlers synchronous access
+ * to native elements.
+ *
+ * Architecture:
+ *   BG: useMainThreadRef(init) → MainThreadRef { wvid, current: init }
+ *        → pushOp(INIT_MT_REF, wvid, init)
+ *   BG: patchProp('main-thread:ref', ref) → pushOp(SET_MT_REF, elId, wvid)
+ *   MT: INIT_MT_REF → workletRefs.set(wvid, { current: init })
+ *   MT: SET_MT_REF  → workletRefs.get(wvid).current = elements.get(elId)
+ */
+export declare function resetWvidCounter(): void;
+/**
+ * A ref whose `.current` property is managed on the Main Thread.
+ *
+ * On the BG thread, `.current` returns the `initValue` and is read-only
+ * (setting it has no effect — the real value lives on MT).
+ *
+ * In main-thread event handlers and `runOnMainThread` callbacks, `.current`
+ * is the real Lynx element handle with methods like `setStyleProperties()`,
+ * `getComputedStyleProperty()`, and `animate()`.
+ */
+export declare class MainThreadRef<T = unknown> {
+    /**
+     * Worklet variable ID — uniquely identifies this ref across threads.
+     * Underscored to match the field name `transformWorklet` walks for
+     * in @lynx-js/react/worklet-runtime when expanding `_c` captures.
+     */
+    readonly _wvid: number;
+    /**
+     * Initial value snapshot — sent to MT in INIT_MT_REF and used by
+     * the worklet-runtime to seed the firstScreen ref map.
+     */
+    readonly _initValue: T;
+    /**
+     * On BG: the init value (read-only snapshot).
+     * On MT: the real element handle (set by SET_MT_REF op).
+     */
+    current: T;
+    constructor(initValue: T);
+}
+/**
+ * Walk a captured `_c` map and serialize MainThreadRef instances to plain
+ * `{ _wvid, _initValue }` objects so they survive the JSON round-trip across
+ * the BG→MT bridge. Upstream's worklet-runtime walks `_c` looking for `_wvid`
+ * to recognize ref captures and resolve them via
+ * `lynxWorkletImpl._refImpl._workletRefMap`.
+ *
+ * Used by both the SET_WORKLET_EVENT path (`nodeOps.patchProp`) and the
+ * SET_GESTURE_DETECTOR path (`native/gesture-detector.ts`).
+ */
+export declare function sanitizeCaptured(captured: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a ref that provides synchronous access to a native element on the
+ * Main Thread. Bind it to an element via `main-thread:ref={ref}`.
+ *
+ * @example
+ * ```tsx
+ * const elRef = useMainThreadRef<MainThread.Element>(null);
+ *
+ * function handleScroll(e: ScrollEvent) {
+ *   'main thread';
+ *   const offset = e.detail.scrollTop;
+ *   elRef.current?.setStyleProperties({
+ *     transform: `translateY(${-offset}px)`,
+ *   });
+ * }
+ *
+ * return (
+ *   <scroll-view
+ *     main-thread-bindscroll={handleScroll}
+ *   >
+ *     <view main-thread:ref={elRef}>
+ *       <text>Sticky header</text>
+ *     </view>
+ *   </scroll-view>
+ * );
+ * ```
+ */
+export declare function useMainThreadRef<T = unknown>(initValue: T): MainThreadRef<T>;

package/dist/model-processor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Platform-specific model processor for Lynx form elements.
+ *
+ * Wires sigx's `model={() => state.field}` two-way binding directive to
+ * Lynx's <input> and <textarea> elements. The processor runs at JSX
+ * creation time (called from runtime-core/jsx-runtime.ts when an
+ * intrinsic element has a `model` prop) and rewrites the props to:
+ *
+ *   1. Set the initial `value` from the bound state
+ *   2. Install a `bindinput` handler that pushes the new value back into state
+ *
+ * Lynx differs from DOM in two important ways:
+ *
+ *   - Lynx <input> fires `bindinput` with `event.detail.value` containing
+ *     the new text. There is no DOM-style `target.value` property — the
+ *     value lives on the event detail object.
+ *   - Lynx Go (and most current Lynx hosts) have no native checkbox or
+ *     radio elements. We only handle text-style <input> and <textarea>
+ *     here. Adding checkbox/radio later is straightforward — mirror the
+ *     branches in packages/runtime-dom/src/model-processor.ts.
+ *
+ * Mirrors packages/runtime-dom/src/model-processor.ts.
+ */
+export {};

package/dist/mt-hmr-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BG → MT hot-update bridge.
+ *
+ * The MT bundle has rspack's HMR runtime in code (because `module.hot.accept`
+ * is referenced) but no transport feeding it updates. After a save, BG's HMR
+ * client patches App.tsx and re-renders, generating worklet placeholders with
+ * new content-hash `_wkltId`s. MT's `_workletMap` still holds the old IDs, so
+ * the lookup fails (`bind of undefined`) when the user taps.
+ *
+ * This bridge closes the gap. We hook the same `webpackHotUpdate` event the
+ * rspack HMR client subscribes to. On every cycle:
+ *   1. Fetch the matching `main__main-thread.<hash>.hot-update.js` over the
+ *      dev server URL (`__webpack_require__.p`).
+ *   2. Extract every `registerWorkletInternal(...)` call from the response.
+ *   3. Forward the concatenated calls to MT via
+ *      `callLepusMethod('sigxApplyMtHotUpdate', { code }, ...)`.
+ * The MT handler `eval`s them in the existing realm, registering the new IDs
+ * into the live `_workletMap` before the user taps a freshly re-rendered
+ * button.
+ *
+ * Loaded only in dev mode — wired into the BG entry by `lynx-plugin`'s
+ * `applyEntry` when `enabledHMR` is true.
+ */
+interface RspackEmitter {
+    on(event: 'webpackHotUpdate', cb: (currentHash: string) => void): void;
+}
+declare const __webpack_require__: {
+    p?: string;
+    c?: Record<string, {
+        exports: unknown;
+    }>;
+    hu?: (chunkId: string) => string;
+};
+declare function findRspackEmitter(): RspackEmitter | undefined;
+interface HotUpdate {
+    modules: Record<string, (...args: unknown[]) => unknown>;
+    runtime?: unknown;
+}
+declare function fetchAndForward(): void;
+/**
+ * Extract `registerWorkletInternal(...)` calls from a hot-update body.
+ *
+ * Mirrors `lynx-plugin/src/loaders/worklet-utils.ts:extractRegistrations`
+ * (duplicated here to avoid a runtime → build-time dep). Bracket-depth count
+ * handles nested braces in the function body.
+ */
+declare function extractRegistrations(source: string): string;

package/dist/mt-hmr-bridge.js

@@ -0,0 +1,58 @@
+//#region src/mt-hmr-bridge.ts
+function e() {
+	let e = __webpack_require__?.c;
+	if (e) for (let t in e) {
+		if (!t.includes("@rspack") || !t.endsWith("emitter.js")) continue;
+		let n = e[t]?.exports;
+		if (n && typeof n.on == "function" && typeof n.emit == "function") return n;
+	}
+}
+Promise.resolve().then(() => {
+	let n = e();
+	if (!n) {
+		console.log("[sigx-mt-hmr-bridge] rspack emitter not found — bridge inactive");
+		return;
+	}
+	n.on("webpackHotUpdate", () => {
+		t();
+	});
+});
+function t() {
+	let e = __webpack_require__?.p ?? "", t = __webpack_require__?.hu;
+	if (typeof t != "function") return;
+	let r = e + t("main__main-thread"), i = lynx?.requireModuleAsync;
+	typeof i == "function" && i(r, (e, t) => {
+		if (e) {
+			console.log("[sigx-mt-hmr-bridge] requireModuleAsync failed:", String(e));
+			return;
+		}
+		let r = "";
+		for (let e in t.modules) {
+			let n = t.modules[e];
+			typeof n == "function" && (r += n.toString() + "\n");
+		}
+		let i = n(r);
+		if (!i) return;
+		let a = lynx?.getNativeApp?.();
+		!a || typeof a.callLepusMethod != "function" || a.callLepusMethod("sigxApplyMtHotUpdate", { code: i }, () => {});
+	});
+}
+function n(e) {
+	let t = [], n = 0;
+	for (;;) {
+		let r = e.indexOf("registerWorkletInternal(", n);
+		if (r === -1) break;
+		let i = 0, a = r + 24 - 1;
+		for (; a < e.length; a++) {
+			let t = e[a];
+			if (t === "(") i++;
+			else if (t === ")" && (i--, i === 0)) break;
+		}
+		let o = a + 1;
+		o < e.length && e[o] === ";" && o++, t.push(e.slice(r, o)), n = o;
+	}
+	return t.join("\n");
+}
+//#endregion
+
+//# sourceMappingURL=mt-hmr-bridge.js.map

package/dist/mt-hmr-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mt-hmr-bridge.js","names":[],"sources":["../src/mt-hmr-bridge.ts"],"sourcesContent":["/**\n * BG → MT hot-update bridge.\n *\n * The MT bundle has rspack's HMR runtime in code (because `module.hot.accept`\n * is referenced) but no transport feeding it updates. After a save, BG's HMR\n * client patches App.tsx and re-renders, generating worklet placeholders with\n * new content-hash `_wkltId`s. MT's `_workletMap` still holds the old IDs, so\n * the lookup fails (`bind of undefined`) when the user taps.\n *\n * This bridge closes the gap. We hook the same `webpackHotUpdate` event the\n * rspack HMR client subscribes to. On every cycle:\n *   1. Fetch the matching `main__main-thread.<hash>.hot-update.js` over the\n *      dev server URL (`__webpack_require__.p`).\n *   2. Extract every `registerWorkletInternal(...)` call from the response.\n *   3. Forward the concatenated calls to MT via\n *      `callLepusMethod('sigxApplyMtHotUpdate', { code }, ...)`.\n * The MT handler `eval`s them in the existing realm, registering the new IDs\n * into the live `_workletMap` before the user taps a freshly re-rendered\n * button.\n *\n * Loaded only in dev mode — wired into the BG entry by `lynx-plugin`'s\n * `applyEntry` when `enabledHMR` is true.\n */\n\ninterface RspackEmitter {\n  on(event: 'webpackHotUpdate', cb: (currentHash: string) => void): void;\n}\n\n// `@rspack/core/hot/emitter` is a CJS singleton EventEmitter the rspack HMR\n// client subscribes to. We can't `import` it here — `@rspack/core` is a\n// transitive build-time dep of the user app via rspeedy, not a runtime dep\n// of this package, so rspack's resolver fails from our install location.\n//\n// Instead, locate it through the BG bundle's webpack module cache at runtime:\n// after `@rspack/core/hot/dev-server` initialises (also injected into the BG\n// entry by lynx-plugin), the emitter module is registered in\n// `__webpack_require__.c` keyed by its resolved path. We scan the cache for\n// the one whose `module.exports` looks like the EventEmitter singleton (has\n// `on` + `emit` + an `events` bag).\ndeclare const __webpack_require__: {\n  p?: string;\n  c?: Record<string, { exports: unknown }>;\n  hu?: (chunkId: string) => string;\n};\n\nfunction findRspackEmitter(): RspackEmitter | undefined {\n  const cache = __webpack_require__?.c;\n  if (!cache) return undefined;\n  for (const id in cache) {\n    if (!id.includes('@rspack') || !id.endsWith('emitter.js')) continue;\n    const exp = cache[id]?.exports as Record<string, unknown> | undefined;\n    if (\n      exp\n      && typeof (exp as { on?: unknown }).on === 'function'\n      && typeof (exp as { emit?: unknown }).emit === 'function'\n    ) {\n      return exp as unknown as RspackEmitter;\n    }\n  }\n  return undefined;\n}\n\n// Defer subscription via a microtask: the entry chain prepends this bridge\n// before `@rspack/core/hot/dev-server`, so at module-eval time the emitter\n// isn't in the webpack cache yet. By the next microtask, dev-server has run\n// its top-level code and the emitter module is cached.\nPromise.resolve().then(() => {\n  const emitter = findRspackEmitter();\n  if (!emitter) {\n    console.log('[sigx-mt-hmr-bridge] rspack emitter not found — bridge inactive');\n    return;\n  }\n  emitter.on('webpackHotUpdate', () => {\n    fetchAndForward();\n  });\n});\n\ninterface HotUpdate {\n  modules: Record<string, (...args: unknown[]) => unknown>;\n  runtime?: unknown;\n}\n\nfunction fetchAndForward(): void {\n  // The `webpackHotUpdate` event payload is the *new* hash, but hot-update\n  // chunks are named with the *previous* hash (the \"delta-from\" hash). Use\n  // `__webpack_require__.hu` — same helper rspack's own loader uses — which\n  // reads `__webpack_require__.h()` to build the URL with the right hash.\n  const publicPath = __webpack_require__?.p ?? '';\n  const hu = __webpack_require__?.hu;\n  if (typeof hu !== 'function') return;\n  const url = publicPath + hu('main__main-thread');\n\n  // Lynx's BG runtime doesn't have a working `fetch` for arbitrary URLs in\n  // many hosts; rspack's own HMR loader uses `lynx.requireModuleAsync` (see\n  // `loadUpdateChunk` in the BG bundle). It returns the parsed hot-update\n  // shape `{ modules, runtime }` — each `modules[id]` is the compiled JS\n  // factory function. We extract registerWorkletInternal calls from\n  // `factory.toString()` so we don't have to actually evaluate the factory\n  // (which would import worklet-runtime / install-hybrid into BG's webpack\n  // module graph, with unwanted side effects).\n  const requireModuleAsync = (lynx as unknown as {\n    requireModuleAsync?: (\n      url: string,\n      cb: (err: unknown, update: HotUpdate) => void,\n    ) => void;\n  })?.requireModuleAsync;\n  if (typeof requireModuleAsync !== 'function') return;\n\n  requireModuleAsync(url, (err, update) => {\n    if (err) {\n      console.log('[sigx-mt-hmr-bridge] requireModuleAsync failed:', String(err));\n      return;\n    }\n    let combined = '';\n    for (const id in update.modules) {\n      const factory = update.modules[id];\n      if (typeof factory === 'function') combined += factory.toString() + '\\n';\n    }\n    const code = extractRegistrations(combined);\n    if (!code) return;\n    const app = lynx?.getNativeApp?.();\n    if (!app || typeof app.callLepusMethod !== 'function') return;\n    app.callLepusMethod('sigxApplyMtHotUpdate', { code }, () => {});\n  });\n}\n\n/**\n * Extract `registerWorkletInternal(...)` calls from a hot-update body.\n *\n * Mirrors `lynx-plugin/src/loaders/worklet-utils.ts:extractRegistrations`\n * (duplicated here to avoid a runtime → build-time dep). Bracket-depth count\n * handles nested braces in the function body.\n */\nfunction extractRegistrations(source: string): string {\n  const out: string[] = [];\n  const marker = 'registerWorkletInternal(';\n  let from = 0;\n\n  while (true) {\n    const idx = source.indexOf(marker, from);\n    if (idx === -1) break;\n\n    let depth = 0;\n    let i = idx + marker.length - 1; // points at the opening '('\n    for (; i < source.length; i++) {\n      const ch = source[i];\n      if (ch === '(') depth++;\n      else if (ch === ')') {\n        depth--;\n        if (depth === 0) break;\n      }\n    }\n\n    let end = i + 1;\n    if (end < source.length && source[end] === ';') end++;\n    out.push(source.slice(idx, end));\n    from = end;\n  }\n\n  return out.join('\\n');\n}\n"],"mappings":";AA6CA,SAAS,IAA+C;CACtD,IAAM,IAAQ,qBAAqB;CAC9B,OACL,KAAK,IAAM,KAAM,GAAO;EACtB,IAAI,CAAC,EAAG,SAAS,UAAU,IAAI,CAAC,EAAG,SAAS,aAAa,EAAE;EAC3D,IAAM,IAAM,EAAM,IAAK;EACvB,IACE,KACG,OAAQ,EAAyB,MAAO,cACxC,OAAQ,EAA2B,QAAS,YAE/C,OAAO;;;AAUb,QAAQ,SAAS,CAAC,WAAW;CAC3B,IAAM,IAAU,GAAmB;CACnC,IAAI,CAAC,GAAS;EACZ,QAAQ,IAAI,kEAAkE;EAC9E;;CAEF,EAAQ,GAAG,0BAA0B;EACnC,GAAiB;GACjB;EACF;AAOF,SAAS,IAAwB;CAK/B,IAAM,IAAa,qBAAqB,KAAK,IACvC,IAAK,qBAAqB;CAChC,IAAI,OAAO,KAAO,YAAY;CAC9B,IAAM,IAAM,IAAa,EAAG,oBAAoB,EAU1C,IAAsB,MAKxB;CACA,OAAO,KAAuB,cAElC,EAAmB,IAAM,GAAK,MAAW;EACvC,IAAI,GAAK;GACP,QAAQ,IAAI,mDAAmD,OAAO,EAAI,CAAC;GAC3E;;EAEF,IAAI,IAAW;EACf,KAAK,IAAM,KAAM,EAAO,SAAS;GAC/B,IAAM,IAAU,EAAO,QAAQ;GAC/B,AAAI,OAAO,KAAY,eAAY,KAAY,EAAQ,UAAU,GAAG;;EAEtE,IAAM,IAAO,EAAqB,EAAS;EAC3C,IAAI,CAAC,GAAM;EACX,IAAM,IAAM,MAAM,gBAAgB;EAC9B,CAAC,KAAO,OAAO,EAAI,mBAAoB,cAC3C,EAAI,gBAAgB,wBAAwB,EAAE,SAAM,QAAQ,GAAG;GAC/D;;AAUJ,SAAS,EAAqB,GAAwB;CACpD,IAAM,IAAgB,EAAE,EAEpB,IAAO;CAEX,SAAa;EACX,IAAM,IAAM,EAAO,QAAQ,4BAAQ,EAAK;EACxC,IAAI,MAAQ,IAAI;EAEhB,IAAI,IAAQ,GACR,IAAI,IAAM,KAAgB;EAC9B,OAAO,IAAI,EAAO,QAAQ,KAAK;GAC7B,IAAM,IAAK,EAAO;GAClB,IAAI,MAAO,KAAK;QACX,IAAI,MAAO,QACd,KACI,MAAU,IAAG;;EAIrB,IAAI,IAAM,IAAI;EAGd,AAFI,IAAM,EAAO,UAAU,EAAO,OAAS,OAAK,KAChD,EAAI,KAAK,EAAO,MAAM,GAAK,EAAI,CAAC,EAChC,IAAO;;CAGT,OAAO,EAAI,KAAK,KAAK"}

package/dist/native/gesture-detector.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Native gesture detector — BG-side wrapper around Lynx's
+ * `__SetGestureDetector(dom, id, type, config, relationMap)` PAPI.
+ *
+ * Mirrors the contract from upstream `@lynx-js/react/runtime/lib/gesture/`:
+ *   - GestureType enum values match `GestureTypeInner`.
+ *   - relationMap keys: `waitFor`, `simultaneous`, `continueWith`.
+ *   - COMPOSED gestures are walked client-side and each base is registered
+ *     with `__SetGestureDetector` separately (the platform receives bases).
+ *
+ * Public surface:
+ *   - `Gesture.Pan() / .Tap() / .LongPress() / ...` — chainable builders.
+ *   - `Gesture.Race(...) / .Simultaneous(...) / .Exclusive(...)` — composers.
+ *   - `useGestureDetector(elRef, gesture)` — attaches the gesture to the
+ *     element pointed at by elRef. Op-emit is deferred to `onMounted` so the
+ *     SET_MT_REF op (pushed during the first JSX render) is applied before
+ *     the SET_GESTURE_DETECTOR op tries to resolve the workletRefMap entry.
+ */
+import { MainThreadRef } from '../main-thread-ref.js';
+export declare const GestureType: {
+    readonly COMPOSED: -1;
+    readonly PAN: 0;
+    readonly FLING: 1;
+    readonly DEFAULT: 2;
+    readonly TAP: 3;
+    readonly LONGPRESS: 4;
+    readonly ROTATION: 5;
+    readonly PINCH: 6;
+    readonly NATIVE: 7;
+};
+export type GestureTypeValue = (typeof GestureType)[keyof typeof GestureType];
+export interface GestureWorklet {
+    _wkltId: string;
+    _c?: Record<string, unknown>;
+    _jsFn?: Record<string, unknown>;
+    _execId?: number;
+    _workletType?: string;
+}
+/**
+ * What users write at the source level — a `'main thread'` arrow function.
+ * The SWC LEPUS transform replaces it with a `GestureWorklet` placeholder
+ * before the BG bundle ships, so by the time the runtime sees the value
+ * it's already in placeholder shape. The union lets TypeScript accept the
+ * source-level function while the runtime branch treats it as a placeholder.
+ */
+export type GestureCallback = GestureWorklet | ((event: never) => void);
+export interface BaseGesture {
+    __isSerialized: true;
+    type: number;
+    id: number;
+    callbacks: Record<string, GestureWorklet>;
+    waitFor: BaseGesture[];
+    simultaneousWith: BaseGesture[];
+    continueWith: BaseGesture[];
+    config?: Record<string, unknown>;
+}
+export interface ComposedGesture {
+    __isSerialized: true;
+    type: -1;
+    gestures: AnyGesture[];
+}
+export type AnyGesture = BaseGesture | ComposedGesture;
+export declare function resetGestureIdCounter(): void;
+declare class GestureBuilderBase {
+    protected gesture: BaseGesture;
+    constructor(type: number);
+    protected setConfigKey(key: string, value: unknown): this;
+    onBegin(cb: GestureCallback): this;
+    onStart(cb: GestureCallback): this;
+    onUpdate(cb: GestureCallback): this;
+    onEnd(cb: GestureCallback): this;
+    onFinalize(cb: GestureCallback): this;
+    waitFor(...gestures: BaseGesture[]): this;
+    simultaneousWith(...gestures: BaseGesture[]): this;
+    continueWith(...gestures: BaseGesture[]): this;
+    build(): BaseGesture;
+}
+declare class PanBuilder extends GestureBuilderBase {
+    constructor();
+    axis(a: 'x' | 'y' | 'xy'): this;
+    minDistance(n: number): this;
+}
+declare class FlingBuilder extends GestureBuilderBase {
+    constructor();
+    minVelocity(n: number): this;
+    direction(d: 'left' | 'right' | 'up' | 'down'): this;
+}
+declare class TapBuilder extends GestureBuilderBase {
+    constructor();
+    numberOfTaps(n: number): this;
+    maxDistance(n: number): this;
+    maxDuration(ms: number): this;
+}
+declare class LongPressBuilder extends GestureBuilderBase {
+    constructor();
+    /**
+     * Minimum hold duration in ms before the gesture activates and `onStart`
+     * fires. Native iOS handler (`LynxLongPressGestureHandler`) reads the
+     * `minDuration` config key — defaults to 500 ms if not set.
+     */
+    minDuration(ms: number): this;
+    /**
+     * @deprecated alias for `minDuration` kept for source compatibility. The
+     * native handler only honours `minDuration`; this method now writes both
+     * keys so older call sites keep working until they migrate.
+     */
+    duration(ms: number): this;
+    maxDistance(n: number): this;
+}
+declare class PinchBuilder extends GestureBuilderBase {
+    constructor();
+}
+declare class RotationBuilder extends GestureBuilderBase {
+    constructor();
+}
+declare class NativeBuilder extends GestureBuilderBase {
+    constructor();
+}
+export declare const Gesture: {
+    Pan: () => PanBuilder;
+    Fling: () => FlingBuilder;
+    Tap: () => TapBuilder;
+    LongPress: () => LongPressBuilder;
+    Pinch: () => PinchBuilder;
+    Rotation: () => RotationBuilder;
+    Native: () => NativeBuilder;
+    /**
+     * Race — first recognizer to claim wins. Sibling bases mutually waitFor
+     * each other so the platform's gesture arena resolves the priority.
+     */
+    Race(...gs: (AnyGesture | {
+        build(): BaseGesture;
+    })[]): ComposedGesture;
+    /**
+     * Simultaneous — all recognizers can fire at once. Sibling bases declare
+     * mutual `simultaneousWith`.
+     */
+    Simultaneous(...gs: (AnyGesture | {
+        build(): BaseGesture;
+    })[]): ComposedGesture;
+    /**
+     * Exclusive — sequential. Later items waitFor all earlier items.
+     */
+    Exclusive(...gs: (AnyGesture | {
+        build(): BaseGesture;
+    })[]): ComposedGesture;
+};
+export declare function useGestureDetector(elRef: MainThreadRef<unknown>, gesture: AnyGesture | {
+    build(): BaseGesture;
+}): void;
+export {};

package/dist/native/index.d.ts

@@ -0,0 +1,2 @@
+export { Gesture, GestureType, useGestureDetector, resetGestureIdCounter, } from './gesture-detector.js';
+export type { GestureTypeValue, GestureWorklet, GestureCallback, BaseGesture, ComposedGesture, AnyGesture, } from './gesture-detector.js';

package/dist/nodeOps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lynx renderer node operations (Background Thread).
+ *
+ * Builds a ShadowElement tree and pushes ops into the op queue. NO Lynx PAPI
+ * globals (__CreateElement, __AppendElement, etc.) are referenced here — those
+ * only exist on the Main Thread. The op queue is flushed to MT via
+ * sigxPatchUpdate, where ops-apply.ts dispatches them to real PAPI calls.
+ */
+import type { RendererOptions } from '@sigx/runtime-core/internals';
+import { ShadowElement } from './shadow-element.js';
+export type LynxNode = ShadowElement;
+export type LynxElement = ShadowElement;
+export declare function resolveClass(el: ShadowElement): string;
+export declare const nodeOps: RendererOptions<ShadowElement, ShadowElement>;

package/dist/op-queue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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';
+/**
+ * Push one op (opcode + arguments) into the buffer as a flat sequence.
+ * Example: pushOp(OP.CREATE, id, type) → buffer gets [0, id, type].
+ */
+export declare function pushOp(...args: unknown[]): void;
+/** Take all buffered ops and reset the buffer. */
+export declare function takeOps(): unknown[];
+/**
+ * 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 declare function scheduleFlush(): void;
+/**
+ * Immediately flush all buffered ops — used on initial mount so the first
+ * frame is committed synchronously.
+ */
+export declare function flushNow(): void;
+/** Reset module state — for testing only. */
+export declare function resetOpQueue(): void;
+/**
+ * Resolves once the most recent ops batch has been applied on the main
+ * thread. If no ops are in flight, resolves immediately.
+ */
+export declare function waitForFlush(): Promise<void>;
+/**
+ * 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 declare function sendHotReloadSignal(): void;
+/**
+ * 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 declare function installEventPublisher(): void;

package/dist/render.d.ts

@@ -0,0 +1,22 @@
+import type { MountFn } from '@sigx/runtime-core';
+import { type ShadowElement } from './shadow-element.js';
+export declare const render: import("@sigx/runtime-core/internals").RootRenderFunction<ShadowElement, ShadowElement>;
+/**
+ * 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 declare const lynxMount: MountFn;

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

@@ -0,0 +1,37 @@
+/**
+ * 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).
+ */
+export interface JsFnHandle {
+    _jsFnId?: number;
+    _execId?: number;
+    _fn?: (...args: unknown[]) => unknown;
+    _isFirstScreen?: boolean;
+    _error?: string;
+}
+interface WorkletCtx {
+    _wkltId: string;
+    _execId?: number;
+    _c?: Record<string, unknown>;
+    _jsFn?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+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 resetRunOnBackgroundState(): void;
+export {};

package/dist/shadow-element.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare class ShadowElement {
+    static nextId: number;
+    id: number;
+    type: string;
+    parent: ShadowElement | null;
+    firstChild: ShadowElement | null;
+    lastChild: ShadowElement | null;
+    prev: ShadowElement | null;
+    next: ShadowElement | null;
+    _style: Record<string, unknown>;
+    _vShowHidden: boolean;
+    _baseClass: string;
+    _transitionClasses: Set<string>;
+    constructor(type: string, forceId?: number);
+    insertBefore(child: ShadowElement, anchor: ShadowElement | null): void;
+    removeChild(child: ShadowElement): void;
+}
+export declare const PAGE_ROOT_ID = 1;
+/** Create the page root shadow element with the reserved id=1. */
+export declare function createPageRoot(): ShadowElement;
+/** Reset the ID counter — for testing only. */
+export declare function resetShadowState(): void;

package/dist/threading.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-thread function invocation primitives for Lynx MTS.
+ *
+ * - runOnMainThread(fn): BG → MT — invoke a function on the Main Thread
+ * - runOnBackground(fn): MT → BG — invoke a function on the Background Thread
+ *
+ * ## Worklet placeholder semantics (Phase 1b)
+ *
+ * The `'main thread'` directive inside the function passed to runOnMainThread
+ * tells the build pipeline (`@lynx-js/react/transform`) to:
+ *   1. Replace the function with a `{ _wkltId }` placeholder in the BG bundle.
+ *   2. Emit a `registerWorkletInternal("main-thread", "<wkltId>", function(...) { ... })`
+ *      call into the MT bundle that registers the function in the MT-side worklet
+ *      registry.
+ *
+ * At runtime, runOnMainThread receives the placeholder, returns a callable, and
+ * each invocation ships `{ wkltId, args }` over `callLepusMethod('sigxRunOnMT')`
+ * to the MT bridge installed in `entry-main.ts`.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { runOnMainThread, runOnBackground } from '@sigx/lynx-runtime';
+ *
+ * const updateOffset = runOnMainThread((offset: number) => {
+ *   'main thread';
+ *   ref.current?.setStyleProperties({ transform: `translateX(${offset}px)` });
+ * });
+ * updateOffset(100);
+ * ```
+ *
+ * The `(offset) => { 'main thread'; ... }` source is what the user writes; after
+ * the build transform it becomes `{ _wkltId: '...' }` at this call site.
+ */
+interface WorkletPlaceholder {
+    _wkltId: string;
+    _c?: Record<string, unknown>;
+}
+export declare function runOnMainThread<TArgs extends unknown[]>(worklet: WorkletPlaceholder | ((...args: TArgs) => unknown)): (...args: TArgs) => Promise<unknown>;
+export { runOnBackground, transformToWorklet, resetRunOnBackgroundState, } from './run-on-background.js';
+export declare function resetThreading(): void;

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Module augmentation for Lynx platform.
+ *
+ * Sets `PlatformTypes.element = ShadowElement` so generic helpers in
+ * @sigx/runtime-core that read the per-platform element type pick up
+ * our shadow tree node.
+ *
+ * Mirrors packages/runtime-terminal/src/types.ts exactly.
+ */
+import type { ShadowElement } from './shadow-element.js';
+declare module '@sigx/runtime-core' {
+    /** Lynx platform sets ShadowElement as the default element type */
+    interface PlatformTypes {
+        element: ShadowElement;
+    }
+}
+export {};