lecodes-sdk 1.1.0 → 2.0.0

package/src/bridges/device.d.ts

@@ -0,0 +1,72 @@
+// The device bridge (`_creatorDevice`): what the app runs on — platform facts, haptics, the motion
+// sensor, the clipboard, the share sheet, the file picker, the camera permission.
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). A HOST bridge (`@host`, see ./app.d.ts): the native side is the `HostDevice`
+// table of runtime/native/include/creator-pkg/host.gen.h, generated from this file. Data properties
+// (`platform`, `language`, `pixelRatio`) are FIELDS of that table, read on every access, so a host
+// may update them in place (a window moving to a display of another density).
+import type { bytes, f32, f64 } from "./types"
+
+declare global {
+  /** @host device */
+  var _creatorDevice: {
+    /** The host bucket surfaced as `device.platform`. Apps BRANCH on it (mouse-look vs on-screen
+     *  sticks, hover affordances, key hints), so it names the INPUT MODEL, not the OS — one of
+     *  "web" | "ios" | "android" | "desktop". macOS reports "desktop", not "macos": a project
+     *  testing `device.platform === "desktop"` must get the same answer on every desktop host.
+     *  OS/version detail belongs in the host's own systemInfo callback, never here. */
+    platform: string
+    language: string
+    /** Display device-pixel ratio (physical px per CSS/logical px): 1 on standard displays, 2–3 on
+     *  retina / iOS. Surfaced as device.pixelRatio — for baking a Canvas at the right resolution
+     *  without hardcoding it. */
+    pixelRatio: f64
+    /** Opt into the precise-touch system (full-rate coalesced sampling) where the host supports it —
+     *  iOS coalesced touches. Surfaced as device.setPreciseTouch. Optional: hosts without a
+     *  coalesced-input concept (web, headless) simply don't implement it. */
+    setPreciseTouch?(enabled: boolean): void
+    /** Fire a one-shot semantic haptic (device.vibrate). `style` is a HapticStyle string. Optional:
+     *  hosts without haptic hardware (web, headless, iPad / older iPhones) simply don't implement it. */
+    vibrate?(style: string): void
+
+    // ---- device.motion (orientation sensor; pull-per-frame model) --------------------------------
+    /** Does this device have the motion sensors (gyro)? Surfaced as device.motion.available. */
+    motionAvailable?(): boolean
+    /** Start fused device-motion updates at `interval` seconds; returns whether it started (false =
+     *  no sensor / permission denied). May return a Promise on hosts with an async permission prompt
+     *  (web). Surfaced as device.motion.start. */
+    motionStart?(interval: f64): boolean | Promise<boolean>
+    /** Stop updates and release the sensor. Surfaced as device.motion.stop. */
+    motionStop?(): void
+    /** The freshest raw sample in the DEVICE frame: `[qx,qy,qz,qw, gx,gy,gz, interfaceOrientation]`
+     *  (orientation code: 0 portrait, 1 landscapeLeft, 2 landscapeRight, 3 upsideDown), or null until
+     *  the first sample / when not running. The SDK converts it to world/screen space. @out 8 */
+    motionSample?(): Float32Array | null
+
+    // ---- Clipboard (docs/app-lifecycle-plan.md) ---------------------------------------------------
+    /** Write text to the system clipboard (fire-and-forget). Backs clipboard.write. */
+    clipboardWrite?(text: string): void
+    /** Read text from the system clipboard — async because web needs a permission prompt; native
+     *  hosts may complete synchronously. Reject = no access / nothing readable. Backs clipboard.read. */
+    clipboardRead?(onComplete: (text: string) => void, onReject: (err: string) => void): void
+
+    // ---- Share, pick, camera ----------------------------------------------------------------------
+    /** Present the OS media share sheet for a host buffer (`systemId` — a File/response id), with an
+     *  optional caption. iOS: the share sheet also offers "Save to Files"/Photos. Web: saves
+     *  (downloads) the file; desktop saves to Downloads. Backs the SDK `share(media, text?)`, which
+     *  is a no-op where the host has no slot (headless, the windowless server). */
+    share?(systemId: bytes, text?: string): void
+    /** The OS file picker. Settles `onComplete` with the picked files as `[systemId, name, size]`
+     *  rows (an empty list / null for a cancelled dialog — not a rejection), `onReject` with the
+     *  error. Absent on hosts without a dialog (headless, CREATOR_HIDDEN runs): the SDK resolves
+     *  "nothing picked". */
+    openFilePicker?(onComplete: (files: [id: number, name: string, size: number][] | null) => void, onReject: (err: Error) => void, multiple: boolean, accept?: string): void
+    /** Prompt for camera permission (resolve = granted, reject = denied). Shared by everything that
+     *  needs the camera — ARScene.prepare, QRScanner, CameraView. Optional: hosts whose view
+     *  factory prompts on its own (web getUserMedia) don't implement it and the SDK resolves
+     *  immediately, so callers go through `_requestCameraPermission()`. */
+    requestCamera?(onComplete: () => void, onReject: () => void): void
+  }
+}
+
+export {}

package/src/bridges/fetch.d.ts

@@ -0,0 +1,80 @@
+// The fetch bridge (`_creatorFetch`): HTTP requests, local assets by name, and the host BUFFER
+// STORE every `systemId` of the platform points into (a fetched body, a picked file, a canvas bake,
+// a local asset — the `bytes` alias of ./types.d.ts, the `_id` an SDK File / FetchResponse carries).
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). A HOST bridge (`@host`, see ./app.d.ts): the native side is the `HostFetch`
+// table of runtime/native/include/creator-pkg/host.gen.h, generated from this file. The store is the
+// HOST's (it owns the bytes; the runtime reads them through `buffer` / `bufferSlice` and never keeps
+// them), so a `bytes` parameter of any bridge reaches native code as that id.
+import type { bytes, i32 } from "./types"
+
+/** One part of a multipart request body (the SDK `FormData`'s `_entries`). A text field carries
+ *  `value`; a binary one carries the host buffer id in `bufferId` (a File / FetchResponse `_id`)
+ *  and `value` null. */
+export type FetchFormEntry = {
+  key: string
+  value: string | null
+  /** -1 for a text field. */
+  bufferId: i32
+  filename: string | null
+}
+
+declare global {
+  /** @host fetch */
+  var _creatorFetch: {
+    /** `fetchOptions.body` is either a string or a FormData: an object carrying `_entries`, an
+     *  array of [key, value, filename?]. A `value` object carrying a numeric `_id` is binary (that's
+     *  the host buffer id — SDK `File` and `FetchResponse` both expose it under that key); anything
+     *  else is a text field. Same `_id` convention as an image `src` object (see _creatorTree.updateNode).
+     *  `onProgress` may also arrive positionally (5th argument); the runtime prefers
+     *  `fetchOptions.onProgress`. A host that reports progress calls it with `{ loaded, total? }`
+     *  (Android does; desktop does not). The runtime flattens the options into `HostFetch.request`. @custom */
+    fetch(url: string, fetchOptions: any, onComplete: (body: Handle, statusCode: number) => void, onReject: (err: string | Error) => void, onProgress?: (progress: { loaded: number, total?: number }) => void): void
+    /** A local asset by NAME → its buffer id, or -1 when the host has no such file. The host searches
+     *  its own places (the app's assets folder, the launched app.js's dir, the runtime dir) and caches
+     *  the id per name; `_creatorFiles.write` / `remove` on that name drop the cache. `asset()`
+     *  compiles to `"id:" + _creatorFetch.local(name)` (sdk/src/compile). */
+    local(path: string): i32
+    /** The buffer parsed as JSON (a syntax error throws). @custom */
+    toJson(systemId: bytes): any
+    /** The buffer's bytes [start, end) decoded as text (the bundle-header sniff). @custom */
+    slice(systemId: bytes, start: i32, end: i32): string
+    /** The buffer decoded as UTF-8 text. @custom */
+    toText(systemId: bytes): string
+    /** The buffer as a Uint8Array copy (a `.terrain` file, any binary the SDK parses itself). @custom */
+    toBytes(systemId: bytes): Uint8Array
+    /** Release a buffer the app is done with. Optional: a host that keeps every buffer for the
+     *  process (desktop, where `local` ids are also cached by name) leaves the slot null. */
+  }
+}
+
+/** The slots of `HostFetch` the runtime calls and JS never sees. */
+export interface HostFetch {
+  /** Release a fetched body's buffer once its response was collected (owned.h). A host that keeps
+   *  every buffer for the process leaves the slot null. */
+  dispose?(systemId: i32): void
+  /** One HTTP request, off the JS thread. `headers` alternates name, value. `body` is the raw text
+   *  body or null; `form` the multipart entries (empty when the body is not a FormData) — a host
+   *  handles at least the raw body. Settle EXACTLY ONE of `onComplete(systemId, status)` /
+   *  `onReject(message)` through the dispatch queue (`dispatchHeapCall`) and free the other
+   *  (`jsFree`); `onProgress` (0 when the app passed none) may be called any number of times with
+   *  `{ loaded, total? }` before the settle and is the host's to free. A URL of the form `id:<n>`
+   *  is an asset the store already holds: resolve to that id with status 200. */
+  request(url: string, method: string, headers: string[], body: string | null, form: FetchFormEntry[], onComplete: (systemId: number, status: number) => void, onReject: (err: string) => void, onProgress?: (progress: { loaded: number, total?: number }) => void): void
+  /** The bytes of buffer `id` as a malloc'd copy the runtime frees, `addByte` = with a trailing
+   *  NUL (the runtime parses it as text). Null / size 0 for an unknown id. */
+  buffer(id: i32, addByte: boolean): bytes
+  /** Bytes [start, end) of buffer `id`, clamped; same ownership as `buffer`. */
+  bufferSlice(id: i32, start: i32, end: i32, addByte: boolean): bytes
+  /** The engine's built-in blobs by system id (1 = the default IBL, 2 = the ubershader archive,
+   *  3 = the materials archive — engines/gl/materials/pack.mjs: one file, or several archives back
+   *  to back), read from the host's runtime dir; same ownership as `buffer`. Null for an id the
+   *  host has nothing for. */
+  systemBuffer(id: i32): bytes
+  /** Store a copy of `bytes` as a new buffer and return its id (0 = the host cannot). The runtime
+   *  hands the store what it produced itself — an encoded canvas (`Canvas.toFile`). Optional: a
+   *  host without the slot makes `toFile` reject. */
+  putBuffer?(bytes: Uint8Array): i32
+}
+
+export {}

package/src/bridges/files.d.ts

@@ -0,0 +1,70 @@
+// The files bridge (`_creatorFiles`): the SDK `files` global — the read/write/delete half of
+// `_creatorFetch.local`, for hosts where the app OWNS a filesystem (desktop).
+// Part of the host contract. A HOST bridge (`@host`, see ./app.d.ts): the native side is the
+// `HostFiles` table of runtime/native/include/creator-pkg/host.gen.h, generated from this file.
+// OPTIONAL AS A WHOLE (`@optional`): a sandboxed host (web, mobile) provides no table, the global is
+// absent and `files.supported` is false there — the contract's "stand or fall together".
+//
+// ASYNC, like `fetch`: file IO must not block the frame, so each method takes an onComplete/onReject
+// pair (the SDK turns them into a promise) and the host does the work off the JS thread. Hosts
+// must keep the ops ORDERED — two appends to one file settle in call order — so a queue, not a
+// thread per call. Exactly one handle is ever settled (`dispatchHeapCall` + `jsFree`).
+//
+// PATH POLICY, identical for all of them and owned by the host: an ABSOLUTE path is used verbatim;
+// a RELATIVE one is resolved against the app's OWN folder — never the process cwd — which for a
+// packaged desktop app is the exe's directory, one of the directories `_creatorFetch.local` searches
+// by name. So `write("save.json", …)` and `local("save.json")` are a pair; the host drops the name's
+// cached id on write / remove so the next read sees the new bytes.
+
+/** One directory entry, as `list` / `stat` report it. */
+export type FileEntry = {
+  /** The last path segment. */
+  name: string
+  /** Relative to the listed directory, `/`-separated (equal to `name` unless the listing was
+   *  recursive). `stat` reports `name` here. */
+  path: string
+  kind: "file" | "dir"
+  /** Bytes; 0 for a directory. */
+  size: number
+  /** Last modification, ms since the epoch. */
+  modified: number
+}
+
+declare global {
+  /** @host files @optional */
+  var _creatorFiles: {
+    /** Write a file, creating the parent folders. `append` adds to the end instead of replacing.
+     *  `data` is text (written as UTF-8), raw bytes (Uint8Array / ArrayBuffer), or a host buffer
+     *  object carrying `_id` (an SDK `File` / `FetchResponse` — so a picked or generated file is
+     *  saved as it is). The runtime flattens it into one span for `HostFiles.write`; the bytes are
+     *  only valid for the duration of the call, so a host that defers the write copies them first. @custom */
+    write(path: string, data: string | Uint8Array | ArrayBuffer | { _id: number }, append: boolean, onComplete: () => void, onReject: (err: Error) => void): void
+    /** The whole file as bytes, or null when there is no such file. Unlike `_creatorFetch.local`
+     *  this re-reads every call and holds nothing — no buffer id to dispose. Only a real failure
+     *  (an unreadable file) rejects; "not there" is a null result. */
+    readBytes(path: string, onComplete: (bytes: Uint8Array | null) => void, onReject: (err: Error) => void): void
+    /** The whole file decoded as UTF-8 text, or null when there is no such file. */
+    readText(path: string, onComplete: (text: string | null) => void, onReject: (err: Error) => void): void
+    /** Delete a file, or an EMPTY directory; `recursive` also deletes a directory's contents.
+     *  Deleting something that is already gone SUCCEEDS — the post-condition is what matters. */
+    remove(path: string, recursive: boolean, onComplete: () => void, onReject: (err: Error) => void): void
+    /** Create a directory and any missing parents. An existing directory is success. */
+    mkdir(path: string, onComplete: () => void, onReject: (err: Error) => void): void
+    /** List a directory. Settles with an array of entries SORTED by `path`, so two runs and two
+     *  hosts agree. Symlinks are followed for `kind`; anything that is neither file nor directory
+     *  is skipped. A MISSING directory is a null result (like the readers); a path that is a file,
+     *  or an unreadable directory, rejects. */
+    list(path: string, recursive: boolean, onComplete: (entries: FileEntry[] | null) => void, onReject: (err: Error) => void): void
+    /** One entry's metadata for a file or a directory, or null when there is nothing at `path`. */
+    stat(path: string, onComplete: (entry: FileEntry | null) => void, onReject: (err: Error) => void): void
+  }
+}
+
+/** The slots of `HostFiles` the runtime calls and JS never sees. */
+export interface HostFiles {
+  /** `_creatorFiles.write` with the data flattened: `size` bytes to write / append. Settle
+   *  onComplete with no arguments. */
+  write(path: string, data: Uint8Array, append: boolean, onComplete: () => void, onReject: (err: Error) => void): void
+}
+
+export {}