lecodes-sdk 1.2.0 → 2.0.0

package/prompts/ui-design.md

@@ -57,7 +57,7 @@ UIImage(src)  // src: string url | SvgSource | imported asset
 // UIButton — the only TAPPABLE container: a UIRow with children centered on both axes by default.
 // Anything clickable in the prototype (a card, a list row, an icon) — wrap it in a UIButton.
 UIButton(...children)
-// extra styles: onPressed: { bgColor, opacity, ... } — style while the finger is down (press feedback is
+// extra styles: $pressed: { bgColor, opacity, ... } — style while the finger is down (press feedback is
 //   OPT-IN; set it so the live prototype feels real)
 // Note: buttons render no chrome of their own — style bgColor/borderRadius/padding yourself, and give a
 //   button an explicit height (on its own it is only as tall as its text). flexDirection: "column" for cards.
@@ -109,8 +109,7 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 // Note: calc()/min()/max() do NOT support % ("calc(100% - 20px)" is invalid; use "calc(100vw - 20px)")
 
 // --- Colors in UI styles ---
-// hex "#f33"/"#f33c"/"#ff3333"/"#ff3333cc" (8 digits = alpha), packed int 0xff3333, "rgb(...)"/"rgba(...)",
-// and exactly these names: white black red green blue yellow orange purple gray cyan magenta brown transparent clear
+// any CSS color (hex, rgb()/hsl(), the CSS names — green = #008000, transparent/clear), 0xRRGGBB, [r,g,b(,a)], "var(--x)"
 
 // --- Safe areas ---
 // Env keywords resolving to the device insets (notch, home indicator):

package/prompts/ui.md

@@ -27,7 +27,7 @@ UIScreen(...children)
 //   popping back fires onOpen again. Anything started in onOpen (loops, intervals, sockets) MUST be stopped
 //   in onClose (see TIMERS & FRAME LOOP above).
 // .onTouchStart(cb) — fires for touches anywhere on the screen; use for full-screen gestures (see TOUCH GESTURES above)
-// .onBackPressed(cb) — Android hardware/gesture back; typically Router.pop()
+// .onBack(cb) — Android hardware/gesture back; typically Router.pop()
 // Screens NEVER scroll — the canonical screen is fixed chrome (header, tab bar) + ONE UIScrollable body
 //   with flexGrow: 1: UIScreen(Header(), UIScrollable(content).style({ flexGrow: 1 }))
 // Note: a screen always fills the device — sizing styles on it (width, height, flexGrow, flexShrink, position) are no-ops
@@ -63,7 +63,7 @@ Router.init(UIScreen(pager, tabBar))   // bar buttons: .onClick(() => pager.sele
 // UIWidget — floating overlay, independent of screens, always position: fixed in device coordinates
 // Persists across Router navigation — create ONCE at module scope, reuse; hidden by default.
 UIWidget(...children)
-// .show(), .hide(), .isShow (getter), .onTouchStart(cb), .onBackPressed(cb)
+// .show(), .hide(), .isShown (getter), .onTouchStart(cb), .onBack(cb)
 // extra style: overlayColor — full-screen scrim BEHIND the widget that blocks taps underneath, turning it into
 //   a modal; null (default) = no layer, "transparent" = invisible but still blocks. A scrim tap fires
 //   .onOverlayTap(cb) — usually () => widget.hide()
@@ -88,7 +88,7 @@ UIModal(...children)
 UIBottomSheet(...children)
 // .detents([0.3, 0.6, 1]) — snap positions, ascending fractions of screen height (the map-app model). Call
 //   BEFORE show(); sizes the sheet to the HIGHEST detent — lower detents show the top slice of the content.
-// .setDetent(i) (animated), .detent (getter), .onDetentChange(cb(i)) — every settle: finger snap or setDetent()
+// .setDetent(i) (animated), .detent (getter), .onDetent(cb(i)) — every settle: finger snap or setDetent()
 // .show()/.hide() slide in/out — plus the full UIModal surface (scrim, onOpen/onClose, dismissible).
 //   Dragging below the lowest detent closes it (fires onClose); .dismissible(false) collapses there instead —
 //   the persistent map sheet (pair it with overlayColor: null so the page behind stays interactive).
@@ -174,11 +174,12 @@ player.play()   // stop playback in the screen's onClose; .dispose() when gone f
 // UIButton — the only TAPPABLE container: a UIRow with children centered on both axes by default.
 // To make anything clickable (a card, a list row, an icon) — wrap it in a UIButton.
 UIButton(...children)
-// .onClick(cb), .onTouchStart(cb), .isPressed()   // gestures: see TOUCH GESTURES above
-// extra styles: onPressed: { bgColor, opacity, ..., duration? } — style while the finger is down;
+// .onClick(cb), .onTouchStart(cb), .isPressed (getter)   // gestures: see TOUCH GESTURES above
+// .onMouseEnter(ev => ev.track({ onMove?, onEnd?, onCancel? })), .isHovered (getter)   // mouse only; no leave event — onEnd is the leave
+// extra styles: $pressed: { bgColor, opacity, ..., duration? } — style while the finger is down (reserved class);
 //               rippleColor ("default" or a Color, Android only)
 // Note: press feedback is OPT-IN — nothing happens visually unless you set it. rippleColor replaces the
-//   onPressed visual on Android, so rippleColor + onPressed = ripple on Android, onPressed dim on iOS.
+//   $pressed visual on Android, so rippleColor + $pressed = ripple on Android, $pressed dim on iOS.
 // Note: buttons render no chrome of their own — style bgColor/borderRadius/padding yourself, and give a
 //   button an explicit height (on its own it is only as tall as its text). flexDirection: "column" for cards.
 
@@ -192,7 +193,7 @@ UIInput() / UITextArea()
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
-//   onFocused: { borderColor, ..., duration? } — style while focused (like onPressed)
+//   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
 // Note: type values are KEYBOARD HINTS, not validators — "number" doesn't block pasted letters. The
 //   phone-pad value is "phone" (there is NO "tel").
 // Note: "date"/"time" open the native PICKER in the keyboard slot (typing disabled). .value and onChange stay
@@ -240,7 +241,7 @@ UIText("Hi").style({ color: "white" }).style({ fontSize: 20 }).onClick(...)
 // Older code may pass a style object as the FIRST factory argument — legacy; write new styles with .style().
 
 // Mutable CONTENT properties are NOT styles — they live on the element:
-//   UIText: .text    UIInput/UITextArea: .value    UIImage: .src    UIButton: .isPressed()
+//   UIText: .text    UIInput/UITextArea: .value    UIImage: .src    UIButton: .isPressed (read-only)
 myText.text = "Updated"    // re-renders immediately
 
 // Style<T> is a global helper type for reusable style objects, no import needed:
@@ -278,20 +279,19 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 //       but do NOT support % ("calc(100% - 20px)" is invalid; use "calc(100vw - 20px)")
 
 // --- Colors in UI styles ---
-// hex "#f33"/"#f33c"/"#ff3333"/"#ff3333cc", packed int 0xff3333, "rgb(...)"/"rgba(...)", and exactly these names:
-// white black red green blue yellow orange purple gray cyan magenta brown transparent clear
-// (UI styles only — engine APIs are hex/packed-int only, see COLORS above)
+// any CSS color (hex, rgb()/hsl(), the CSS names — green = #008000, transparent/clear), 0xRRGGBB, [r,g,b(,a)],
+// or "var(--x)" — the same colors as every engine API (see COLORS above); a non-color throws
 
 // --- Safe areas & comfort ---
 // Env keywords resolving to the device insets (notch, home indicator):
 //   "safe-top" | "safe-bottom" | "safe-left" | "safe-right";  "safe-all" — p / m shorthands only
 // Comfort tokens — where content comfortably starts, never collapse to 0: max(safe-edge, knob) on clearance
-// insets (iOS notch/home indicator, gesture nav); past exact-height system BARS (Android status/nav bar) the
-// knob ADDS instead. Knob defaults: 12 top, 4 bottom, 16 horizontal (the page gutter):
+// insets (iOS notch/home indicator); past exact-height system BARS (Android status/nav bar) the
+// knob ADDS instead. Knob defaults: 12 top, 8 bottom, 16 horizontal (the page gutter):
 //   "comfort-top" | "comfort-bottom" | "comfort-left" | "comfort-right"
 //   "comfort-x" — px/mx | "comfort-y" — py/my | "comfort-all" — p / m
 // Accepted on per-side padding & margin, position offsets (top/left/bottom/right), and inside calc()/min()/max():
-.style({ pb: "comfort-bottom" })        // bottom bar: 34 over a home indicator, 52 above Android's button bar, 4 on inset-less devices
+.style({ pb: "comfort-bottom" })        // bottom bar: 34 over a home indicator, 56 above Android's button bar, 8 on inset-less devices
 .style({ px: "comfort-x" })             // page gutter that also clears the notch in landscape
 .style({ pb: "calc(comfort-bottom + 56px)" })   // scroll content clearing a 56px floating bar
 
@@ -306,14 +306,9 @@ label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
 // Bare comfort-* tokens apply the safe-area formula; "var(--comfort-top)" reads the raw knob.
 // "var(--name, fallback)" applies the fallback while the key is unset. Env names (safe-*, vw/vh) are not theme keys.
 
-// --- Responsive: onLandscape / onPortrait ---
-// Any style can nest orientation overrides, merged on top while the device is in that orientation:
-.style({ flexDirection: "column", p: 16, onLandscape: { flexDirection: "row", p: 32 } })
-// Keys: onLandscape, onPortrait.
-
-// --- Style classes ($name) — named states that CASCADE ---
-// A $-prefixed key in .style() declares a named style state (like onPressed, but yours: selected,
-// checked, expanded); duration/delay inside the block animate the swap. Drive it via el.class:
+// --- Style classes ($name) — the ONLY state mechanism; they CASCADE ---
+// A $-prefixed key in .style() declares a style state (yours: selected, checked, expanded);
+// duration/delay/easing inside the block animate the swap. Drive yours via el.class:
 const item = UIButton(UIText("Wi-Fi")).style({ bgColor: "#151515", $selected: { bgColor: "#1d2b45", duration: 150 } })
 item.onClick(ev => ev.target.class.selected = !ev.target.class.selected)
 // el.class.selected reads/writes a boolean; el.class({ a: true, b: false }) is the chainable batch
@@ -324,11 +319,13 @@ UIButton(
     UIImage(icon).style({ tintColor: "#888", $selected: { tintColor: "#5b8cff" } }),
     UIText("Label").style({ color: "#888", $selected: { color: "#5b8cff" } }),
 )   // .class.selected = true → icon AND label restyle (the cascade stops at hosted screens/widgets)
-// $pressed / $focused are RESERVED — the system toggles them (finger down / input focused) and they
-// CASCADE, so a button's children can restyle during its press. onPressed/onFocused stay
-// own-element-only — use those on nested interactives (a button inside a clickable card):
-UIButton(UIText("Buy").style({ $pressed: { color: "#999" } })).style({ $pressed: { transform: "scale(0.97)" } })
-// Precedence on the same prop: base < $classes < $pressed/$focused < onPressed/onFocused.
+// RESERVED — the system toggles them, el.class.pressed = … throws:
+//   $hovered / $pressed / $focused (mouse over / finger down / input focused) cascade to children but STOP at
+//   a nested UIButton — a button inside a pressed card is not pressed;
+//   $landscape / $portrait — GLOBAL, from the display size (the swap on rotation is instant).
+UIButton(UIText("Buy").style({ $pressed: { color: "#999" } })).style({ $hovered: { opacity: 0.9 }, $pressed: { transform: "scale(0.97)" } })
+screen.style({ flexDirection: "column", p: 16, $landscape: { flexDirection: "row", p: 32 } })
+// Precedence on the same prop: base < $landscape/$portrait < $classes < $hovered < $pressed < $focused.
 
 // --- Defaults that surprise ---
 // flexShrink: 0 — elements don't shrink to fit (exception: UIScrollable, UIVirtualizedList and UIPager
@@ -411,14 +408,25 @@ UIButton().onLayout(({ width }) => { buttonWidth = width })
 // ===== ROUTER (multi-page apps) =====
 // Tabs are UITabs' job, in-tab stacks UIPager's (see UI COMPONENTS) — the Router owns what sits ABOVE the shell.
 Router.init(homeScreen, opts?: { showDefaultBackButton?: boolean })  // call once in the entry file (default false)
-Router.push(screen)      // push onto the stack, screen becomes active
-Router.pop(to?: number)  // default -1 = one back; negative = relative (-2 = back two), 0/positive = absolute
+Router.push(screen, opts?: { transition, popTransition })  // push onto the stack, screen becomes active (default "push")
+Router.pop(to?: number, opts?: { transition })
+                         // default -1 = one back; negative = relative (-2 = back two), 0/positive = absolute
                          // stack index (0 = home). Popped screens' native trees are destroyed; the UIScreen
-                         // object stays reusable (push remounts it).
-Router.replace(screen, opts?: { transition })  // swap the top screen; transition: "slide-from-left" |
-    // "slide-from-right" | "slide-from-top" | "slide-from-bottom" | "zoom" | "zoom-out" | "zoom-in" | "fade" | "none" (default "fade")
+                         // object stays reusable (push remounts it). Plays the way back the screen remembers.
+Router.replace(screen, opts?: { transition, popTransition })  // swap the top screen (default "none"; theme({ replaceTransition }))
 Router.current                   // the active UIScreen (getter)
-Router.hide() / Router.restore() // hide/restore the whole router — stack stays alive; fires the top screen's onClose/onOpen
+Router.hide(opts?) / Router.restore(opts?) // hide/restore the whole router — stack stays alive; fires the top screen's onClose/onOpen
+// TRANSITIONS — every call above, and open() / close() of any destination, takes { transition }:
+//   a name: "push" | "pop" | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom" |
+//           "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
+//   or your own: { enter?: pose, exit?: pose, onTop?: "enter" | "exit" } — the incoming screen comes FROM `enter`,
+//     the outgoing one goes TO `exit`. pose = { transform?, opacity?, dim?, duration? (ms, 300), delay?, easing? };
+//     arrays are keyframes; in a pose a % in translate is a percent of the screen ("translateY(100%)").
+//     e.g. Router.push(page, { transition: { enter: { transform: "translateY(100%)", duration: 400 }, exit: { dim: 0.3 } } })
+// popTransition = the way BACK the screen remembers (Router.pop(), the back gesture, the system's back play it).
+//   Default: the transition it came with, the other way round (a slide from the bottom leaves downwards;
+//   a zoom / a fade go back with a fade). A replace without one keeps the way back of the screen it replaces.
+// A screen's own transform / opacity are not seen while a transition moves it — style a child instead.
 Router.addEventListener("change", (screen: UIScreen) => ...) / .removeEventListener("change", cb)  // after every navigation
 // Screens BELOW the top stay mounted — element trees and state survive, they're just not rendered.
 // push fires the outgoing screen's onClose + the incoming one's onOpen; pop fires them in reverse and
@@ -622,7 +630,7 @@ const detailScreen = (name: string) => UIScreen(
 ).style({ p: 16, pt: "comfort-top", gap: 16, bgColor: "black" })
 
 const Item = (name: string) => UIButton(UIText(name).style({ color: "white" }))
-    .style({ height: 52, px: 16, justifyContent: "flex-start", borderRadius: 12, bgColor: "#151515", onPressed: { opacity: 0.7 } })
+    .style({ height: 52, px: 16, justifyContent: "flex-start", borderRadius: 12, bgColor: "#151515", $pressed: { opacity: 0.7 } })
     .onClick(() => UIPager.push(detailScreen(name)))          // in-tab push: tab bar stays, back-swipe pops
 
 export const homeScreen = UIScreen(
@@ -658,7 +666,7 @@ Router.init(tabs)
 const Field = (label: string, style: Style<UIInput> = {}) => {
     const input = UIInput().style({ height: 50, px: 14, borderRadius: 12, bgColor: "#161A22",
         border: "1px solid #262C3A", color: "white", placeholderColor: "#5A6272",
-        onFocused: { borderColor: "#4C8DFF" }, ...style })
+        $focused: { borderColor: "#4C8DFF" }, ...style })
     const message = UIText("").style({ fontSize: 13, minHeight: 18, color: "#FF6B6B" })
     input.onChange(() => message.text = "")
     return {
@@ -709,7 +717,7 @@ const screen = UIScreen(
         UIText("Create account").style({ fontSize: 28, fontWeight: 700, mb: 12 }),
         name.node, email.node, password.node,
         UIButton(btnLabel = UIText("Create account").style({ fontSize: 16, fontWeight: 700 }))
-            .style({ name: "submit", height: 52, borderRadius: 14, bgColor: "#4C8DFF", mt: 8, onPressed: { opacity: 0.85 } })
+            .style({ name: "submit", height: 52, borderRadius: 14, bgColor: "#4C8DFF", mt: 8, $pressed: { opacity: 0.85 } })
             .onClick(() => submit())
     ).style({ flexGrow: 1, px: 20, pt: "comfort-top", pb: 28, gap: 8 })
 ).style({ bgColor: "#0C0F14" })
@@ -739,7 +747,7 @@ const sheet = UIBottomSheet(
 .style({ bgColor: "white", borderRadius: 20, overlayColor: null })  // no scrim — the map stays interactive
 .detents([0.25, 0.6, 1])            // collapsed / half / full
 .dismissible(false)                 // drag below the lowest detent collapses, never closes
-.onDetentChange(i => console.log("detent", i))
+.onDetent(i => console.log("detent", i))
 
 const mapScreen = UIScreen(
     // the map / page content behind the sheet

package/src/animate/tween/Animation.ts

@@ -1,11 +1,12 @@
 // The animation HANDLE (docs/timeline-plan.md §2.2): what `animateTo` / `animateFrom` / `Timeline`
 // return. Owns one spec; every `play()` builds the blob (target ids resolve at play time), hands it
-// to the host (`_creatorUI.tweenCreate`) and gets events back (`registerTweenEvent`: time-callbacks
+// to the host (`_creatorTree.tweenCreate`) and gets events back (`registerTweenEvent`: time-callbacks
 // and finish). On a host without the tween core the UI tracks fall back to the old
 // `animateTo` / `animateFrom` bridge pair (single-value tweens only) and the clock is a timer —
 // see `fallback` below.
 
 import { CLOCK_GAME, CLOCK_UI, DOM_UI, DOM_VALUE, buildBlob, evaluateTrack, type Track, type TweenSpec } from "./spec"
+import { DEAD_HANDLE, Pins } from "../../core/pins"
 
 const OP_PLAY = 0
 const OP_PAUSE = 1
@@ -43,17 +44,17 @@ export interface Animation {
   onFinish(fn: (done: boolean) => void): this
 }
 
-const hasCore = (): boolean => typeof _creatorUI !== "undefined" && typeof (_creatorUI as any).tweenCreate === "function"
 
 // ---- host events -------------------------------------------------------------------------------
 
-const live = new Map<number, TweenAnimation>()
+/** The animations native owns right now (playing), by id — what the host's events resolve to. */
+const tweens = new Pins<TweenAnimation>()
 let eventsRegistered = false
 const ensureEvents = (): void => {
   if (eventsRegistered) return
   eventsRegistered = true
-  ;(_creatorUI as any).registerTweenEvent?.(function (this: unknown, id: number, kind: number, index: number) {
-    const a = live.get(id)
+  _creatorTree.registerTweenEvent(function (this: unknown, id: number, kind: number, index: number) {
+    const a = tweens.get(id)
     if (!a) return
     if (kind === EV_CALL) a._fireCall(index)
     else if (kind === EV_FINISH) a._hostFinished()
@@ -81,7 +82,8 @@ export class TweenAnimation implements Animation {
   /** @internal VALUE-track deliverers by slot (`animate()` / `Timeline.animate`). */
   _values = new Map<number, (lanes: Float32Array) => void>()
 
-  private _id = 0                 // host id, 0 = not created
+  /** @internal The host animation's owned handle (DEAD_HANDLE while there is none). */
+  _h: Handle = DEAD_HANDLE
   private _started = false        // play() ran at least once (the first play keeps the constructor's promise)
   private _endTime = 0            // `time` after the host freed a finished animation
   private _playing = false
@@ -90,7 +92,6 @@ export class TweenAnimation implements Animation {
   private _resolve!: (done: boolean) => void
   private _settled = true
   private _listeners: Array<(done: boolean) => void> = []
-  private _fb?: Fallback
 
   constructor(spec: TweenSpec) {
     this._spec = spec
@@ -118,13 +119,12 @@ export class TweenAnimation implements Animation {
   get rate(): number { return this._rate }
   set rate(r: number) {
     this._rate = r
-    if (this._id) (_creatorUI as any).tweenSetRate(this._id, r)
-    this._fb?.setRate(r)
+    if (this._h.id) _creatorTree.tweenSetRate(this._h.id, r)
   }
 
   get time(): number {
-    if (this._id) return (_creatorUI as any).tweenGetTime?.(this._id) ?? 0
-    return this._fb?.time ?? this._endTime
+    if (this._h.id) return _creatorTree.tweenGetTime(this._h.id)
+    return this._endTime
   }
   set time(ms: number) { this.seek(ms) }
 
@@ -143,36 +143,29 @@ export class TweenAnimation implements Animation {
     return s.durationMs * n * (s.pingPong && s.iterations !== 1 ? 2 : 1)
   }
   private _elapsedMs(): number {
-    if (this._id) return (_creatorUI as any).tweenGetElapsed?.(this._id) ?? this.time
-    return this._fb?.elapsed ?? (this._endTime > 0 ? this._totalMs() : 0)
+    if (this._h.id) return _creatorTree.tweenGetElapsed(this._h.id)
+    return this._endTime > 0 ? this._totalMs() : 0
   }
   private _seekTotal(ms: number): void {
-    if (hasCore()) {
-      this._ensure()
-      ;(_creatorUI as any).tweenSeek(this._id, ms)
-    } else {
-      this._ensureFallback().seek(ms)
-    }
+    this._ensure()
+    _creatorTree.tweenSeek(this._h.id, ms)
   }
 
   /** Create the host animation (paused at t = 0) if it doesn't exist. */
   private _ensure(): void {
-    if (this._id) return
+    if (this._h.id) return
     ensureEvents()
     const blob = buildBlob(this._spec)
-    this._id = (_creatorUI as any).tweenCreate(blob.data, blob.strings, blob.targets)
-    if (this._id) live.set(this._id, this)
-    if (this._rate !== 1) (_creatorUI as any).tweenSetRate(this._id, this._rate)
+    this._h = _creatorTree.tweenCreate(blob.data, blob.strings, blob.targets as number[]) ?? DEAD_HANDLE
+    if (this._h.id && this._rate !== 1) _creatorTree.tweenSetRate(this._h.id, this._rate)
   }
 
   private _destroy(): void {
-    if (this._id) {
-      live.delete(this._id)
-      ;(_creatorUI as any).tweenControl(this._id, OP_CANCEL)
-      this._id = 0
+    if (this._h.id) {
+      tweens.unpin(this._h.id)
+      _creatorTree.tweenControl(this._h.id, OP_CANCEL)   // the runtime frees it; drop the handle too
+      this._h = DEAD_HANDLE
     }
-    this._fb?.cancel()
-    this._fb = undefined
   }
 
   play(): this {
@@ -195,27 +188,26 @@ export class TweenAnimation implements Animation {
       if (last && last.value !== undefined) t.channel.commit(last.raw)
     }
     this._playing = true
-    if (hasCore()) {
-      this._ensure()
-      ;(_creatorUI as any).tweenControl(this._id, OP_PLAY)
-    } else {
-      this._ensureFallback().play()
-    }
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_PLAY)
+    tweens.pin(this)   // playing: native owns it, its events must find it
     return this
   }
 
   pause(): this {
-    if (hasCore()) { this._ensure(); (_creatorUI as any).tweenControl(this._id, OP_PAUSE) }
-    else this._ensureFallback().pause()
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_PAUSE)
     this._playing = false
+    tweens.unpin(this._h.id)   // paused: only the app's reference keeps it
     return this
   }
 
   resume(): this {
     if (this._settled) return this.play()
-    if (hasCore()) { this._ensure(); (_creatorUI as any).tweenControl(this._id, OP_RESUME) }
-    else this._ensureFallback().resume()
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_RESUME)
     this._playing = true
+    tweens.pin(this)
     return this
   }
 
@@ -229,12 +221,8 @@ export class TweenAnimation implements Animation {
   }
 
   finish(): this {
-    if (hasCore()) {
-      this._ensure()
-      ;(_creatorUI as any).tweenControl(this._id, OP_FINISH)   // the host answers with EV_FINISH
-    } else {
-      this._ensureFallback().finish()
-    }
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_FINISH)   // the host answers with EV_FINISH
     return this
   }
 
@@ -256,115 +244,11 @@ export class TweenAnimation implements Animation {
 
   /** @internal The host reached the end (naturally or via finish()) and has freed the animation. */
   _hostFinished(): void {
-    if (this._id) { live.delete(this._id); this._id = 0 }
-    // the old-host path's timers / value loop must stop with the run, or an interval outlives it
-    if (this._fb) { this._fb.cancel(); this._fb = undefined }
+    if (this._h.id) { tweens.unpin(this._h.id); this._h = DEAD_HANDLE }   // the runtime freed it
     this._endTime = this._spec.durationMs
     this._settle(true)
   }
 
-  // ---- old hosts ------------------------------------------------------------------------------
-
-  private _ensureFallback(): Fallback {
-    if (!this._fb) this._fb = new Fallback(this)
-    return this._fb
-  }
-}
-
-/** Old-host path: UI tracks go through the legacy `animateTo` / `animateFrom` pair (one value per
- *  prop — the last explicit key for a to-tween, the first for a from-tween; no easing, no seek), a
- *  track on any other domain is dropped with one warning, and the clock is a timer that fires the
- *  calls and the finish. Good enough for the simple cases on web / Apple until their core lands. */
-class Fallback {
-  time = 0
-  elapsed = 0
-  private _timers: ReturnType<typeof setTimeout>[] = []
-  private _startedAt = 0
-  private _rate = 1
-  private _warned = false
-  private _loop?: ReturnType<typeof setInterval>
-  private _valueTracks: Track[] = []
-  private _scratch = new Float32Array(16)
-  private _lanes: number[] = []
-
-  private a: TweenAnimation
-  constructor(a: TweenAnimation) { this.a = a }
-
-  setRate(r: number): void { this._rate = r }
-
-  play(): void {
-    const s = this.a._spec
-    this.cancel()
-    this._startedAt = Date.now()
-    const byTarget = new Map<Track["target"], { to: Record<string, unknown>, from: Record<string, unknown>, at: number, dur: number, commit: boolean }>()
-    this._valueTracks = []
-    for (const t of s.tracks) {
-      if (t.channel.domain === DOM_VALUE) { this._valueTracks.push(t); continue }
-      if (t.channel.domain !== DOM_UI) {
-        if (!this._warned) { this._warned = true; console.warn("[tween] this host animates UI elements and values only (no tween core) — 3D / 2D tracks skipped") }
-        continue
-      }
-      const rec = byTarget.get(t.target) ?? { to: {}, from: {}, at: t.atMs, dur: t.durMs, commit: t.commit }
-      byTarget.set(t.target, rec)
-      const first = t.keys[0]!, last = t.keys[t.keys.length - 1]!
-      if (last.value === undefined) rec.from[t.prop] = first.raw          // animateFrom shape
-      else rec.to[t.prop] = last.raw
-      rec.at = Math.min(rec.at, t.atMs)
-      rec.dur = Math.max(rec.dur, t.durMs)
-    }
-    for (const [target, rec] of byTarget) {
-      // Sent even for an unmounted element (id 0), exactly as the direct call used to be — the host
-      // ignores it; a stub host in tests records it.
-      const id = ((target as any)._id as number) ?? 0
-      const delay = rec.at + s.delayMs
-      const meta: Record<string, unknown> = { duration: rec.dur }
-      if (delay > 0) meta.delay = delay
-      if (s.iterations !== 1) { meta.loop = s.iterations < 0 ? true : s.iterations; meta.loopMode = s.pingPong ? "ping-pong" : "restart" }
-      // The host merges its animate layer into base on commit (the SDK committed its own style already)
-      if (Object.keys(rec.to).length) _creatorUI.animateTo?.(id, { ...rec.to, ...meta, ...(rec.commit ? {} : { commit: false }) })
-      if (Object.keys(rec.from).length) _creatorUI.animateFrom?.(id, { ...rec.from, ...meta })
-    }
-    const scale = this._rate > 0 ? 1 / this._rate : 0
-    if (scale === 0) return
-    for (let i = 0; i < s.calls.length; i++) {
-      this._timers.push(setTimeout(() => this.a._fireCall(i), (s.delayMs + s.calls[i]!) * scale))
-    }
-    if (s.iterations === 1) {
-      this._timers.push(setTimeout(() => { this._applyValues(s.durationMs); this.elapsed = this.time = s.durationMs; this.a._hostFinished() }, (s.delayMs + s.durationMs) * scale))
-    }
-    // VALUE tracks are evaluated here in JS (the C evaluator's twin), ~60 times a second
-    if (this._valueTracks.length) {
-      this._applyValues(0)
-      this._loop = setInterval(() => {
-        const total = (Date.now() - this._startedAt) * this._rate - s.delayMs
-        if (total < 0) return
-        const period = s.durationMs * (s.pingPong && s.iterations !== 1 ? 2 : 1)
-        let local = period > 0 ? total % period : 0
-        if (s.iterations !== 1 && s.pingPong && local > s.durationMs) local = 2 * s.durationMs - local
-        if (s.iterations === 1) local = Math.min(total, s.durationMs)
-        this.elapsed = total
-        this.time = local
-        this._applyValues(local)
-      }, 16)
-    }
-  }
-  private _applyValues(local: number): void {
-    for (const t of this._valueTracks) {
-      evaluateTrack(t, local, this._lanes)
-      for (let i = 0; i < t.lanes; i++) this._scratch[i] = this._lanes[i]!
-      this.a._fireValue(t.channel.id() as number, this._scratch)
-    }
-  }
-  pause(): void { this.cancel() }
-  resume(): void { /* no partial resume on the timer clock: the tween already ran on the host */ }
-  seek(ms: number): void { this.elapsed = ms; this.time = ms % Math.max(1, this.a._spec.durationMs); this._applyValues(this.time) }
-  finish(): void { this.cancel(); this._applyValues(this.a._spec.durationMs); this.a._hostFinished() }
-  cancel(): void {
-    for (const t of this._timers) clearTimeout(t)
-    this._timers = []
-    if (this._loop !== undefined) { clearInterval(this._loop); this._loop = undefined }
-    if (this._startedAt) this.elapsed = this.time = Math.min(this.a._spec.durationMs, (Date.now() - this._startedAt) * this._rate)
-  }
 }
 
 /** @internal Build a one-bag animation for a single target (the `animateTo` / `animateFrom` path). */