@mindees/renderer 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -16,7 +16,7 @@ import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@min
 /** The npm package name. */
 declare const name = "@mindees/renderer";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.7.0";
 /**
  * Current maturity. The Helix **web/DOM** renderer (reconciler, DOM backend,
  * headless backend, SSR + hydration) is implemented and tested. Native

package/dist/index.js

@@ -15,7 +15,7 @@ import { NotImplementedError, notImplemented } from "@mindees/core";
 /** The npm package name. */
 const name = "@mindees/renderer";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 /**
 * Current maturity. The Helix **web/DOM** renderer (reconciler, DOM backend,
 * headless backend, SSR + hydration) is implemented and tested. Native

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** Host-backend contract + capability detection. */\nexport {\n  type HostBackend,\n  isSerializable,\n  type SerializableBackend,\n} from './backend'\n/** DOM (web) backend. */\nexport {\n  createDomBackend,\n  type DomDocument,\n  type DomElement,\n  type DomNode,\n  type DomText,\n  domTagFor,\n} from './dom'\n/** Keyed list reconciliation (the renderer side of core's KeyedRegion). */\nexport { bindKeyedChild } from './for'\n/** Headless (in-memory) backend — the reference/test target. */\nexport {\n  createHeadlessBackend,\n  createHeadlessRoot,\n  type HeadlessNode,\n  isEventProp,\n} from './headless'\n/**\n * Native backends. `createNativeCommandBackend` is implemented (emits a native\n * command stream); `createNativeBackend`/`createCanvasBackend` are research\n * tracks that throw `NotImplementedError`.\n */\nexport {\n  type CanvasBackend,\n  createCanvasBackend,\n  createNativeBackend,\n  createNativeCommandBackend,\n  type NativeBackend,\n  type NativeCommandBackend,\n  type NativeCommandBackendOptions,\n  type NativeCommandNode,\n} from './native'\n/** One-call native app entry — wires the command backend + host contract. */\nexport {\n  type CreateNativeAppOptions,\n  createNativeApp,\n  type NativeApp,\n} from './native-app'\n/**\n * The strict reference native host — applies a command stream to a model tree and\n * validates it (the executable conformance contract real native hosts implement).\n */\nexport {\n  createReferenceHost,\n  NativeHostError,\n  type ReferenceHost,\n  type ReferenceHostNode,\n} from './native-host'\n/** The native command protocol: command types + serialization-safe helpers. */\nexport {\n  type CreateNodeCommand,\n  type CreateTextCommand,\n  createNativeNodeIdFactory,\n  type DisposeNodeCommand,\n  type InsertChildCommand,\n  isNativeCommand,\n  isNativePropValue,\n  type NativeCommand,\n  type NativeNodeId,\n  type NativePropValue,\n  normalizeNativeProp,\n  type RegisterEventCommand,\n  type RemoveChildCommand,\n  type RemovePropCommand,\n  type SetPropCommand,\n  type UnregisterEventCommand,\n  type UpdateTextCommand,\n} from './native-protocol'\n/** Portal reconciliation (the renderer side of core's PortalRegion). */\nexport { bindPortalChild } from './portal'\n/** The fine-grained reactive reconciler. */\nexport { type Mounted, mountNode, render } from './render'\n/** Server-side rendering + hydration (web). */\nexport { hydrate, renderToString } from './ssr'\n\n/** The npm package name. */\nexport const name = '@mindees/renderer'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.5.0'\n\n/**\n * Current maturity. The Helix **web/DOM** renderer (reconciler, DOM backend,\n * headless backend, SSR + hydration) is implemented and tested. Native\n * (iOS/Android) and the GPU canvas are research tracks (throw\n * `NotImplementedError`). See the repository `STATUS.md`.\n */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;;;;;AAsFA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;AAQvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** Host-backend contract + capability detection. */\nexport {\n  type HostBackend,\n  isSerializable,\n  type SerializableBackend,\n} from './backend'\n/** DOM (web) backend. */\nexport {\n  createDomBackend,\n  type DomDocument,\n  type DomElement,\n  type DomNode,\n  type DomText,\n  domTagFor,\n} from './dom'\n/** Keyed list reconciliation (the renderer side of core's KeyedRegion). */\nexport { bindKeyedChild } from './for'\n/** Headless (in-memory) backend — the reference/test target. */\nexport {\n  createHeadlessBackend,\n  createHeadlessRoot,\n  type HeadlessNode,\n  isEventProp,\n} from './headless'\n/**\n * Native backends. `createNativeCommandBackend` is implemented (emits a native\n * command stream); `createNativeBackend`/`createCanvasBackend` are research\n * tracks that throw `NotImplementedError`.\n */\nexport {\n  type CanvasBackend,\n  createCanvasBackend,\n  createNativeBackend,\n  createNativeCommandBackend,\n  type NativeBackend,\n  type NativeCommandBackend,\n  type NativeCommandBackendOptions,\n  type NativeCommandNode,\n} from './native'\n/** One-call native app entry — wires the command backend + host contract. */\nexport {\n  type CreateNativeAppOptions,\n  createNativeApp,\n  type NativeApp,\n} from './native-app'\n/**\n * The strict reference native host — applies a command stream to a model tree and\n * validates it (the executable conformance contract real native hosts implement).\n */\nexport {\n  createReferenceHost,\n  NativeHostError,\n  type ReferenceHost,\n  type ReferenceHostNode,\n} from './native-host'\n/** The native command protocol: command types + serialization-safe helpers. */\nexport {\n  type CreateNodeCommand,\n  type CreateTextCommand,\n  createNativeNodeIdFactory,\n  type DisposeNodeCommand,\n  type InsertChildCommand,\n  isNativeCommand,\n  isNativePropValue,\n  type NativeCommand,\n  type NativeNodeId,\n  type NativePropValue,\n  normalizeNativeProp,\n  type RegisterEventCommand,\n  type RemoveChildCommand,\n  type RemovePropCommand,\n  type SetPropCommand,\n  type UnregisterEventCommand,\n  type UpdateTextCommand,\n} from './native-protocol'\n/** Portal reconciliation (the renderer side of core's PortalRegion). */\nexport { bindPortalChild } from './portal'\n/** The fine-grained reactive reconciler. */\nexport { type Mounted, mountNode, render } from './render'\n/** Server-side rendering + hydration (web). */\nexport { hydrate, renderToString } from './ssr'\n\n/** The npm package name. */\nexport const name = '@mindees/renderer'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.7.0'\n\n/**\n * Current maturity. The Helix **web/DOM** renderer (reconciler, DOM backend,\n * headless backend, SSR + hydration) is implemented and tested. Native\n * (iOS/Android) and the GPU canvas are research tracks (throw\n * `NotImplementedError`). See the repository `STATUS.md`.\n */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;;;;;AAsFA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;AAQvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}

package/dist/native-app.d.ts

@@ -2,12 +2,18 @@ import { NativeNodeId } from "./native-protocol.js";
 import { MindeesNode } from "@mindees/core";
 
 //#region src/native-app.d.ts
-/** The contract a native host drives: render once, then dispatch events by id. */
+/** The contract a native host drives: render once, dispatch events, and tick frames. */
 interface NativeApp {
   /** Mount the app and flush the initial command batch to the host. */
   start(): void;
   /** Invoke a registered handler (a native event fired), then flush the resulting batch. */
   dispatchEvent(handlerId: string, event?: unknown): boolean;
+  /**
+   * Advance animations by one frame: forward the host's vsync timestamp (ms) to the animation
+   * engine, then flush the resulting command batch. The host calls this each vsync while the frame
+   * loop is active (see {@link CreateNativeAppOptions}). A no-op when no frame source is installed.
+   */
+  frameTick(nowMs: number): void;
 }
 /** Options for {@link createNativeApp}. */
 interface CreateNativeAppOptions {
@@ -22,11 +28,26 @@ interface CreateNativeAppOptions {
    */
   readonly emit?: (json: string) => void;
   /**
-   * Expose the app on a global so the host can call `start()`/`dispatchEvent()`.
+   * Expose the app on a global so the host can call `start()`/`dispatchEvent()`/`frameTick()`.
    * `true` (default) → `globalThis.MindeesApp`; a string → that global name; `false` →
    * don't expose (use the returned handle directly, e.g. in Node tests).
    */
   readonly expose?: boolean | string;
+  /**
+   * Install the reactive scheduler that powers `startTransition`/`deferred`/normal-lane effects.
+   * `createNativeApp` owns this scheduler so it can flush the command batch after each microtask
+   * drain (otherwise deferred mutations would recompute but never reach the host). Pass `false` to
+   * run the pure synchronous lane; to use a fully custom scheduler, pass `false` and call
+   * `setReactiveScheduler` yourself (you then own flushing).
+   */
+  readonly scheduler?: false;
+  /**
+   * Install the reactive scheduler + the vsync frame source. Default: `true` when the app is
+   * exposed AND a host (`globalThis.MindeesHost`) is present — so SSR/Node/tests install nothing
+   * and keep the synchronous jump-to-final behavior. Pass `true` to force-wire (e.g. tests driving
+   * `frameTick` directly).
+   */
+  readonly wireEngines?: boolean;
 }
 /**
  * Wire a root node to a native command host. Returns the {@link NativeApp} handle and

package/dist/native-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-app.d.ts","names":[],"sources":["../src/native-app.ts"],"mappings":";;;;;UA0BiB,SAAA;EAwBA;EAtBf,KAAA;EAuCc;EArCd,aAAA,CAAc,SAAA,UAAmB,KAAA;AAAA;;UAIlB,sBAAA;EAoCd;;;;EAAA,SA/BQ,MAAA,GAAS,YAAY;EA8BrB;;;;EAAA,SAzBA,IAAA,IAAQ,IAAA;;;;;;WAMR,MAAA;AAAA;;;;;iBAiBK,eAAA,CACd,IAAA,EAAM,WAAA,EACN,OAAA,GAAS,sBAAA,GACR,SAAA"}
+{"version":3,"file":"native-app.d.ts","names":[],"sources":["../src/native-app.ts"],"mappings":";;;;;UAmDiB,SAAA;EA2Ed;EAzED,KAAA;EAyEU;EAvEV,aAAA,CAAc,SAAA,UAAmB,KAAA;EAqEjC;;;;;EA/DA,SAAA,CAAU,KAAA;AAAA;;UASK,sBAAA;;;;;WAKN,MAAA,GAAS,YAAY;;;;;WAKrB,IAAA,IAAQ,IAAA;;;;;;WAMR,MAAA;;;;;;;;WAQA,SAAA;;;;;;;WAOA,WAAA;AAAA;;;;;iBAsBK,eAAA,CACd,IAAA,EAAM,WAAA,EACN,OAAA,GAAS,sBAAA,GACR,SAAA"}

package/dist/native-app.js

@@ -1,11 +1,44 @@
 import { render } from "./render.js";
 import { createNativeCommandBackend } from "./native-command-backend.js";
+import { createScheduler, setFrameSource, setReactiveScheduler } from "@mindees/core";
 //#region src/native-app.ts
+/**
+* `createNativeApp` — the one-call entry point for a MindeesNative app on an embedded
+* native host. It hides the wiring an app author should never have to write: creating
+* the {@link createNativeCommandBackend}, rendering the root, flushing the command
+* batch to the host, and exposing the start/dispatch/frame contract the host calls.
+*
+* ```tsx
+* import { createNativeApp } from '@mindees/renderer'
+* import { App } from './App'
+*
+* createNativeApp(<App />)
+* ```
+*
+* That's the whole entry file. The native host (see `examples/native-hosts/`) injects a
+* `MindeesHost.emit(json)` global and calls `MindeesApp.start()` once, then
+* `MindeesApp.dispatchEvent(handlerId)` per native event — both of which this wires.
+*
+* On a host it also makes animations + concurrency **work by default**: it installs a
+* reactive {@link Scheduler} (so `startTransition`/`deferred`/normal-lane effects run) and a
+* vsync-driven {@link FrameSource} (so `timing`/`spring`/gesture animations advance). The host
+* drives frames by calling `MindeesApp.frameTick(nowMs)` each vsync, and the engine signals when
+* to start/stop that loop through a `MindeesHostFrame.setFrameLoopActive(boolean)` global — so the
+* vsync loop runs **only while something is animating** (battery-friendly), tied to the animation
+* engine's own arm/sleep. With no host (SSR / Node / tests) nothing is installed and animations
+* jump straight to their final value, exactly as before.
+*
+* @module
+*/
+let enginesWired = false;
 function defaultEmit(json) {
 	const host = globalThis.MindeesHost;
 	if (!host || typeof host.emit !== "function") throw new Error("createNativeApp: no `emit` was provided and globalThis.MindeesHost.emit is unavailable");
 	host.emit(json);
 }
+function hostIsPresent() {
+	return typeof globalThis.MindeesHost?.emit === "function";
+}
 /**
 * Wire a root node to a native command host. Returns the {@link NativeApp} handle and
 * (unless `expose: false`) publishes it as `globalThis.MindeesApp` for the host to call.
@@ -17,6 +50,51 @@ function createNativeApp(root, options = {}) {
 		const batch = backend.flushCommands();
 		if (batch.length > 0) emit(JSON.stringify(batch));
 	};
+	const expose = options.expose ?? true;
+	const wireEngines = options.wireEngines ?? (expose !== false && hostIsPresent());
+	let storedTick = null;
+	if (wireEngines) {
+		if (enginesWired) throw new Error("createNativeApp: the reactive engines are already wired by another app instance. Create one app per runtime, or pass `wireEngines: false` (and wire the scheduler/frame source yourself).");
+		enginesWired = true;
+		if (options.scheduler !== false) {
+			let flushQueued = false;
+			const trailingFlush = () => {
+				if (flushQueued) return;
+				flushQueued = true;
+				queueMicrotask(() => {
+					flushQueued = false;
+					flush();
+				});
+			};
+			setReactiveScheduler(createScheduler({
+				scheduleMicrotask: (cb) => queueMicrotask(() => {
+					cb();
+					trailingFlush();
+				}),
+				onError: (error) => {
+					queueMicrotask(() => {
+						throw error;
+					});
+				}
+			}));
+		}
+		const hostFrame = globalThis.MindeesHostFrame;
+		if (hostFrame) {
+			const frameSource = (tick) => {
+				storedTick = tick;
+				try {
+					hostFrame.setFrameLoopActive?.(true);
+				} catch {}
+				return () => {
+					storedTick = null;
+					try {
+						hostFrame.setFrameLoopActive?.(false);
+					} catch {}
+				};
+			};
+			setFrameSource(frameSource);
+		}
+	}
 	const app = {
 		start() {
 			render(root, backend, backend.root);
@@ -26,9 +104,12 @@ function createNativeApp(root, options = {}) {
 			const handled = backend.dispatchEvent(handlerId, event);
 			flush();
 			return handled;
+		},
+		frameTick(nowMs) {
+			if (storedTick) storedTick(nowMs);
+			flush();
 		}
 	};
-	const expose = options.expose ?? true;
 	if (expose !== false) {
 		const name = typeof expose === "string" ? expose : "MindeesApp";
 		globalThis[name] = app;

package/dist/native-app.js.map

@@ -1 +1 @@
-{"version":3,"file":"native-app.js","names":[],"sources":["../src/native-app.ts"],"sourcesContent":["/**\n * `createNativeApp` — the one-call entry point for a MindeesNative app on an embedded\n * native host. It hides the wiring an app author should never have to write: creating\n * the {@link createNativeCommandBackend}, rendering the root, flushing the command\n * batch to the host, and exposing the start/dispatch contract the host calls.\n *\n * ```tsx\n * import { createNativeApp } from '@mindees/renderer'\n * import { App } from './App'\n *\n * createNativeApp(<App />)\n * ```\n *\n * That's the whole entry file. The native host (see `examples/native-hosts/`) injects\n * a `MindeesHost.emit(json)` global and calls `MindeesApp.start()` once, then\n * `MindeesApp.dispatchEvent(handlerId)` per native event — both of which this wires.\n *\n * @module\n */\n\nimport type { MindeesNode } from '@mindees/core'\nimport { createNativeCommandBackend } from './native-command-backend'\nimport type { NativeNodeId } from './native-protocol'\nimport { render } from './render'\n\n/** The contract a native host drives: render once, then dispatch events by id. */\nexport interface NativeApp {\n  /** Mount the app and flush the initial command batch to the host. */\n  start(): void\n  /** Invoke a registered handler (a native event fired), then flush the resulting batch. */\n  dispatchEvent(handlerId: string, event?: unknown): boolean\n}\n\n/** Options for {@link createNativeApp}. */\nexport interface CreateNativeAppOptions {\n  /**\n   * Id of the host's pre-existing root container. Defaults to `\"host-root\"` — the\n   * convention the reference hosts register — so the common case needs no config.\n   */\n  readonly rootId?: NativeNodeId\n  /**\n   * How to deliver a command batch to the host. Defaults to `globalThis.MindeesHost.emit`\n   * (what the embedded hosts inject). Override in tests or alternative transports.\n   */\n  readonly emit?: (json: string) => void\n  /**\n   * Expose the app on a global so the host can call `start()`/`dispatchEvent()`.\n   * `true` (default) → `globalThis.MindeesApp`; a string → that global name; `false` →\n   * don't expose (use the returned handle directly, e.g. in Node tests).\n   */\n  readonly expose?: boolean | string\n}\n\nfunction defaultEmit(json: string): void {\n  const host = (globalThis as { MindeesHost?: { emit?: (json: string) => void } }).MindeesHost\n  if (!host || typeof host.emit !== 'function') {\n    throw new Error(\n      'createNativeApp: no `emit` was provided and globalThis.MindeesHost.emit is unavailable',\n    )\n  }\n  host.emit(json)\n}\n\n/**\n * Wire a root node to a native command host. Returns the {@link NativeApp} handle and\n * (unless `expose: false`) publishes it as `globalThis.MindeesApp` for the host to call.\n */\nexport function createNativeApp(\n  root: MindeesNode,\n  options: CreateNativeAppOptions = {},\n): NativeApp {\n  const backend = createNativeCommandBackend({ rootId: options.rootId ?? 'host-root' })\n  const emit = options.emit ?? defaultEmit\n\n  const flush = (): void => {\n    const batch = backend.flushCommands()\n    if (batch.length > 0) emit(JSON.stringify(batch))\n  }\n\n  const app: NativeApp = {\n    start(): void {\n      render(root, backend, backend.root)\n      flush()\n    },\n    dispatchEvent(handlerId: string, event?: unknown): boolean {\n      const handled = backend.dispatchEvent(handlerId, event)\n      flush()\n      return handled\n    },\n  }\n\n  const expose = options.expose ?? true\n  if (expose !== false) {\n    const name = typeof expose === 'string' ? expose : 'MindeesApp'\n    ;(globalThis as Record<string, unknown>)[name] = app\n  }\n\n  return app\n}\n"],"mappings":";;;AAqDA,SAAS,YAAY,MAAoB;CACvC,MAAM,OAAQ,WAAmE;CACjF,IAAI,CAAC,QAAQ,OAAO,KAAK,SAAS,YAChC,MAAM,IAAI,MACR,wFACF;CAEF,KAAK,KAAK,IAAI;AAChB;;;;;AAMA,SAAgB,gBACd,MACA,UAAkC,CAAC,GACxB;CACX,MAAM,UAAU,2BAA2B,EAAE,QAAQ,QAAQ,UAAU,YAAY,CAAC;CACpF,MAAM,OAAO,QAAQ,QAAQ;CAE7B,MAAM,cAAoB;EACxB,MAAM,QAAQ,QAAQ,cAAc;EACpC,IAAI,MAAM,SAAS,GAAG,KAAK,KAAK,UAAU,KAAK,CAAC;CAClD;CAEA,MAAM,MAAiB;EACrB,QAAc;GACZ,OAAO,MAAM,SAAS,QAAQ,IAAI;GAClC,MAAM;EACR;EACA,cAAc,WAAmB,OAA0B;GACzD,MAAM,UAAU,QAAQ,cAAc,WAAW,KAAK;GACtD,MAAM;GACN,OAAO;EACT;CACF;CAEA,MAAM,SAAS,QAAQ,UAAU;CACjC,IAAI,WAAW,OAAO;EACpB,MAAM,OAAO,OAAO,WAAW,WAAW,SAAS;EAClD,WAAwC,QAAQ;CACnD;CAEA,OAAO;AACT"}
+{"version":3,"file":"native-app.js","names":[],"sources":["../src/native-app.ts"],"sourcesContent":["/**\n * `createNativeApp` — the one-call entry point for a MindeesNative app on an embedded\n * native host. It hides the wiring an app author should never have to write: creating\n * the {@link createNativeCommandBackend}, rendering the root, flushing the command\n * batch to the host, and exposing the start/dispatch/frame contract the host calls.\n *\n * ```tsx\n * import { createNativeApp } from '@mindees/renderer'\n * import { App } from './App'\n *\n * createNativeApp(<App />)\n * ```\n *\n * That's the whole entry file. The native host (see `examples/native-hosts/`) injects a\n * `MindeesHost.emit(json)` global and calls `MindeesApp.start()` once, then\n * `MindeesApp.dispatchEvent(handlerId)` per native event — both of which this wires.\n *\n * On a host it also makes animations + concurrency **work by default**: it installs a\n * reactive {@link Scheduler} (so `startTransition`/`deferred`/normal-lane effects run) and a\n * vsync-driven {@link FrameSource} (so `timing`/`spring`/gesture animations advance). The host\n * drives frames by calling `MindeesApp.frameTick(nowMs)` each vsync, and the engine signals when\n * to start/stop that loop through a `MindeesHostFrame.setFrameLoopActive(boolean)` global — so the\n * vsync loop runs **only while something is animating** (battery-friendly), tied to the animation\n * engine's own arm/sleep. With no host (SSR / Node / tests) nothing is installed and animations\n * jump straight to their final value, exactly as before.\n *\n * @module\n */\n\nimport {\n  createScheduler,\n  type FrameSource,\n  type MindeesNode,\n  setFrameSource,\n  setReactiveScheduler,\n} from '@mindees/core'\nimport { createNativeCommandBackend } from './native-command-backend'\nimport type { NativeNodeId } from './native-protocol'\nimport { render } from './render'\n\n// The reactive scheduler + animation frame source are PROCESS globals (one per runtime). This guard\n// makes a second `createNativeApp` that would re-wire them fail loudly instead of silently stealing\n// the first app's engines. Reset with `_resetNativeAppEngines()` between tests.\nlet enginesWired = false\n\n/** @internal Test-only: reset the process-global engine-wiring guard. */\nexport function _resetNativeAppEngines(): void {\n  enginesWired = false\n}\n\n/** The contract a native host drives: render once, dispatch events, and tick frames. */\nexport interface NativeApp {\n  /** Mount the app and flush the initial command batch to the host. */\n  start(): void\n  /** Invoke a registered handler (a native event fired), then flush the resulting batch. */\n  dispatchEvent(handlerId: string, event?: unknown): boolean\n  /**\n   * Advance animations by one frame: forward the host's vsync timestamp (ms) to the animation\n   * engine, then flush the resulting command batch. The host calls this each vsync while the frame\n   * loop is active (see {@link CreateNativeAppOptions}). A no-op when no frame source is installed.\n   */\n  frameTick(nowMs: number): void\n}\n\n/** The JS→host battery signal: the engine asks the host to run / stop its vsync loop. */\ninterface HostFrameApi {\n  setFrameLoopActive?: (active: boolean) => void\n}\n\n/** Options for {@link createNativeApp}. */\nexport interface CreateNativeAppOptions {\n  /**\n   * Id of the host's pre-existing root container. Defaults to `\"host-root\"` — the\n   * convention the reference hosts register — so the common case needs no config.\n   */\n  readonly rootId?: NativeNodeId\n  /**\n   * How to deliver a command batch to the host. Defaults to `globalThis.MindeesHost.emit`\n   * (what the embedded hosts inject). Override in tests or alternative transports.\n   */\n  readonly emit?: (json: string) => void\n  /**\n   * Expose the app on a global so the host can call `start()`/`dispatchEvent()`/`frameTick()`.\n   * `true` (default) → `globalThis.MindeesApp`; a string → that global name; `false` →\n   * don't expose (use the returned handle directly, e.g. in Node tests).\n   */\n  readonly expose?: boolean | string\n  /**\n   * Install the reactive scheduler that powers `startTransition`/`deferred`/normal-lane effects.\n   * `createNativeApp` owns this scheduler so it can flush the command batch after each microtask\n   * drain (otherwise deferred mutations would recompute but never reach the host). Pass `false` to\n   * run the pure synchronous lane; to use a fully custom scheduler, pass `false` and call\n   * `setReactiveScheduler` yourself (you then own flushing).\n   */\n  readonly scheduler?: false\n  /**\n   * Install the reactive scheduler + the vsync frame source. Default: `true` when the app is\n   * exposed AND a host (`globalThis.MindeesHost`) is present — so SSR/Node/tests install nothing\n   * and keep the synchronous jump-to-final behavior. Pass `true` to force-wire (e.g. tests driving\n   * `frameTick` directly).\n   */\n  readonly wireEngines?: boolean\n}\n\nfunction defaultEmit(json: string): void {\n  const host = (globalThis as { MindeesHost?: { emit?: (json: string) => void } }).MindeesHost\n  if (!host || typeof host.emit !== 'function') {\n    throw new Error(\n      'createNativeApp: no `emit` was provided and globalThis.MindeesHost.emit is unavailable',\n    )\n  }\n  host.emit(json)\n}\n\nfunction hostIsPresent(): boolean {\n  const host = (globalThis as { MindeesHost?: { emit?: unknown } }).MindeesHost\n  return typeof host?.emit === 'function'\n}\n\n/**\n * Wire a root node to a native command host. Returns the {@link NativeApp} handle and\n * (unless `expose: false`) publishes it as `globalThis.MindeesApp` for the host to call.\n */\nexport function createNativeApp(\n  root: MindeesNode,\n  options: CreateNativeAppOptions = {},\n): NativeApp {\n  const backend = createNativeCommandBackend({ rootId: options.rootId ?? 'host-root' })\n  const emit = options.emit ?? defaultEmit\n\n  const flush = (): void => {\n    const batch = backend.flushCommands()\n    if (batch.length > 0) emit(JSON.stringify(batch))\n  }\n\n  const expose = options.expose ?? true\n  const wireEngines = options.wireEngines ?? (expose !== false && hostIsPresent())\n\n  // The engine's onFrame, captured when the animation loop subscribes; `frameTick` drives it.\n  let storedTick: ((nowMs: number) => void) | null = null\n\n  if (wireEngines) {\n    if (enginesWired) {\n      // The reactive scheduler + frame source are process globals; a second wiring would silently\n      // steal the first app's engines. Fail loudly instead. (One app per runtime; tests reset via\n      // _resetNativeAppEngines.)\n      throw new Error(\n        'createNativeApp: the reactive engines are already wired by another app instance. Create one ' +\n          'app per runtime, or pass `wireEngines: false` (and wire the scheduler/frame source yourself).',\n      )\n    }\n    enginesWired = true\n\n    // A microtask-drained scheduler. After each drained task we run ONE coalesced trailing flush so\n    // deferred/startTransition/normal-lane tree mutations (which land on a microtask, outside the\n    // frameTick + dispatchEvent windows) still reach the host — one frame late, never dropped. We\n    // OWN this scheduler so the trailing flush is always wired (a custom scheduler couldn't be).\n    if (options.scheduler !== false) {\n      let flushQueued = false\n      const trailingFlush = (): void => {\n        if (flushQueued) return\n        flushQueued = true\n        queueMicrotask(() => {\n          flushQueued = false\n          flush()\n        })\n      }\n      setReactiveScheduler(\n        createScheduler({\n          scheduleMicrotask: (cb) =>\n            queueMicrotask(() => {\n              cb()\n              trailingFlush()\n            }),\n          onError: (error) => {\n            // Surface a scheduled-task error instead of swallowing it (uncaught → host log).\n            queueMicrotask(() => {\n              throw error\n            })\n          },\n        }),\n      )\n    }\n\n    // The vsync frame source: capture the engine's tick + signal the host to run/stop its loop. The\n    // subscribe (START) fires the instant the first animation driver arms the loop; the unsubscribe\n    // (STOP) fires the instant the last driver settles — so the host's vsync loop runs ONLY while\n    // something animates (the battery win), with no separate heuristic to keep in sync.\n    //\n    // CRITICAL: only install the source when a host can actually DRIVE it (MindeesHostFrame present,\n    // i.e. there's a `frameTick` caller + a `setFrameLoopActive` listener). Arming a loop that\n    // nothing ticks would FREEZE animations at their start value — strictly worse than jumping to\n    // the final value. With no driver, leave the source null → animations jump-to-final (safe).\n    const hostFrame = (globalThis as { MindeesHostFrame?: HostFrameApi }).MindeesHostFrame\n    if (hostFrame) {\n      const frameSource: FrameSource = (tick) => {\n        storedTick = tick\n        try {\n          hostFrame.setFrameLoopActive?.(true)\n        } catch {\n          // a throwing host signal must not break arming the loop\n        }\n        return () => {\n          storedTick = null\n          try {\n            hostFrame.setFrameLoopActive?.(false)\n          } catch {\n            // ditto: always stop the loop even if the host signal throws\n          }\n        }\n      }\n      setFrameSource(frameSource)\n    }\n  }\n\n  const app: NativeApp = {\n    start(): void {\n      render(root, backend, backend.root)\n      flush()\n    },\n    dispatchEvent(handlerId: string, event?: unknown): boolean {\n      const handled = backend.dispatchEvent(handlerId, event)\n      flush()\n      return handled\n    },\n    frameTick(nowMs: number): void {\n      if (storedTick) storedTick(nowMs)\n      flush()\n    },\n  }\n\n  if (expose !== false) {\n    const name = typeof expose === 'string' ? expose : 'MindeesApp'\n    ;(globalThis as Record<string, unknown>)[name] = app\n  }\n\n  return app\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAI,eAAe;AA6DnB,SAAS,YAAY,MAAoB;CACvC,MAAM,OAAQ,WAAmE;CACjF,IAAI,CAAC,QAAQ,OAAO,KAAK,SAAS,YAChC,MAAM,IAAI,MACR,wFACF;CAEF,KAAK,KAAK,IAAI;AAChB;AAEA,SAAS,gBAAyB;CAEhC,OAAO,OADO,WAAoD,aAC9C,SAAS;AAC/B;;;;;AAMA,SAAgB,gBACd,MACA,UAAkC,CAAC,GACxB;CACX,MAAM,UAAU,2BAA2B,EAAE,QAAQ,QAAQ,UAAU,YAAY,CAAC;CACpF,MAAM,OAAO,QAAQ,QAAQ;CAE7B,MAAM,cAAoB;EACxB,MAAM,QAAQ,QAAQ,cAAc;EACpC,IAAI,MAAM,SAAS,GAAG,KAAK,KAAK,UAAU,KAAK,CAAC;CAClD;CAEA,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAM,cAAc,QAAQ,gBAAgB,WAAW,SAAS,cAAc;CAG9E,IAAI,aAA+C;CAEnD,IAAI,aAAa;EACf,IAAI,cAIF,MAAM,IAAI,MACR,2LAEF;EAEF,eAAe;EAMf,IAAI,QAAQ,cAAc,OAAO;GAC/B,IAAI,cAAc;GAClB,MAAM,sBAA4B;IAChC,IAAI,aAAa;IACjB,cAAc;IACd,qBAAqB;KACnB,cAAc;KACd,MAAM;IACR,CAAC;GACH;GACA,qBACE,gBAAgB;IACd,oBAAoB,OAClB,qBAAqB;KACnB,GAAG;KACH,cAAc;IAChB,CAAC;IACH,UAAU,UAAU;KAElB,qBAAqB;MACnB,MAAM;KACR,CAAC;IACH;GACF,CAAC,CACH;EACF;EAWA,MAAM,YAAa,WAAmD;EACtE,IAAI,WAAW;GACb,MAAM,eAA4B,SAAS;IACzC,aAAa;IACb,IAAI;KACF,UAAU,qBAAqB,IAAI;IACrC,QAAQ,CAER;IACA,aAAa;KACX,aAAa;KACb,IAAI;MACF,UAAU,qBAAqB,KAAK;KACtC,QAAQ,CAER;IACF;GACF;GACA,eAAe,WAAW;EAC5B;CACF;CAEA,MAAM,MAAiB;EACrB,QAAc;GACZ,OAAO,MAAM,SAAS,QAAQ,IAAI;GAClC,MAAM;EACR;EACA,cAAc,WAAmB,OAA0B;GACzD,MAAM,UAAU,QAAQ,cAAc,WAAW,KAAK;GACtD,MAAM;GACN,OAAO;EACT;EACA,UAAU,OAAqB;GAC7B,IAAI,YAAY,WAAW,KAAK;GAChC,MAAM;EACR;CACF;CAEA,IAAI,WAAW,OAAO;EACpB,MAAM,OAAO,OAAO,WAAW,WAAW,SAAS;EAClD,WAAwC,QAAQ;CACnD;CAEA,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindees/renderer",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MindeesNative Helix — fine-grained reactive renderer with a web/DOM backend, SSR + hydration, and a headless test backend. Native and GPU-canvas backends are research tracks.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -23,7 +23,7 @@
     "directory": "packages/renderer"
   },
   "dependencies": {
-    "@mindees/core": "0.5.0"
+    "@mindees/core": "0.7.0"
   },
   "devDependencies": {
     "happy-dom": "20.9.0"