lecodes-sdk 2.4.5 → 2.4.6

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.5",
+  "version": "2.4.6",
   "files": [
     "src",
     "dist",

package/src/bridges/app.d.ts

@@ -11,7 +11,7 @@
 // `?` on a method = an optional slot: a host that leaves it null gets no such JS method, so the SDK's
 // `typeof` feature-detects stay honest. The `HostApp` interface below adds the slots the runtime
 // calls that JS never sees (notifications to the host).
-import type { bytes, i32 } from "./types"
+import type { bytes, f64, i32 } from "./types"
 
 declare global {
   // ---- World control (run/restart/quit — the platform's `location` analog) ----------------------
@@ -58,6 +58,13 @@ declare global {
     /** Collect garbage, drain the release queue and report the live owned records per kind
      *  (`{"live":{"tree":n,…},"pending":n}`) — the read behind checks/owned. @custom */
     ownedStats(): string
+    /** Collect garbage and drain the release queue now, logging `[gc] app.gc: <ms>, heap …, next at
+     *  …, <n> owned resources freed`. `headroomMB` (> 0) puts the next automatic pass at least that
+     *  many megabytes above the heap the pass left (QuickJS; until that pass). On JavaScriptCore a
+     *  request (the engine collects on its own schedule, the drain follows: on iOS the line says 0;
+     *  no headroom); the wasm arm collects only under Bun, in a browser page it is the drain alone.
+     *  Web Lite has no such member. Backs app.gc. @custom */
+    gc?(headroomMB?: f64): void
     /** Current lifecycle state: "active" | "background". Surfaced as app.state. */
     state?(): string
     /** Current connectivity (navigator.onLine semantics — best-effort: false only when the platform

package/src/runtime/app.ts

@@ -113,6 +113,20 @@ export const app = {
   quit(): void {
     _creatorApp.quit?.()
   },
+  /** Collect garbage now: what the app no longer references — a finished level's nodes, its
+   *  textures and materials — is freed before this returns, not whenever the collector next runs.
+   *  Call it where a pause is invisible (a loading screen, between levels), after dropping the
+   *  references; never during play — a collection walks the whole heap. It also puts the next
+   *  automatic collection at half again the heap it leaves: the room the next stretch of play has.
+   *  `headroomMB` asks for more room when the play ahead allocates more than that — a drive that
+   *  streams in hundreds of megabytes of terrain buffers: `app.gc({ headroomMB: 512 })` keeps the
+   *  next collection at least 512 MB away (until it comes; then the engine's rule again). The log's
+   *  `[gc]` line says what it took, what it freed and where the next one is. On iOS a request the
+   *  engine serves on its own schedule, without the headroom; a no-op in the browser, where a page
+   *  cannot ask for a collection. */
+  gc(options?: { headroomMB?: number }): void {
+    _creatorApp.gc?.(options?.headroomMB)
+  },
   /** Global back-press fallback (Android back button/gesture — iOS has no system back). Fires
    *  only when nothing else consumed the press: no open widget/modal claimed it, the current
    *  screen has no `onBack`, every pager is at its tab root and the router is at its

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.5"
+export const SDK_VERSION = "2.4.6"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {