lecodes-sdk 0.19.0

package/dist/types/net/replication.d.ts

@@ -0,0 +1,101 @@
+import { Aspect } from "../core/Aspect";
+import { Vec3 } from "../math/vec";
+import type { Node } from "../gl/Node";
+import { Scene } from "../gl/Scene";
+import { type Layout } from "./codec";
+import { NetPlayer } from "./core";
+export type NetTransform = "pos" | "pos+rot" | "none";
+/** The per-tick input layout: `const PlayerInput = Net.input({ moveX: 0, moveY: 0, jump: false })`. */
+export type NetInput<T extends object = any> = {
+    readonly layout: Layout;
+    readonly defaults: T;
+    readonly __t?: T;
+};
+/** A replicated entity type: `const PlayerKind = Net.kind('player', { pos: [0,0,0], hp: 100 }, { transform: 'pos', client })`. */
+export type NetKind<S extends object = any> = {
+    readonly name: string;
+    readonly layout: Layout;
+    readonly defaults: S;
+    /** Which state fields the SDK samples on the server and applies to a client proxy: `pos` (a
+     *  `pos: [x,y,z]` field), `pos+rot` (+ a `rot: [x,y,z,w]` quaternion field), or `none`. */
+    readonly transform: NetTransform;
+    /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns. */
+    readonly client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void;
+    readonly __t?: S;
+};
+/** Live counters (`Net.stats`): how the clocks and the prediction are doing. */
+export declare const stats: {
+    /** client: snapshots received */ snapshots: number;
+    /** client: how far ahead of the server's simulation our newest input was at the last snapshot */ ahead: number;
+    /** client: our tick minus the estimated server tick */ lead: number;
+    /** client: tick nudges (+1 / −1) by the lead control */ nudges: number;
+    /** owner: corrections applied, the largest one and their sum (metres) — `sum / corrections` = the typical one */ corrections: number;
+    maxCorrection: number;
+    sumCorrection: number;
+    /** server: inputs that arrived late (the last one was repeated), all clients */ missed: number;
+    /** bytes sent on the unreliable channel (snapshots / inputs) */ bytesOut: number;
+};
+export declare class NetEntity<S extends object = any> {
+    /** Session-unique id, assigned by the server. */
+    readonly netId: number;
+    readonly kind: NetKind<S>;
+    /** The owning player's id; 0 = the server's own (props, the game state). */
+    readonly ownerId: number;
+    /** Server: the authoritative state you write (`pos` is sampled from the node). Client remote:
+     *  interpolated. Client owner: the newest authoritative state. */
+    readonly state: S;
+    /** The node carrying this entity (server: yours; client: what the kind's factory returned). */
+    node: Node | null;
+    /** Owner on a client: the visual offset left by the last correction, decaying to zero — add it to
+     *  what you DRAW (a child mesh, the camera), never to physics. */
+    readonly correction: Vec3;
+    constructor(netId: number, kind: NetKind<S>, ownerId: number, s: S);
+    get owner(): NetPlayer | null;
+    /** Our own player owns it (offline: everything owned by `Net.me`). */
+    get isMine(): boolean;
+    /** This machine runs the simulation for it: the server always, a client for what it owns
+     *  (prediction). A remote proxy on a client is interpolation only. */
+    get simulated(): boolean;
+    /** The owner's input for the tick being simulated — the ring entry on the server (the last one
+     *  repeated when it is late), the local input on the owner / host / offline. */
+    input<T extends object>(inp: NetInput<T>): T;
+    /** Client: `state` was refreshed (a snapshot landed / the interpolation moved). */
+    on(event: "state", cb: (s: S) => void): this;
+    off(event: "state", cb: (s: S) => void): this;
+}
+export declare const declareKind: <S extends object>(name: string, defaults: S, opts?: {
+    transform?: NetTransform;
+    client?: NetKind<S>["client"];
+}) => NetKind<S>;
+export declare const declareInput: <T extends object>(defaults: T) => NetInput<T>;
+export declare const setInput: <T extends object>(inp: NetInput<T>, values: Partial<T>) => void;
+export declare const currentTick: () => number;
+export declare const allEntities: () => NetEntity[];
+export declare const entityById: (netId: number) => NetEntity | undefined;
+/**
+ * The server's handle on a replicated entity — attach it to the node that IS the entity:
+ * `new Node().aspect(Replicated, { kind: PlayerKind, owner: player })`. From then on the entity exists
+ * on every client (the kind's `client` factory births the proxy there, and the SDK attaches this same
+ * aspect to it), its state is packed into every snapshot, and `node.destroy()` despawns it everywhere.
+ * `node.replicated.state` / `.isMine` / `.simulated` / `.input()` are the same on both sides.
+ */
+export declare class Replicated extends Aspect<"replicated", Node> {
+    static readonly aspect = "replicated";
+    /** Server: the entity type (required). */
+    kind: NetKind<any>;
+    /** Server: the owning player, or null for the server's own. */
+    owner: NetPlayer | null;
+    protected onAttach(): void;
+    protected onDetach(): void;
+    /** The entity itself (what the client factory received). */
+    get entity(): NetEntity;
+    get netId(): number;
+    get state(): any;
+    get isMine(): boolean;
+    get simulated(): boolean;
+    get ownerPlayer(): NetPlayer | null;
+    get correction(): Vec3;
+    /** The owner's input for the tick being simulated (see `NetEntity.input`). */
+    input<T extends object>(inp: NetInput<T>): T;
+}
+export declare const installReplication: () => void;

package/dist/types/plugins/camera.d.ts

@@ -0,0 +1,25 @@
+import { File } from "../runtime/fetch";
+import { type PresentOptions } from "../ui/presentable";
+import { NativeView } from "../ui/NativeView";
+export type CameraFacing = "front" | "back";
+export interface CameraView extends NativeView {
+    /** Request camera permission, then present the preview. The current destination stays visible
+     *  until the camera is ready; rejects if permission is denied, the host has no camera, or
+     *  another navigation superseded this one. */
+    open(options?: PresentOptions): Promise<void>;
+    /** Capture a still frame as an image `File` (host-encoded). */
+    takePhoto(): Promise<File>;
+    /** Switch between the front and back camera while the preview is live. */
+    setFacingMode(facingMode: CameraFacing): Promise<void>;
+}
+/**
+ * Create a camera view (default: the back camera). `CameraView.isSupported` reports whether this
+ * host has a camera capability — check it before offering the feature.
+ */
+export declare const CameraView: {
+    (options?: {
+        facingMode?: CameraFacing;
+    }): CameraView;
+    /** Whether this host registered a "camera" view. */
+    readonly isSupported: boolean;
+};

package/dist/types/plugins/geolocation.d.ts

@@ -0,0 +1,39 @@
+export interface GeoPosition {
+    latitude: number;
+    longitude: number;
+    /** Horizontal accuracy radius, meters. */
+    accuracy: number;
+    /** Meters above sea level, or null when the provider doesn't know. */
+    altitude: number | null;
+    /** Direction of travel in degrees clockwise from north, or null when stationary/unknown. */
+    heading: number | null;
+    /** Ground speed in m/s, or null when unknown. */
+    speed: number | null;
+    /** When this fix was taken, ms epoch. */
+    timestamp: number;
+}
+export interface GeoOptions {
+    /** Prefer the precise (GPS) provider — slower first fix, more battery. Default false. */
+    highAccuracy?: boolean;
+    /** getCurrent only: reject with "timeout" if no fix arrives in this many ms. */
+    timeout?: number;
+}
+/** A live `Geolocation.watch()` subscription — `stop()` it when the screen goes away. */
+export interface GeoWatch {
+    stop(): void;
+}
+/**
+ * The device position. `Geolocation.isSupported` reports whether this host registered the
+ * service — check it before offering location features.
+ */
+export declare const Geolocation: {
+    /** Whether this host registered a "geolocation" service. */
+    readonly isSupported: boolean;
+    /** One position fix. Prompts for permission on first use; rejects on denial ("denied"), no
+     *  provider ("unavailable"), or `options.timeout` elapsing ("timeout"). */
+    getCurrent(options?: GeoOptions): Promise<GeoPosition>;
+    /** Continuous updates. Resolves once watching (permission granted + provider started) — so a
+     *  denial is a rejection, never a silently dead callback. One host watch serves every
+     *  subscriber; the options of the watch that starts it win. Always `stop()` when done. */
+    watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch>;
+};

package/dist/types/plugins/oauth.d.ts

@@ -0,0 +1,25 @@
+export type OAuthProviderName = "google" | "apple" | "yandex" | "vk";
+/** What a native provider SDK yields — pass it verbatim to your endpoint / `auth.oauth.signIn`. */
+export type OAuthCredential = {
+    provider: OAuthProviderName;
+    /** OAuth access token (Yandex, VK ID). */
+    accessToken?: string;
+    /** OpenID identity token (Google, Apple). */
+    idToken?: string;
+    /** Apple only sends the name once, on the first sign-in — forward it so the server can store it. */
+    name?: string;
+    email?: string;
+};
+/**
+ * Native provider sign-in. `OAuth.isSupported` reports whether this host registered the service;
+ * `OAuth.providers()` which providers it has SDKs for. Otherwise open `auth.oauth.url(provider)` (server)
+ * with `openURL` — the browser broker.
+ */
+export declare const OAuth: {
+    /** Whether this host registered an "oauth" service. */
+    readonly isSupported: boolean;
+    /** The providers this host can sign in with natively. */
+    providers(): Promise<OAuthProviderName[]>;
+    /** Run the provider's native sheet; resolves with the credential for `auth.oauth.signIn`. Rejects "cancelled" / "unavailable". */
+    signIn(provider: OAuthProviderName): Promise<OAuthCredential>;
+};

package/dist/types/plugins/permission.d.ts

@@ -0,0 +1 @@
+export declare const _requestCameraPermission: () => Promise<void>;

package/dist/types/plugins/push.d.ts

@@ -0,0 +1,46 @@
+/** A delivered notification, as the app sees it. */
+export interface PushPayload {
+    title: string;
+    body?: string;
+    /** Deep link — also delivered through `app.launchUrl` / the app "url" event. */
+    url?: string;
+    /** The developer's own JSON, ≤ 2 KB serialized. */
+    data?: Record<string, any>;
+    badge?: number;
+}
+export interface PushStatus {
+    /** OS notification permission for the host app. "prompt" = not asked yet. */
+    permission: "granted" | "denied" | "prompt";
+    /** Whether this device already holds a registration (an address) for this app. */
+    registered: boolean;
+}
+export interface PushRegisterOptions {
+    /** Your app's OWN user id ("external user id"): lets your server send to `users: ["u42"]`
+     *  instead of storing addresses, fanning out to all the user's devices. CLIENT-ASSERTED and
+     *  unverified — never target sensitive content by user. The registration reflects the latest
+     *  `register()` call, so registering without `user` clears it (logout). */
+    user?: string;
+}
+export type PushEvent = "message" | "tap";
+/**
+ * Remote push notifications. `Push.isSupported` reports whether this host registered the
+ * service — check it before offering notification features.
+ */
+export declare const Push: {
+    /** Whether this host registered a "push" service. */
+    readonly isSupported: boolean;
+    /** Permission + registration state. Never prompts. */
+    getStatus(): Promise<PushStatus>;
+    /** Ask for permission (first time) and register this device → the opaque address your server
+     *  targets. Idempotent — safe to call every launch; rejects "denied" / "unavailable". */
+    register(options?: PushRegisterOptions): Promise<{
+        address: string;
+    }>;
+    /** Remove this device's registration (the address stops receiving). */
+    unregister(): Promise<void>;
+    /** The notification that cold-started this app run, or null. Stable across calls. */
+    getLaunch(): Promise<PushPayload | null>;
+    /** "message" = received while the app is open; "tap" = the user tapped one while it ran. */
+    addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void;
+    removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void;
+};

package/dist/types/plugins/qr.d.ts

@@ -0,0 +1,21 @@
+import { type PresentOptions } from "../ui/presentable";
+import { NativeView } from "../ui/NativeView";
+export interface QRScanner extends NativeView {
+    /** Fires per decoded camera frame: the decoded string, or `null` for a frame with no readable
+     *  code (expect those repeatedly while the user aims). The same code can be reported more than
+     *  once — `close()` or debounce once you have what you need. */
+    onScan(callback: (data: string | null) => void): this;
+    /** Request camera permission, then present the scanner. The current destination (and its
+     *  loading state) stays visible until the scanner is ready; rejects if the camera is denied,
+     *  the host can't scan, or another navigation superseded this one. */
+    open(options?: PresentOptions): Promise<void>;
+}
+/**
+ * Create a QR scanner view. `QRScanner.isSupported` reports whether this host can scan at all —
+ * check it before offering the feature.
+ */
+export declare const QRScanner: {
+    (): QRScanner;
+    /** Whether this host registered a "qrScanner" view. */
+    readonly isSupported: boolean;
+};

package/dist/types/plugins/service.d.ts

@@ -0,0 +1,33 @@
+export interface Service {
+    /** Invoke a method on the service (`battery.call("level")`). Arguments and the result are
+     *  JSON-serialized; rejects when the host has no such service or the method reports an
+     *  error. The host session opens lazily on the first call. */
+    call(method: string, ...args: any[]): Promise<any>;
+    /** Subscribe to an event the service emits while a session is open
+     *  (`battery.on("change", data => …)`). Payloads are JSON-decoded. */
+    on(event: string, callback: (data?: any) => void): this;
+    /** Remove a previously added listener. */
+    off(event: string, callback: (data?: any) => void): this;
+    /** Close the host session (stops whatever the service was doing). Listeners stay
+     *  registered — a later `call()` opens a fresh session that delivers to them again. */
+    close(): void;
+}
+/**
+ * A host-registered headless service — the UI-less sibling of `NativeView`. Use it for
+ * services without a typed wrapper: native code registered in your app shell
+ * (`engine.registerService("app.battery") { … }`) or a third-party plugin's channel.
+ * **Host-optional** — gate on `Service.isSupported` (the web editor registers none of them).
+ *
+ * ```ts
+ * if (Service.isSupported("app.battery")) {
+ *   const battery = Service("app.battery")
+ *   battery.on("change", data => { level.text = data.level + "%" })
+ *   const { level } = await battery.call("level")
+ * }
+ * ```
+ */
+export declare const Service: {
+    (name: string, params?: any): Service;
+    /** Whether this host registered a service under `name`. */
+    isSupported(name: string): boolean;
+};

package/dist/types/runtime/app.d.ts

@@ -0,0 +1,67 @@
+export type AppState = "active" | "background";
+/** `"landscape"` — either landscape direction (sensor landscape), `"portrait"` — upright only,
+ *  `"auto"` — released: the device's own rotation rules apply. */
+export type OrientationLock = "auto" | "portrait" | "landscape";
+type AppEventMap = {
+    /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
+     *  the host halts the frame loop — the last chance to persist state / pause work. */
+    pause: () => void;
+    /** The app returned to the foreground; frames are running again. */
+    resume: () => void;
+    /** A link arrived while the app was running (warm deep link). `app.launchUrl` is already
+     *  updated to the same value when this fires. */
+    url: (url: string) => void;
+    /** The on-screen keyboard changed. `height` mirrors `app.keyboardHeight` (the raw overlap, see
+     *  there); `duration` is the platform's keyboard animation duration in ms (0 where none) — pass
+     *  it to `animateTo` to move a composer in sync with the keyboard. */
+    keyboard: (height: number, duration: number) => void;
+};
+export declare const app: {
+    /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
+     *  hidden. `"active"` on hosts that don't track it. */
+    readonly state: AppState;
+    /** The URL the app was (most recently) opened with — the deep link — or `null` for a plain
+     *  launch. Warm links update it and fire the `"url"` event. */
+    readonly launchUrl: string | null;
+    /** On-screen keyboard height in logical px currently overlapping the app viewport, `0` when
+     *  hidden. This is the RAW overlap, independent of the focused input's `keyboardShrink` policy —
+     *  with the default shrink the layout already avoids the keyboard; the main consumer is overlay
+     *  mode (`keyboardShrink: false`), e.g. a chat composer's `pb`. `0` on hosts without an
+     *  on-screen keyboard. */
+    readonly keyboardHeight: number;
+    /** Lock the screen orientation — `"landscape"` for a horizontal game (the device rotates to
+     *  landscape right away and stays there whichever way it is held), `"portrait"` for upright
+     *  only, `"auto"` to release. Call it once at startup; the lock is per app run (it resets
+     *  when the app quits or restarts), so there is nothing to undo. The rotation arrives as an
+     *  ordinary resize — layouts reflow, a scene's viewport follows. Silent no-op on hosts
+     *  without a rotatable screen (desktop, headless, web). */
+    setOrientation(mode: OrientationLock): void;
+    /** Re-run this app's bundle in a fresh world — the platform's `location.reload()`. Pass `url`
+     *  to reboot with different launch arguments (the new run reads them via `app.launchUrl`),
+     *  `null` to reboot with a cleared one, or omit it to replay the current one. No-op on hosts
+     *  without world control (headless). */
+    restart(url?: string | null): void;
+    /** Leave this app. Inside the LeCodes viewer that returns to the launcher (the LeCodes home
+     *  screen); a standalone-built app leaves to the platform instead — Android backgrounds it,
+     *  iOS ignores the call (the platform forbids programmatic exit). */
+    quit(): void;
+    /** 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 `onBackPressed`, every pager is at its tab root and the router is at its
+     *  stack root. The place for app-wide policy — e.g. double-press-to-quit:
+     *
+     *  ```ts
+     *  let armedAt = 0
+     *  app.onBackPressed(() => {
+     *    if (Date.now() - armedAt < 2000) { app.quit(); return }
+     *    armedAt = Date.now()
+     *    toast("Press back again to exit")
+     *  })
+     *  ```
+     *
+     *  Replaces the previous handler; pass `null` to remove. */
+    onBackPressed(callback: (() => void) | null): void;
+    addEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void;
+    removeEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void;
+};
+export {};

package/dist/types/runtime/appEvents.d.ts

@@ -0,0 +1,7 @@
+type AppEventCallback = (data?: string) => void;
+export declare const appEventsOn: (event: string, cb: AppEventCallback) => void;
+export declare const appEventsOff: (event: string, cb: AppEventCallback) => void;
+type KeyboardCallback = (height: number, duration: number) => void;
+export declare const keyboardEventsOn: (cb: KeyboardCallback) => void;
+export declare const keyboardEventsOff: (cb: KeyboardCallback) => void;
+export {};

package/dist/types/runtime/channel.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/clipboard.d.ts

@@ -0,0 +1,7 @@
+export declare const clipboard: {
+    /** Put `text` on the system clipboard. Silent no-op on hosts without clipboard access. */
+    write(text: string): void;
+    /** Read text from the system clipboard. Rejects when the platform has no clipboard access, the
+     *  user denied it, or there is nothing readable. */
+    read(): Promise<string>;
+};

package/dist/types/runtime/datetime.d.ts

@@ -0,0 +1,80 @@
+export type Locale = "en" | "ru";
+export type DateInput = Date | number | string | DateValue;
+export type Unit = "ms" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/**
+ * An immutable moment in time — the value returned by [`date()`]. Wraps a single epoch-millisecond
+ * scalar (`t`); every method returns a new `DateValue` or a plain scalar, never mutating. Construct
+ * it with `date(...)`, not `new`.
+ */
+export declare class DateValue {
+    /** Epoch milliseconds — the one canonical scalar. Prefer `valueOf()`; this is public so `date(a)`
+     *  can read it back cheaply and so tooling can treat it as the value's single component. */
+    readonly t: number;
+    constructor(ms: number);
+    /**
+     * Format against a `day.js`-style token pattern (default `"D MMMM YYYY"`). Locale defaults to the
+     * current device language.
+     *
+     * Tokens: `YYYY`/`YY` year · `MMMM`/`MMM`/`MM`/`M` month · `DD`/`D` day · `dddd`/`ddd` weekday ·
+     * `HH`/`H` 24-hour · `hh`/`h` 12-hour · `mm`/`m` minute · `ss`/`s` second · `A`/`a` AM/PM.
+     *
+     * ```ts
+     * date().format()                     // "10 July 2026"  /  "10 июля 2026"
+     * date(ts).format("DD.MM.YYYY HH:mm") // "10.07.2026 14:05"
+     * date(ts).format("MMMM YYYY", "ru")  // "Июль 2026"  (nominative — no day token)
+     * ```
+     */
+    format(pattern?: string, locale?: Locale): string;
+    /**
+     * Human relative time vs `now` (default: the current time) — "5 minutes ago", "in 2 days",
+     * "5 минут назад", "через 2 дня". Reads as "just now" under ~45 seconds; handles Russian number
+     * agreement (`1 минуту` / `2 минуты` / `5 минут`). Locale defaults to the device language.
+     */
+    timeAgo(locale?: Locale, now?: DateInput): string;
+    /** Add `n` of a unit, returning a new value. Linear units (`ms`…`week`) are scalar ms math;
+     *  `month`/`year` are calendar-aware (clamp on short months, like day.js). */
+    add(n: number, unit: Unit): DateValue;
+    /** Subtract `n` of a unit. Equivalent to `add(-n, unit)`. */
+    subtract(n: number, unit: Unit): DateValue;
+    /** Snap down to the start of a unit (local time): start of day/hour/month/year, etc. */
+    startOf(unit: Unit): DateValue;
+    /** Snap up to the end of a unit (local time): the last millisecond of the day/hour/month/… */
+    endOf(unit: Unit): DateValue;
+    /** Epoch milliseconds. Enables `+date(x)`, `date(a) < date(b)`, `date(a) - date(b)` via coercion. */
+    valueOf(): number;
+    /** Whole seconds since the epoch (Unix time). */
+    unix(): number;
+    /** Signed difference to `other`, in whole `unit`s (default `ms`), truncated toward zero. */
+    diff(other: DateInput, unit?: Unit): number;
+    isBefore(other: DateInput): boolean;
+    isAfter(other: DateInput): boolean;
+    isSame(other: DateInput): boolean;
+    year(): number;
+    /** 0-based month (0 = January), matching `Date.getMonth`. */
+    month(): number;
+    /** Day of the month, 1–31. */
+    day(): number;
+    /** Day of the week, 0 (Sunday)–6 (Saturday), matching `Date.getDay`. */
+    weekday(): number;
+    hour(): number;
+    minute(): number;
+    second(): number;
+    /** A native `Date` snapshot of this value. */
+    toDate(): Date;
+}
+/**
+ * Create a `DateValue` — a locale-aware, immutable moment, dayjs-style. Accepts a `Date`, a
+ * millisecond timestamp (`Date.now()`), a parseable string, or another `DateValue`; with no argument
+ * it's the current time. Chain arithmetic and finish with `format` / `timeAgo`, both of which
+ * understand **English** and **Russian** and default to the current device language
+ * ([`device.language`](../runtime/device.ts)).
+ *
+ * ```ts
+ * date().format("dddd, D MMMM")            // "Friday, 10 July"  /  "пятница, 10 июля"
+ * date(ts).timeAgo()                       // "5 minutes ago"    /  "5 минут назад"
+ * date().add(3, "day").startOf("day").format("D MMMM")
+ * date(a).diff(b, "hour")                  // signed whole hours
+ * date(a).isBefore(b)                      // boolean
+ * ```
+ */
+export declare const date: (value?: DateInput) => DateValue;

package/dist/types/runtime/device.d.ts

@@ -0,0 +1,126 @@
+import { Quat } from "../math/quat";
+import { Vec3 } from "../math/vec";
+type ResizeCallback = (width: number, height: number) => void;
+type HdrChangeCallback = (headroom: number) => void;
+type DeviceEventMap = {
+    resize: ResizeCallback;
+    /** Connectivity came back (best-effort, navigator.onLine semantics). */
+    online: () => void;
+    /** Connectivity was lost. */
+    offline: () => void;
+    /** The headroom the 3D engine renders to moved (`device.hdr.headroom`): the display ramped up to
+     *  its peak after launch, brightness changed, the window went to another screen. */
+    hdrchange: HdrChangeCallback;
+};
+/** Semantic haptic styles for `device.vibrate`. Impact styles (`light`/`medium`/`heavy`/`soft`/
+ *  `rigid`) are a physical "tap" of varying weight; notification styles (`success`/`warning`/`error`)
+ *  cue an outcome; `selection` is a light tick for a value change. Chosen to map 1:1 onto iOS
+ *  `UIFeedbackGenerator` and, on Android, `HapticFeedbackConstants` / `VibrationEffect` — so the same
+ *  call feels native everywhere, rather than a duration that only web/Android can honor. */
+export type HapticStyle = "light" | "medium" | "heavy" | "soft" | "rigid" | "success" | "warning" | "error" | "selection";
+/** Options for `device.motion.start`. */
+export interface MotionOptions {
+    /** Sensor update interval in seconds (default 1/60). The sensor fuses at ≥ this rate in the
+     *  background; you poll the freshest sample each frame, so this is a floor, not a sync. */
+    interval?: number;
+    /** Frame the readables are delivered in. "world" (default): engine Y-up, screen-oriented — drops
+     *  straight into `camera.quaternion` / any node. "device": the raw sensor frame, no conversion. */
+    frame?: "world" | "device";
+}
+export declare const device: {
+    /** Which INPUT MODEL the app is running under — the thing to branch on when a build needs
+     *  mouse-look instead of on-screen sticks. It is not the OS name: a Mac reports `"desktop"`,
+     *  like Windows and Linux do (the OS/version detail is host-side, not here). */
+    readonly platform: "web" | "android" | "ios" | "desktop" | string;
+    readonly language: string;
+    /** Display device-pixel ratio (physical px per logical/CSS px): 1 on standard displays, 2–3 on
+     *  retina / iOS. Bake a Canvas at this ratio for crisp output without hardcoding, e.g.
+     *  `new Canvas(w, h, { pixelRatio: device.pixelRatio })`. NOTE: the web 2D/GL surface currently
+     *  renders at logical resolution, so on web this only helps UI canvases / is forward-looking for
+     *  2D; on iOS (physical surface) it makes 2D canvases crisp. Falls back to 1 if the host omits it. */
+    readonly pixelRatio: number;
+    /** Current display width in logical px — the same value the "resize" event delivers, but readable at
+     *  any time (not only inside the listener). 0 until the host has reported a size. */
+    readonly width: number;
+    /** Current display height in logical px — the same value the "resize" event delivers, readable at any
+     *  time. 0 until the host has reported a size. */
+    readonly height: number;
+    /** Opt into the precise-touch system where the platform supports it. OFF by default. When on, fast
+     *  strokes are sampled at the touch digitizer's full rate (iOS coalesced touches, ≈120–240 Hz) instead
+     *  of once per display frame (~60 Hz), so a pointer-heavy app (drawing, handwriting, dragging) gets more
+     *  points and smoother lines. Leave it off for tap/button UIs. No-op on hosts without a coalesced-input
+     *  concept (web already coalesces pointermove; headless). */
+    setPreciseTouch(enabled: boolean): void;
+    /** Fire a one-shot haptic of the given semantic `style` (default `"medium"`) — a physical tap on
+     *  supported hardware (iOS Taptic Engine, Android vibrator). Chosen by meaning, not duration, so it
+     *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
+     *  no haptic hardware (iPad, older iPhones, web, headless). */
+    vibrate(style?: HapticStyle): void;
+    /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
+     *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
+     *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */
+    motion: {
+        /** Whether this device has the motion sensors at all (no gyro → false; iPad/older, web, headless). */
+        readonly available: boolean;
+        /** Whether updates are currently running (start succeeded and stop hasn't been called). */
+        readonly enabled: boolean;
+        /** Begin sensor updates. Resolves to whether it actually started (false = no sensor / denied).
+         *  Async so a web host can await its permission prompt; native resolves immediately. */
+        start(options?: MotionOptions): Promise<boolean>;
+        /** Stop sensor updates and release the sensor (battery). */
+        stop(): void;
+        /** Capture the current heading as "forward" — a yaw-only recenter (pitch/roll stay gravity-
+         *  referenced, so the horizon stays level). No-op in the "device" frame. */
+        recenter(): void;
+        /** The device's current orientation as a `Quat`. In the "world" frame (default) it's engine Y-up
+         *  and screen-oriented, so `camera.quaternion = device.motion.attitude` is a complete magic-window
+         *  / panorama camera. `Quat.identity` until the first sample arrives / when not running. */
+        readonly attitude: Quat;
+        /** Gravity direction for tilt controls. In the "world" frame it's SCREEN space (x → right, y →
+         *  down, matching clientX/clientY), orientation-aware — a 2D game reads `gravity.x / gravity.y`.
+         *  `(0,0,0)` when not running. */
+        readonly gravity: Vec3;
+    };
+    /** The display's extended dynamic range — HDR. On a screen with headroom above SDR white (Apple's
+     *  XDR panels; the macOS host today) the 3D surface is float and the engine renders past 1.0:
+     *  1.0 is the white of the UI and of a diffuse white surface, and the sun, emissives and speculars
+     *  climb up to `headroom` times that. Everywhere else it is SDR: `available` false, `headroom` 1,
+     *  the look setters remembered but invisible.
+     *
+     *  Branch content on `available`, not on `headroom` — the live value ramps up from 1 over the
+     *  first seconds after launch and follows the brightness keys. Particle `emissive` is the thing
+     *  to raise: it is in post-exposure units (1 = white on screen) and everything above that clips on
+     *  SDR, so an HDR display is the only place a fireball peaking at 8 reads as one. */
+    hdr: {
+        /** Whether the surface can show anything above SDR white at all (`maxHeadroom > 1`). */
+        readonly available: boolean;
+        /** The peak the display can reach, as a multiple of SDR white (a 1600-nit XDR panel reports up
+         *  to 16). Constant for the surface; 1 on SDR. */
+        readonly maxHeadroom: number;
+        /** The headroom the engine renders to right now — the screen's current peak as a multiple of SDR
+         *  white, quantised to half-stops. Moves with brightness and the screen under the window
+         *  (`hdrchange` event); never below 1. */
+        readonly headroom: number;
+        /** How much of the picture reaches for the headroom, 0..1 (default 0.35). 0 touches only what
+         *  SDR clipped — faithful to the SDR grade, but a mostly-mid-tone frame then looks flat next to
+         *  the one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit exterior
+         *  takes 1, a dim interior wants less. A host may pin it (`LECODES_HDR_STRENGTH`). */
+        strength: number;
+        /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
+         *  console game's calibration screen, where paper white sits at ~200 nits against SDR's ~100.
+         *  It scales the WHOLE picture: at 1 a white wall is as bright as the UI's white, at 2 it is
+         *  twice that, and highlights still climb above it (the engine keeps `headroom / paperWhite` for
+         *  them, clamped at the peak). `strength` decides how much of the picture reaches for the
+         *  peak; this decides where the picture starts. 1.5–2 is the console norm; a game that wants to
+         *  read as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. A host may
+         *  pin it (`LECODES_HDR_PAPER_WHITE`). */
+        paperWhite: number;
+    };
+    /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
+     *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
+     *  `"offline"`. */
+    readonly online: boolean;
+    addEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void;
+    removeEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void;
+};
+export {};

package/dist/types/runtime/fetch.d.ts

@@ -0,0 +1,31 @@
+export type FetchOptions = {
+    body?: any;
+    method?: string;
+    headers?: Record<string, string>;
+    useOnce?: boolean;
+    onProgress?: (progress: {
+        loaded: number;
+        total?: number;
+    }) => void;
+};
+export interface FetchResponse {
+    readonly status: number;
+    json<T = any>(): T;
+    text(): string;
+    dispose(): void;
+}
+export declare const fetch: (url: string, options?: FetchOptions) => Promise<FetchResponse>;
+export declare const fetchLocal: (path: string) => FetchResponse;
+/** A handle to a picked / fetched file (see openFilePicker). */
+export declare class File {
+    readonly name: string;
+    readonly size: number;
+    constructor(systemId: number, name: string, size: number);
+}
+type FormDataValue = string | number | boolean | File | FetchResponse;
+export declare class FormData {
+    private _entries;
+    append(name: string, value: FormDataValue, filename?: string): void;
+    delete(name: string): void;
+}
+export {};