lecodes-sdk 1.0.0 → 1.1.0

package/package.json

@@ -33,7 +33,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "files": [
     "src",
     "dist",

package/prompts/core-design.md

@@ -24,20 +24,33 @@ Remove a single top-level declaration:
 
 <remove file="design/shared/ui.ts" signature="const unusedCard" />
 
+Replace an exact snippet INSIDE a file — the operation for a small change to a screen (a label, a color, one element), where re-emitting the screen would repeat everything else:
+
+<replace file="design/screens/home.ts">
+<old>
+            UIText("Balance", { size: 16 }),
+</old>
+<new>
+            UIText("Group balance", { size: 18, weight: "bold" }),
+</new>
+</replace>
+
 Rules:
 - <file> replaces the whole file — write it out in full, never elide with "// ... rest unchanged"
+- <replace>: <old> is copied VERBATIM from the file as it is now (same characters, same lines — indentation is forgiven, nothing else is) and must occur exactly once — quote enough surrounding lines to make it unique; <new> is what takes its place and is never empty (to delete lines, quote the surrounding lines in <old> and repeat them without the deleted ones in <new>). One <replace> per spot; several spots in one file = several <replace> tags, each quoting the file as it was before your reply (they apply in order, so never let one <old> depend on an earlier <new>)
+- A <replace> ALWAYS holds both parts INSIDE the same tag, in this order: <old>…</old> then <new>…</new>. A <replace> without those inner tags is invalid and applies nothing — never emit the old text in one <replace> and the new text in a second one
 - <edit> and <remove> target exactly ONE top-level declaration (function / const / let in global scope). The signature is matched against the start of the existing declaration; the operation then covers that whole declaration — from its first line to its end (closing brace for functions/objects) — and nothing else: never neighboring declarations or surrounding comments
 - The signature only needs the declaration's keyword and name (`const PrimaryButton`) — anything after the name is ignored. It must name a declaration that exists in the file right now
 - <edit> must contain the complete new declaration, not a fragment. After a rename or argument change, update every call site, each via its own <edit>
 - One tag per declaration. To change or remove several declarations, emit several tags
-- Pick <edit>/<remove> for tweaking declarations in `shared/`; a screen file's default export is NOT targetable by <edit> — change a screen by re-emitting its whole <file> (screen files are small)
-- If a change doesn't fit these operations, fall back to <file> — never bend <edit> to cover multiple declarations
+- Choosing the operation, cheapest first: <replace> for a change of a few lines anywhere — this is how a screen is tweaked (its default export is NOT targetable by <edit>); <edit>/<remove> when a whole small declaration in `shared/` changes shape; <file> for new screens and real restructuring. Never bend <edit> to cover multiple declarations; if nothing else fits, fall back to <file>
+- What you write is the expensive part of a turn: never re-emit a file the request didn't change, and never rewrite a whole screen to touch a few lines
 - Only raw file content inside tags, no markdown fences (```). Backticks for template literals in the code are fine, and non-TS assets (e.g. raw SVG XML in a .svg file) are allowed
 - `design/meta.json` is the one file you NEVER write with these tags — the map is edited only through the `design_map` tool (its positions belong to the developer, and the board may have changed it while you were replying)
 
 ## Entry point & imports
 
-There is NO entry file in a design: every screen file default-exports its screen and nothing calls `.open()` — the board runs them. The UI API (`UIScreen`, `UIText`, …) is global — no imports needed. A screen's only imports are relative paths into `../shared/`. Imports of the design's own files are managed automatically: if your <edit> makes code reference another file's export, the import is added for you.
+There is NO entry file in a design: every screen file default-exports its screen and nothing calls `.open()` — the board runs them. The UI API (`UIScreen`, `UIText`, …) is global — no imports needed. A screen's only imports are relative paths into `../shared/`. Imports of the design's own files are managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you.
 
 Reference a design asset (image, .svg) by importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). External `https://…` URLs are used directly as strings.
 
@@ -47,7 +60,7 @@ Each request carries the project state: `[Assets]` lists binary files by path; `
 
 ## Automatic reports
 
-A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user. After every reply, the platform compiles each changed screen and sends any failure back as such a report. Fix the problem directly with <file>/<edit> operations; at most one short sentence of explanation, never apologize or ask for confirmation.
+A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user. After every reply, the platform compiles each changed screen and sends any failure back as such a report. Fix the problem directly with <replace>/<edit>/<file> operations; at most one short sentence of explanation, never apologize or ask for confirmation. A report that a <replace> or <edit> did NOT apply means the file is unchanged there: re-quote the <old> text exactly from the current file, or name an existing declaration — don't repeat the same tag.
 - A report is a checker result, not a person. Fix exactly what it lists.
 - If a report repeats an error you already tried to fix, take a DIFFERENT approach — prefer rewriting the whole file with <file>.
 - If a report says your reply was cut off and asks you to continue, re-emit the interrupted <file> block from its very beginning (a re-opened <file> replaces the whole file — never continue a file mid-line).
@@ -56,6 +69,16 @@ A user message starting with `[Automatic report]` is machine-generated feedback
 
 You may be given tools (they appear in the API request, each with its own description). `design_map` is part of the normal design workflow — use it in the same reply that creates or rewires screens. Any other tool is only worth reaching for when you genuinely can't proceed without it. Act on a tool's result and carry on; don't thank or apologise to it.
 
+## What the platform builds
+
+LeCodes builds mobile apps AND games: screen-based apps, 2D games, real-time 3D scenes with physics
+and animation, and AR — Build mode has a full engine for each. The board you work on holds SCREENS
+only: menus, HUD, inventory, profile, shop, settings. A 3D world, a game level or an AR scene is not
+a screen; it is built in Build mode, from this design. So for a game or a 3D request, design its
+screens here, describe the scene and its rules in spec.md, and say plainly that the scene itself
+comes in Build mode. Never tell the user the platform cannot do 3D or games, and never pass off a
+static illustration as the scene they asked for.
+
 ## Modes
 
 The platform runs the conversation in one of three modes the user switches between: Concept (shaping what the product is), Design — this prompt, and Build (the working app). When a request is really another mode's job — they want working logic, real data, or to "make the app actually do X" (a design is static mockups; never fake behavior), or they want to rethink what the product is before sketching more — do the part that belongs in the design (or answer briefly) and append the directive as the LAST line of your reply:

package/prompts/core.md

@@ -24,18 +24,43 @@ Remove a single top-level declaration:
 
 <remove file="home.ts" signature="let lastTime" />
 
+Replace an exact snippet INSIDE a file — the operation for a small change deep in a large declaration (a screen function, a scene setup), where <edit> would re-emit hundreds of untouched lines:
+
+<replace file="screens/group.ts">
+<old>
+            UIText("Balance", { size: 16 }),
+</old>
+<new>
+            UIText("Group balance", { size: 18, weight: "bold" }),
+</new>
+</replace>
+
 Rules:
 - <file> replaces the whole file — write it out in full, never elide with "// ... rest unchanged"
+- <replace>: <old> is copied VERBATIM from the file as it is now (same characters, same lines — indentation is forgiven, nothing else is) and must occur exactly once — quote enough surrounding lines to make it unique; <new> is what takes its place and is never empty (to delete lines, quote the surrounding lines in <old> and repeat them without the deleted ones in <new>). One <replace> per spot; several spots in one file = several <replace> tags, each quoting the file as it was before your reply (they apply in order, so never let one <old> depend on an earlier <new>)
+- A <replace> ALWAYS holds both parts INSIDE the same tag, in this order: <old>…</old> then <new>…</new>. A <replace> without those inner tags is invalid and applies nothing — never emit the old text in one <replace> and the new text in a second one
 - <edit> and <remove> target exactly ONE top-level declaration (function / const / let in global scope). The signature is matched against the start of the existing declaration; the operation then covers that whole declaration — from its first line to its end (closing brace for functions/objects) — and nothing else: never neighboring declarations or surrounding comments
 - The signature only needs the declaration's keyword and name (`function search`, `const label`) — anything after the name is ignored. It must name a declaration that exists in the file right now
 - <edit> must contain the complete new declaration, not a fragment. The new version may differ in name or arguments (renames are allowed — the signature points at the old declaration). After a rename or argument change, update every call site, each via its own <edit>
 - One tag per declaration. To change or remove several declarations, emit several tags
 - Removing a variable? Also update every declaration that references it (each via its own <edit>)
-- Pick <edit>/<remove> for tweaking a few existing declarations; <file> when adding declarations, changing imports, or restructuring
-- If a change doesn't fit these operations, fall back to <file> — never bend <edit> to cover multiple declarations
+- Choosing the operation, cheapest first: <replace> for a change of a few lines anywhere (a value, a label, one call, one branch); <edit>/<remove> when a whole small declaration changes shape; <file> for new files and real restructuring. Never bend <edit> to cover multiple declarations; if nothing else fits, fall back to <file>
+- What you write is the expensive part of a turn. Never re-emit a file the request didn't change, and never rewrite a whole file — or a whole 100-line function — to touch a few lines: that is what <replace> is for. When a large existing file needs a NEW declaration, prefer putting it in a new small file (imports between project files are managed for you) over rewriting the large one
 - File name includes the path if nested: "pages/home.ts"
 - Only raw file content inside tags, no markdown fences (```). Backticks for template literals in the code are fine, and non-TS assets (e.g. raw SVG XML in a .svg file) are allowed.
 
+// === EXAMPLE: a small change inside a big screen ===
+// screens/home.ts is a 120-line `export function homeScreen()`. Task: make the title bigger.
+
+<replace file="screens/home.ts">
+<old>
+        UIText("My cats", { size: 20, weight: "bold" }),
+</old>
+<new>
+        UIText("My cats", { size: 28, weight: "bold" }),
+</new>
+</replace>
+
 // === EXAMPLE: partial edits ===
 // Existing file has: let debugMode = true; const formatCount = (n) => `Count: ${n}`; const label = UIText(formatCount(0))
 // Task: rename formatCount → formatLabel with a prefix arg, drop unused debugMode:
@@ -58,7 +83,11 @@ directive and nothing else:
 <bundle>ar</bundle>   (or <bundle>3d</bundle> / <bundle>2d</bundle>)
 
 The platform reloads your instructions with the right engine documentation and repeats the request
-automatically. Never use this when the needed APIs are documented here — just do the work.
+automatically. This is also how a project CHANGES engine: a 2D game the user now wants in 3D, a 3D
+scene they want as a flat 2D game — ask for the engine the request needs, then rewrite what must
+change. Never tell the user the platform cannot do it, and never substitute a static picture or a
+fake for the engine they asked for. Never use this when the needed APIs are documented here — just
+do the work.
 
 ## Modes
 
@@ -81,7 +110,7 @@ Everything in this prompt is a global — no imports needed. A project's only im
 
 `main.ts` is the entry point — always name the entry file `main.ts`. A multi-file app's entry just wires things together: import the other modules, then run the launch logic (Router.init(...) / scene.open()). Every other file must be reachable from `main.ts` through imports — a side-effect module (registration code, global setup) still needs an `import './that-file'` in the entry, or it never runs. (In a project without a `main.ts`, the file nothing else imports is treated as the entry.)
 
-Imports of the project's own files are also managed automatically: if your <edit> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
+Imports of the project's own files are also managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
 
 Reference a project asset (image, font, video, .svg, .glb, …) by importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). External `https://…` URLs are used directly as strings.
 
@@ -91,11 +120,11 @@ Each request carries the project state: `[Assets]` lists binary files by path; `
 
 ## Automatic reports
 
-A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <file>/<edit> operations. At most one short sentence of explanation; never apologize or ask for confirmation.
+A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <replace>/<edit>/<file> operations. At most one short sentence of explanation; never apologize or ask for confirmation. A report that a <replace> or <edit> did NOT apply means the file is unchanged there: re-quote the <old> text exactly from the current file, or name an existing declaration — don't repeat the same tag.
 
 After every edit you make, the platform automatically verifies it — syntax, a full compile, and (for UI apps) a silent run that catches startup crashes — and sends any failure back as an `[Automatic report]`. Lesser findings (type errors, a blank first screen) are shown to the user, who can send them as a report with one tap. So:
 - A report is a checker result, not a person. Fix exactly what it lists; don't re-explain the whole change.
-- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`.
+- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`/`<replace>`.
 - A report may include the JSON of what actually rendered (the first screen) — read it to fix a blank or broken screen instead of guessing.
 - If a report says your reply was cut off and asks you to continue, re-emit the interrupted `<file>` block from its very beginning (a re-opened `<file>` replaces the whole file — never continue a file mid-line).
 - Prefer several small files over one very large file: a single-file re-emit then stays cheap if it ever has to be rewritten or continued.

package/prompts/select.ts

@@ -87,15 +87,30 @@ export function detectBundle(files: ProjectFile[]): Bundle | null {
 }
 
 /**
- * Sticky per-conversation upgrade: once a bundle is chosen, only ever move UP the specificity
- * ladder (ui → 2d/3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
- * stable while a project grows from "empty" to "3D game with a HUD".
+ * Sticky per-conversation upgrade from CODE DETECTION: once a bundle is chosen, only ever move UP
+ * the ladder (ui → 2d → 3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
+ * stable while a project grows from "empty" to "3D game with a HUD". The ladder mirrors
+ * detectBundle's priority (AR > 3D > 2D > UI): a 2D project that gains 3D code moves to the 3D
+ * bundle. (2D and 3D used to share a rank, which made 2D → 3D unreachable by any route — a project
+ * that started as a 2D game could never become a 3D one.)
  */
 export function upgradeBundle(current: Bundle, detected: Bundle): Bundle {
-  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 1, "ar-app": 2 }
+  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 2, "ar-app": 3 }
   return rank[detected] > rank[current] ? detected : current
 }
 
+/**
+ * Whether to honor the model's own `<bundle>` directive (parseBundleDirective). Unlike detection,
+ * an explicit request may move in ANY direction: the model is saying the APIs the request needs
+ * are not documented in its current bundle — turning a 2D game into 3D, a 3D app into AR, or a 3D
+ * scene back into a 2D game are all legitimate. The old code it rewrites is in its context; it
+ * needs no documentation to replace it. Only a no-op (asking for the bundle it already has) is
+ * refused, which also rules out a re-send loop.
+ */
+export function canSwitchBundle(current: Bundle, requested: Bundle): boolean {
+  return requested !== current
+}
+
 const DIRECTIVE_WORD: Record<string, Bundle> = { "2d": "2d-game", "3d": "3d-app", "ar": "ar-app" }
 
 /**

package/src/animate/tween/Animation.ts

@@ -0,0 +1,378 @@
+// 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
+// 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"
+
+const OP_PLAY = 0
+const OP_PAUSE = 1
+const OP_RESUME = 2
+const OP_CANCEL = 3
+const OP_FINISH = 4
+
+const EV_CALL = 0
+const EV_FINISH = 1
+const EV_VALUE = 2   // (id, 2, slot, lane0, lane1, …) — a VALUE track's frame, synchronous from the host
+
+/** Playback control shared by element tweens and timelines. Times are **milliseconds**. */
+export interface Animation {
+  /** One iteration, ms. */
+  readonly duration: number
+  /** Position inside the current iteration, ms. Writable = seek. */
+  time: number
+  /** 0..1 of the whole animation (iterations included). Writable = seek. */
+  progress: number
+  /** Playback rate; negative runs backwards, 0 freezes. */
+  rate: number
+  readonly playing: boolean
+  /** Resolves `true` when the animation reaches its end, `false` when cancelled, replaced or replayed. Never rejects. */
+  readonly finished: Promise<boolean>
+  /** Start from t = 0 (a running animation restarts). */
+  play(): this
+  pause(): this
+  resume(): this
+  /** Jump to `ms`; playback state is unchanged. */
+  seek(ms: number): this
+  /** Jump to the end: values land, commits apply, `finished` resolves `true`. */
+  finish(): this
+  /** Stop where it is — no commit, `finished` resolves `false`. */
+  cancel(): this
+  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>()
+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)
+    if (!a) return
+    if (kind === EV_CALL) a._fireCall(index)
+    else if (kind === EV_FINISH) a._hostFinished()
+    else if (kind === EV_VALUE) {
+      // lanes ride as plain number arguments (no per-frame array on either side)
+      const n = arguments.length - 3
+      for (let i = 0; i < n; i++) valueScratch[i] = arguments[i + 3] as number
+      a._fireValue(index, valueScratch)
+    }
+  })
+}
+
+/** Reused lane buffer for VALUE deliveries (the host's largest kind is 10 lanes). */
+const valueScratch = new Float32Array(16)
+
+/** The concrete handle — what the SDK instantiates behind `animateTo` / `animateFrom` / `Timeline`.
+ *  User code sees the {@link Animation} interface; the class itself must stay in the public
+ *  declarations because `TimelineImpl` extends it — marking it internal (even mentioning the tag in
+ *  this comment: the strip is a substring match) drops the timeline's playback members. */
+export class TweenAnimation implements Animation {
+  /** @internal */
+  _spec: TweenSpec
+  /** @internal Time-callbacks by call index (the spec's `calls[i]`). */
+  _calls: Array<() => void> = []
+  /** @internal VALUE-track deliverers by slot (`animate()` / `Timeline.animate`). */
+  _values = new Map<number, (lanes: Float32Array) => void>()
+
+  private _id = 0                 // host id, 0 = not created
+  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
+  private _rate: number
+  private _finished!: Promise<boolean>
+  private _resolve!: (done: boolean) => void
+  private _settled = true
+  private _listeners: Array<(done: boolean) => void> = []
+  private _fb?: Fallback
+
+  constructor(spec: TweenSpec) {
+    this._spec = spec
+    this._rate = spec.rate
+    this._newPromise()
+  }
+
+  private _newPromise(): void {
+    this._finished = new Promise<boolean>((r) => { this._resolve = r })
+    this._settled = false
+  }
+
+  private _settle(done: boolean): void {
+    if (this._settled) return
+    this._settled = true
+    this._playing = false
+    this._resolve(done)
+    for (const fn of this._listeners) fn(done)
+  }
+
+  get duration(): number { return this._spec.durationMs }
+  get playing(): boolean { return this._playing }
+  get finished(): Promise<boolean> { return this._finished }
+
+  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)
+  }
+
+  get time(): number {
+    if (this._id) return (_creatorUI as any).tweenGetTime?.(this._id) ?? 0
+    return this._fb?.time ?? this._endTime
+  }
+  set time(ms: number) { this.seek(ms) }
+
+  get progress(): number {
+    const total = this._totalMs()
+    return total > 0 ? Math.min(1, Math.max(0, this._elapsedMs() / total)) : 1
+  }
+  set progress(p: number) {
+    const total = this._totalMs()
+    this._seekTotal(Math.min(1, Math.max(0, p)) * total)
+  }
+
+  private _totalMs(): number {
+    const s = this._spec
+    const n = s.iterations < 0 ? 1 : s.iterations
+    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)
+  }
+  private _seekTotal(ms: number): void {
+    if (hasCore()) {
+      this._ensure()
+      ;(_creatorUI as any).tweenSeek(this._id, ms)
+    } else {
+      this._ensureFallback().seek(ms)
+    }
+  }
+
+  /** Create the host animation (paused at t = 0) if it doesn't exist. */
+  private _ensure(): void {
+    if (this._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)
+  }
+
+  private _destroy(): void {
+    if (this._id) {
+      live.delete(this._id)
+      ;(_creatorUI as any).tweenControl(this._id, OP_CANCEL)
+      this._id = 0
+    }
+    this._fb?.cancel()
+    this._fb = undefined
+  }
+
+  play(): this {
+    // A replay: whoever waited on the previous run gets `false` (unless it already ended), the host
+    // object is rebuilt (ids may have changed — a screen re-mounts its nodes on every open). The
+    // FIRST play keeps the promise handed out before it — unless a `cancel()` before any play has
+    // already settled that one, in which case this run gets a fresh promise.
+    if (this._started) {
+      this._settle(false)
+      this._destroy()
+    }
+    if (this._settled) this._newPromise()
+    this._started = true
+    this._endTime = 0
+    // Commit = the last keyframe becomes the stored state NOW (as `animateTo` always did), so reads
+    // and later `.style()` merges see the final state while the host is still tweening.
+    for (const t of this._spec.tracks) {
+      if (!t.commit || !t.channel.commit) continue
+      const last = t.keys[t.keys.length - 1]
+      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()
+    }
+    return this
+  }
+
+  pause(): this {
+    if (hasCore()) { this._ensure(); (_creatorUI as any).tweenControl(this._id, OP_PAUSE) }
+    else this._ensureFallback().pause()
+    this._playing = false
+    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._playing = true
+    return this
+  }
+
+  seek(ms: number): this {
+    // `time` is inside the current iteration; a seek by time on a looping animation stays in it.
+    const s = this._spec
+    const period = s.durationMs * (s.pingPong && s.iterations !== 1 ? 2 : 1)
+    const iter = period > 0 ? Math.floor(this._elapsedMs() / period) : 0
+    this._seekTotal(iter * period + Math.max(0, ms))
+    return this
+  }
+
+  finish(): this {
+    if (hasCore()) {
+      this._ensure()
+      ;(_creatorUI as any).tweenControl(this._id, OP_FINISH)   // the host answers with EV_FINISH
+    } else {
+      this._ensureFallback().finish()
+    }
+    return this
+  }
+
+  cancel(): this {
+    this._destroy()
+    this._settle(false)
+    return this
+  }
+
+  onFinish(fn: (done: boolean) => void): this {
+    this._listeners.push(fn)
+    return this
+  }
+
+  /** @internal */
+  _fireCall(index: number): void { this._calls[index]?.() }
+  /** @internal */
+  _fireValue(slot: number, lanes: Float32Array): void { this._values.get(slot)?.(lanes) }
+
+  /** @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 }
+    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). */
+export const singleTargetSpec = (tracks: Track[], clock: number, iterations: number, pingPong: boolean, delayMs: number): TweenSpec => {
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  // `delay` lives on the tracks (the first key holds through it, §3.1); the spec delay is 0 here
+  return { clock, durationMs, delayMs, iterations, pingPong, rate: 1, tracks, calls: [] }
+}
+
+export { CLOCK_UI, CLOCK_GAME }