lecodes-sdk 1.1.0 → 2.0.0

package/src/bridges/tree.d.ts

@@ -0,0 +1,301 @@
+// The UI tree bridge (`_creatorTree`): the runtime OWNS the UI tree — every node exists in
+// runtime/native's presentation from `create()` on (engines/ui Yoga + the screens / destinations /
+// widgets / pager / vlist model), and the SDK's element objects are HANDLES over it (docs/hosts-
+// unification-plan.md, phase 9). Nothing here reads a JS object: every argument is a node id or a
+// scalar, every event comes back through the one emitter with the node id. Part of the host
+// contract: every runtime implements this global (runtime/native in C++, the wasm build of the same
+// code for the simulator hosts). Types are the PRECISE ones the native side reads (./types.d.ts).
+import type { f32, f64, i32, i64, nodeid, u16, u32, u8 } from "./types"
+
+declare global {
+  /** A node id: the runtime's node pointer as a JS number (< 2^53). Stable for the node's life. */
+  type TreeNodeId = number
+
+  /** An OWNED handle (docs/plans/hosts-unification-plan.md, phase 10): what a `create…` call returns —
+   *  the resource's id on an object whose collection tells the runtime "the app dropped this" (a
+   *  class object with a finalizer on QuickJS / JSC, a FinalizationRegistry token in wasm). The
+   *  SDK wrapper keeps it as `_h` and uses `_h.id` on the wire; there is no other reference. */
+  interface Handle { readonly id: number }
+
+  var _creatorTree: {
+    // ---- nodes --------------------------------------------------------------------------------
+    // Create a node of `type` ("screen", "column", "text", "input", "pager", "vlist", "native", …) as
+    // a detached layout root; the host's view exists from here on (HostUI.nodeFactory). The node
+    // belongs to the JS handle until it gets a parent or is presented.
+    create(type: string): Handle
+    // Free a DETACHED subtree now (`node.destroy()`): yoga, the host views, the owner slots. A node
+    // that still has a parent or is presented is left alone (an error is logged). The handles of
+    // the freed descendants come back through `freed`.
+    destroy(id: TreeNodeId): void
+    // Attach `child` (a root) under `parent` at `index` (clamped); `remove` makes it a root again
+    // without freeing it. A pager parent takes PAGES (independent layout roots), a vlist parent takes
+    // nothing (items go through vlistMount).
+    insert(parent: TreeNodeId, child: TreeNodeId, index: i32): void
+    remove(parent: TreeNodeId, child: TreeNodeId): void
+    // The parent's id, 0 for a root; the children's ids (a pager's pages in tab-major order).
+    parent(id: TreeNodeId): TreeNodeId
+    children(id: TreeNodeId): TreeNodeId[]
+
+    // ---- content ------------------------------------------------------------------------------
+    // A content property as text: "text", "src" (a url; "id:<bufferId>" for a host buffer,
+    // "svg:<source>", "canvas:<surfaceId>", "scene2d:<sceneId>" — the SDK spells the prefixes),
+    // "value", "focus" ("1" / "0"), "sourceRect" ("x y w h"), "viewName", "viewParams" (JSON),
+    // "name". null clears. The runtime dirties a measured leaf's layout for text / src / value and
+    // forwards to the host. "srcTintColor" (a CSS color or var(), the source's own tint) is the
+    // exception: the runtime stores it as the node's tintColor on the core's SOURCE layer (under
+    // every style tint; a src write drops it) and never forwards it.
+    setString(id: TreeNodeId, key: string, value: string | null): void
+    // A small integer content property: "playerId" (a media player), "viewId" (a NativeView).
+    setInt(id: TreeNodeId, key: string, value: i32): void
+    // Which listeners / traits the node has (TREE_FLAG_* of the SDK's tree.ts, mirrored in
+    // runtime/native/src/presentation/tree-events.h): the host reads the mask for hit-testing
+    // and event routing; the runtime for the back chain and the interaction classes' scope (an
+    // INTERACTIVE node starts its own $hovered / $pressed / $focused). Replaces the whole mask.
+    setFlags(id: TreeNodeId, mask: u32): void
+    // An input's live text (the host's; "" for anything else).
+    getTextValue(id: TreeNodeId): string
+
+    // ---- style --------------------------------------------------------------------------------
+    setStyle(id: TreeNodeId, key: string, value: string | f64 | null): void
+    // A style bag: plain values, `{ _h }` owned handles (backgroundImage), nested state blocks
+    // (`$class` keys — `$pressed`, `$landscape`, `$checked`, …) under their own layer.
+    mergeStyle(id: TreeNodeId, style: object): void
+    // Toggle a user style class (`name` WITHOUT the `$`); cascades to descendants — engines/ui's
+    // setNodeClass owns the cascade, hosts add nothing. The reserved names (hovered pressed focused
+    // landscape portrait) are refused: the system toggles those.
+    setClass(id: TreeNodeId, name: string, enabled: boolean): void
+    // Theme variables: MERGES `values` (null removes a key, numbers are px lengths, a color is a
+    // string) and re-resolves live styles. Env names (safe-*, vw/vh/…) are reserved.
+    setTheme(values: Record<string, string | f64 | null>): void
+
+    // ---- presentation -------------------------------------------------------------------------
+    // A transition (sdk/src/ui/transitions.ts): a tween blob whose targets are ROLES — `roles[i]` is
+    // the role of the blob's target i (0 the incoming screen, 1 the outgoing one, 2 / 3 the same two
+    // playing ALONE: next to a scene / a native view / a video, which never move, or to nothing).
+    // `flags`: 1 = the incoming side is above the outgoing one. Registered once per world; the id
+    // (> 0) is what the calls below carry — 0 = no transition, -1 = the caller names none (a pop
+    // plays what the entry it pops remembers; a replace keeps the way back of the entry it replaces).
+    defineTransition(data: Float32Array, strings: string[], roles: i32[], flags: i32): i32
+    // Present a destination directly (suspends an active router until routerRestore). `kind` is
+    // TREE_DEST_* (0 screen: `id` = the screen node; 1 scene3d / 2 scene2d: `id` = the sceneId;
+    // 3 native: `id` = the NativeView's viewId, `viewName` + `paramsJson` its factory call; 4 video:
+    // `id` = the video node).
+    open(kind: u8, id: f64, viewName: string, paramsJson: string, transition: i32): void
+    // Dismiss the destination (kind, id) with no successor — only when it is the one on screen: a
+    // destination something else already replaced (a router init / push, another open) is left
+    // alone, so a late `scene.close()` never takes down the page that replaced the scene.
+    close(kind: u8, id: f64, transition: i32): void
+    // The router over destinations (the same (kind, id, viewName, paramsJson) tuple). The runtime
+    // reports every stack change through the `routerChange` event with the new top's (kind, id).
+    // `back` = the way back the new entry remembers: what a pop that names no transition, the edge
+    // swipe and the system's back play.
+    routerOpen(kind: u8, id: f64, viewName: string, paramsJson: string, showBackButton: boolean): void
+    routerPush(kind: u8, id: f64, viewName: string, paramsJson: string, transition: i32, back: i32): void
+    routerReplace(kind: u8, id: f64, viewName: string, paramsJson: string, transition: i32, back: i32): void
+    routerPop(index: i32, transition: i32): void
+    routerHide(transition: i32): void
+    routerRestore(transition: i32): void
+    // Does the host registerView(name)? / the contract version its half was generated from (0 = no
+    // such view; on a host that does not say, 1 for a view it has) / the NativeView method channel:
+    // `args` is the array of the call's arguments, the callbacks settle exactly once through the
+    // dispatch bridge. A value that cannot cross (runtime/native/src/values/js.h) throws here,
+    // before the host sees the call.
+    isViewSupported(name: string): boolean
+    viewVersion(name: string): i32
+    viewCall(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
+    // Show a widget root; `ownerKind` / `ownerId` bind it to a destination (widget.attachTo: it
+    // mounts inside that page and rides its transition) — TREE_DEST_NONE = a global overlay.
+    showWidget(id: TreeNodeId, ownerKind: u8, ownerId: f64): void
+    hideWidget(id: TreeNodeId): void
+
+    // ---- pager (a "pager" node's children are its pages; TAB-MAJOR order, `lens` = per-tab stack
+    //      lengths, `index` = the selected tab). A change of the current tab's stack plays a
+    //      transition like the router's — the same ids, the pager being the stage; `back` = the way
+    //      back the new entry remembers (what a pop that names none, the back button and the edge
+    //      swipe's fallback play) ----------------------------------------------------------------
+    pagerSetContent(id: TreeNodeId, pages: TreeNodeId[], lens: i32[], index: i32): void
+    pagerSelect(id: TreeNodeId, index: i32, animated: boolean): void
+    pagerPush(id: TreeNodeId, page: TreeNodeId, transition: i32, back: i32): void
+    pagerPop(id: TreeNodeId, transition: i32): void
+    pagerPopToRoot(id: TreeNodeId, transition: i32): void
+    pagerReplace(id: TreeNodeId, page: TreeNodeId, transition: i32, back: i32): void
+
+    // ---- virtualized list (the window math lives in engines/ui vlist.cpp) ----------------------
+    // Right after create("vlist"): the list's config (overscan px, -1 = a viewport; chat mode;
+    // the onStart / onEnd thresholds).
+    vlistInit(id: TreeNodeId, overscan: f32, inverted: boolean, startThreshold: f32, endThreshold: f32): void
+    vlistSetKeys(id: TreeNodeId, keys: string[], estimates: f32[]): void
+    vlistInsertKeys(id: TreeNodeId, index: i32, keys: string[], estimates: f32[]): void
+    vlistRemoveKeys(id: TreeNodeId, keys: string[]): void
+    vlistInvalidate(id: TreeNodeId, key: string): void
+    // From inside a `vlistSync` event, per mount key: the item subtree (a root) becomes the mounted
+    // item — the runtime measures it and anchors the window.
+    vlistMount(id: TreeNodeId, key: string, item: TreeNodeId): void
+    vlistScrollTo(id: TreeNodeId, offset: f32, animated: boolean): void
+    vlistScrollToKey(id: TreeNodeId, key: string, animated: boolean): void
+    vlistScrollToEnd(id: TreeNodeId, animated: boolean): void
+
+    // ---- misc ---------------------------------------------------------------------------------
+    // Load a font face (weight 100–900, style 0 normal / 2 italic); the callbacks settle once.
+    registerFont(fontFamily: string, url: string, weight: i32, style: i32, onComplete: () => void, onReject: () => void): void
+    // Preferred container format for CDN-served faces: "woff2" on browser hosts, absent (= "ttf")
+    // on native / headless — read by the font() macro's generated registration code.
+    fontFormat?: "woff2" | "ttf"
+    toast(message: string, durationMs: i32): void
+    // Is the button node pressed right now (the UIButton.isPressed getter)?
+    isButtonPressed(id: TreeNodeId): boolean
+    // Is the node the one under the mouse cursor (the runtime's hover state, presentation/hover.cpp)?
+    isHovered(id: TreeNodeId): boolean
+    // [left, top, width, height] in logical px, scroll included, read live; null when not laid out
+    // or on a host without the read (VR panel).
+    getBoundingClientRect(id: TreeNodeId): [number, number, number, number] | null
+    // The display size [width, height] in logical px (0×0 until the host's first onResize).
+    getDisplaySize(): [number, number]
+    // ---- debug: the tree of truth as JSON ------------------------------------------------------
+    // Every live root (the presented screen, the shown widgets, a pager's pages); per node the id,
+    // type, name, flags, laid-out box and the paint record (present / dirty / own + every field).
+    // Runtime-side text, identical on every host — the same JSON `lecodes test`'s `dump` writes.
+    debugDump(): string
+    // One node's paint record as JSON ("null" for a dead id).
+    debugPaint(id: TreeNodeId): string
+    // Canvas.update(): every image node showing this baked surface re-reads its pixels in place —
+    // a HOST-provided method (registerCallback) where the host can; the SDK re-assigns `src` otherwise.
+    refreshCanvasSurface?(surfaceId: i32): void
+
+    // ---- keyframe animation core (creator-tween; docs/timeline-plan.md) ------------------------
+    // One evaluator for UI style props, 3D node transforms / lights / cameras and 2D sprites: the
+    // SDK hands over a flat blob (sdk/src/animate/tween/spec.ts) and gets an id. `targets` are the
+    // track targets: a node id for the UI domain, an entity / scene id for the 3D and 2D domains.
+    // Created = paused at t = 0. Ops: 0 play, 1 pause, 2 resume, 3 cancel, 4 finish. Events come
+    // back through the `tween` event (kind 0 call, 1 finish, 2 a VALUE track's frame).
+    // Owned (owned.h): the animation is natively owned while it PLAYS; dropped otherwise → cancelled.
+    tweenCreate(data: Float32Array, strings: string[], targets: f64[]): Handle | null
+    tweenControl(id: u32, op: i32): void
+    tweenSeek(id: u32, ms: f32): void
+    tweenSetRate(id: u32, rate: f32): void
+    tweenGetTime(id: u32): f64
+    tweenGetElapsed(id: u32): f64
+    // The tween core's own callback (kind 0 = call, 1 = finish, 2 = a VALUE track's frame followed
+    // by its lanes as plain numbers) — separate from the emitter because of the variable arity.
+    registerTweenEvent(callback: (id: number, kind: number, index: number, ...lanes: number[]) => void): void
+
+    // ---- events -------------------------------------------------------------------------------
+    // ONE function per world receives everything the runtime says (TREE_EVENT_* of tree.ts /
+    // tree-events.h): `fn(id, kind, a, b, c, d)` with `id` the node (0 for world-level events: scene
+    // touches, resize, router changes, back). The return value matters for touchStart / longPress
+    // (the track claim mask: 0 = untracked, else TREE_TRACK_* bits) and back (true = handled).
+    // Delivered on the JS thread; `vlistSync` arrives synchronously (the SDK re-enters vlistMount
+    // from it).
+    setEmitter(fn: (id: TreeNodeId, kind: i32, a?: any, b?: any, c?: any, d?: any) => any): void
+  }
+}
+
+/** The UI RENDERER's side of the contract — the table runtime/native's presentation core calls
+ *  (`HostUI` of creator-pkg/host.gen.h; a host fills it BEFORE initJS(), `?` = optional slot). The
+ *  runtime owns the tree (engines/ui Yoga, the screens / destinations / widgets / pager / vlist
+ *  model); the host owns one view per node, keyed by the node id (the same pointer engines/ui's
+ *  style handlers deliver) and paints it. Nothing of JavaScript reaches the host:
+ *  listeners are a flag mask, events go back through the runtime's entry points with the node id.
+ *  One implementation per platform: renderers/tgfx (desktop, Quest), the Kotlin views (Android),
+ *  UIKit (Apple), the null renderer of lecodes-server.
+ *  @host ui HostUI */
+export interface HostUI {
+  /** Create the host view for a node of `type` ("column", "text", "image", "input", "screen", …).
+   *  Called at the node's creation, before any parent exists (`parent` is 0 then); `index` is the
+   *  position it will take under `parent` when both are known at once. */
+  nodeFactory(id: nodeid, type: string, parent: nodeid, index: i32): void
+  /** A content property as text ("text", "src", "value", "focus", "placeholder", "sourceRect",
+   *  "viewName", "viewParams", "name", …); null clears. Never "srcTintColor": a source's tint
+   *  arrives in the paint record's tintColor. */
+  setPropertyString(id: nodeid, prop: string, value: string | null): void
+  /** A small integer content property ("playerId", "viewId"). */
+  setPropertyInt(id: nodeid, prop: string, value: i32): void
+  /** The node's listener / trait mask (TREE_FLAG_* of tree-events.h): interactive (a touch target),
+   *  click, longPress, layout, scroll, overscroll, scrollRelease, refresh, change, focus, blur,
+   *  submit, overlayTap, detent, keepAlive, back. */
+  setFlags(id: nodeid, mask: u32): void
+  /** Mount `child` under `parent` at `index` (the runtime already laid it out). */
+  insertNode(parent: nodeid, child: nodeid, index: u16): void
+  removeNode(parent: nodeid, child: nodeid): void
+  /** The node is freed: drop the host's view and its map entry. */
+  releaseNode(id: nodeid): void
+  /** Make a destination the visible one (TREE_DEST_* = creator-pkg.h VIEW_DEST_*): screen — `node` =
+   *  the screen root (`id` 0); scene3d / scene2d — `id` = sceneId, the engine is already active, the
+   *  host mounts / reveals its scene view; native — `id` = viewId, `viewName` + `paramsJson` describe
+   *  the registerView factory call; video — `node` = the video node. `above`: the view goes over
+   *  what is shown, else under it (a scene / native view / video is always the bottom: a screen
+   *  next to one is above it). What WAS shown stays mounted until its `dropView`: the runtime moves
+   *  both through their own `transform` / `opacity` / `dim` meanwhile (a transition is tween tracks
+   *  on the roots — the host plays none of its own) and drops the one that left when it lands; with
+   *  no transition the drop follows at once. */
+  openView(kind: u8, node: nodeid, id: i32, viewName: string, paramsJson: string, above: boolean): void
+  /** The destination that left the screen is unmounted (the same (kind, node, id) its openView had). */
+  dropView(kind: u8, node: nodeid, id: i32): void
+  /** Nothing is the current destination (the one that was stays mounted until its `dropView`). */
+  closeView(): void
+  /** Did the host registerView(name)? */
+  isViewSupported?(name: string): boolean
+  /** The contract version the half registered as `name` was generated from; 1 for a half written
+   *  by hand, 0 when there is none. Backs `supports("<method>")` of a generated wrapper. */
+  viewVersion?(name: string): i32
+  /** NativeView channel: invoke `method` on the live instance `viewId`; `args` is the array of the
+   *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
+   *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
+  viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
+  /** Show a widget root: `ownerKind` = TREE_DEST_* (0xFF = a global overlay), `ownerId` = the sceneId /
+   *  viewId of a scene / native owner (0 for a screen), `ownerNode` = the owner screen's root (a
+   *  screen destination or a pager page) — 0 otherwise. */
+  widgetOpen(node: nodeid, ownerKind: u8, ownerId: i32, ownerNode: nodeid): void
+  widgetClose(node: nodeid): void
+  /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
+   *  one of the callbacks through the dispatch bridge. */
+  registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
+  showToast(message: string, duration: i32): void
+  /** Is the button node currently pressed (the UIButton.isPressed getter)? */
+  getButtonPressed(node: nodeid): boolean
+  /** The current text of an input node (malloc'd; the runtime frees it). */
+  getTextValue(node: nodeid): string
+  /** {left, top, width, height} of a laid-out node in LOGICAL px, every ancestor's scroll included,
+   *  read live; null when not mounted / laid out yet. Optional: the JS method answers null without
+   *  it. @out 4 */
+  getBoundingRect?(node: nodeid): Float32Array | null
+  /** A node's touchStart / longPress listener took the gesture (`ev.track`): keep feeding this
+   *  pointer's moves (`claim` = a PanDirection bitmask, `hasMove` = it wants onMove). */
+  touchHandler?(pointerId: i32, hasMove: boolean, claim: u8, node: nodeid): void
+  /** A long press was HANDLED: swallow the click that would follow the release. */
+  longPressHandler?(pointerId: i32, node: nodeid): void
+  /** Virtualized list: apply a scroll position (physical px). `animated` false = anchoring (idempotent,
+   *  after the content height update), true = a user scroll command. */
+  vlistScroll(node: nodeid, scrollY: f32, animated: boolean): void
+  /** UIPager: a change the runtime already made — "select" (the selected tab; `animated` = scroll
+   *  to it) or "content" (the pages changed wholesale: remount from the pager* pulls, every tab
+   *  showing its stack's top). A change of a tab's STACK is not a command: see pagerShowPage. */
+  pagerCommand?(node: nodeid, cmd: string, animated: boolean): void
+  /** UIPager: `page` is the top of the current tab's stack from now on, laid out at the pager's box
+   *  — show it in the tab's cell, above the page shown there or under it, and KEEP that one shown
+   *  (the twin of openView: the runtime moves both through their own `transform` / `opacity` /
+   *  `dim` and drops the one that left when the transition lands — at once when none plays). */
+  pagerShowPage?(node: nodeid, page: nodeid, above: boolean): void
+  /** UIPager: `page` left the top of its tab and its transition has landed — hide it. It may stay
+   *  a child (covered by a push, a keepAlive page); a page that is released goes through
+   *  removeNode right after. */
+  pagerDropPage?(node: nodeid, page: nodeid): void
+  /** A pager page root (`page`) was mounted under the pager or released (an attachTo widget names the
+   *  page node as its owner). */
+  pagerPageMounted?(page: nodeid, mounted: boolean): void
+  /** Optional: the host may PLAY a UI tween track itself — a platform animation interpolating on its
+   *  own clock (Core Animation on iOS) instead of one style write per runtime frame. `samples` holds
+   *  the track evaluated at even points of its length, easing included, `lanes` floats each: 1 for a
+   *  number prop, 4 (rgba 0..1) for a color, 9 for `transform` (the 3x3 in the paint record's layout).
+   *  The first sample shows after `delayMs`, the samples span `durationMs`, the last one holds;
+   *  `iterations` -1 = forever, `pingPong` = every other iteration backwards; `rate` = playback speed.
+   *  Return true to own the channel's presentation until `tweenRelease` — the runtime keeps its clock,
+   *  its events and the resting value, and writes nothing to the prop meanwhile. false = the runtime
+   *  writes per frame as usual (a prop the host has no layer property for, a fixed-clock run). */
+  tweenClaim?(node: nodeid, prop: string, lanes: i32, samples: Float32Array, durationMs: f32, delayMs: f32, iterations: i32, pingPong: boolean, rate: f32): boolean
+  /** The claimed channel is the runtime's again (`reason`: 0 the end was reached, 1 a control —
+   *  paused / seeked / re-played / cancelled, 2 dropped — a newer animation took the channel or the
+   *  node left the tree). The prop's model was just written with the value to show: apply the pending
+   *  paint of the node, then stop the host's playback — nothing may flash. */
+  tweenRelease?(node: nodeid, prop: string, reason: u8): void
+}

package/src/bridges/types.d.ts

@@ -0,0 +1,49 @@
+// The precise scalar types of the host contract (sdk/src/bridges/*.d.ts). Every alias is `number`
+// for the SDK and TypeScript; the name says what the NATIVE side reads out of the JS value, i.e. what
+// the generated bridge handlers (runtime/native/src/gen, runtime/web/src/gen) convert to. Derived
+// 2026-09-23 from runtime/native's hand-written handlers (u32()/f32()/JS_ToInt32/…), so a declaration
+// here is what QuickJS actually reads today — and what a JavaScriptCore backend must read tomorrow.
+
+/** Unsigned 32-bit: entity / node / texture / clip / body handles, counts, masks, packed RGBA colors. */
+export type u32 = number
+/** Signed 32-bit: indices that can be -1, durations, offsets, small enums. */
+export type i32 = number
+/** Unsigned 8-bit: small enums and flags read through u8(). */
+export type u8 = number
+/** Single precision: positions, angles, scales, weights — the engines' own float ABI. */
+export type f32 = number
+/** Double precision: read through JS_ToFloat64 (time stamps, intensities, a few legacy params). */
+export type f64 = number
+/** A host buffer id (a `systemId` from fetch / fetchLocal / a canvas bake): the native side turns it
+ *  into a malloc'd byte copy before the call, so the engine sees bytes, not the id. */
+export type bytes = number
+/** Unsigned 16-bit: a child index in the UI tree (host table slots). */
+export type u16 = number
+/** Signed 64-bit: a yoga node id, a retained JS value handed to the host as an opaque long. */
+export type i64 = number
+
+// The host-table (`export interface Host<Name>`) types the runtime hands a host and JS never sees —
+// scripts/lib/gen-host.ts maps them to C, Kotlin and Swift.
+/** An opaque HOST pointer (a renderer's node object, a GL context): `void*` in C, a Long in Kotlin,
+ *  a raw pointer in Swift. The runtime stores and passes it back; it never dereferences it. */
+export type ptr = number
+/** A UI node id — the runtime's node pointer (engines/ui): `const void*` in C, a Long in Kotlin, an
+ *  Int in Swift, a number in JS. The one identity of a node across the SDK, the runtime and the host. */
+export type nodeid = number
+/** A numeric HOST handle (a GL context): `void*` in C, a Long in Kotlin, a raw pointer in Swift —
+ *  `ptr` is a host OBJECT (a node), this is a number a host packs itself. */
+export type handle = number
+/** A retained JS value the runtime hands the host as an opaque handle (a node's JS element for the
+ *  jsCallListeners* entry points): `js_ptr` in C, a Long in Kotlin. Released by the runtime. */
+export type jsptr = number
+/** DATA on its way to a host — what a plugin channel carries (a call's arguments, its result, an
+ *  event's payload): null, a boolean, a number, a string, a Uint8Array, arrays and objects of them.
+ *  The runtime reads it ONCE into a LeValue (runtime/native/src/values/js.h says what cannot
+ *  cross) and the host gets its platform's own values: `const LeValue*` in C; in Kotlin and Swift the
+ *  objects the platform's JSON reader makes (org.json / Foundation), plus bytes as ByteArray / Data.
+ *  A TS host — JavaScript like the app — gets the value itself. */
+export type value = unknown
+/** An OUT parameter: the runtime passes a buffer the host FILLS (`float*` / `int32_t*`); how many
+ *  values, the slot's doc says. */
+export type f32out = Float32Array
+export type i32out = Int32Array