lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/inject.ts

@@ -1,171 +1,186 @@
-// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
-// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
-// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
-// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
-//
-// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
-// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
-// they live in src/host.d.ts as declarations and stay as free references at runtime.
-
-// ---- math ----
-export { Mathf } from "./math/Mathf"
-export { Vec2, Vec3 } from "./math/vec"
-export { Quat } from "./math/quat"
-export { Mat4 } from "./math/mat4"
-export { Color } from "./core/color"
-
-// ---- aspects (attachable node capabilities) ----
-export { Aspect, type With } from "./core/Aspect"
-export { InspectorUI } from "./core/InspectorUI"
-
-// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
-export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
-
-// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
-export { Canvas, Bitmap } from "./canvas/Canvas"
-
-// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
-export { toast, openURL, SvgSource } from "./runtime/misc"
-export { app, type AppState, type OrientationLock } from "./runtime/app"
-export { clipboard } from "./runtime/clipboard"
-export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
-export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
-export { localStorage } from "./runtime/storage"
-export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
-export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
-export { WebSocket } from "./runtime/net"
-// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
-// only ever imports its server functions (docs/backend-plan.md §4).
-export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
-export { AudioPlayer, VideoPlayer } from "./runtime/media"
-export { openFilePicker } from "./runtime/files"
-export { share } from "./runtime/share"
-export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
-
-// ---- 2D engine (creator-2d) ----
-export { Scene2D } from "./g2/Scene2D"
-export { Node2D } from "./g2/Node2D"
-export { Camera2D } from "./g2/Camera2D"
-export { Sprite } from "./g2/Sprite"
-export { SpriteAnimation } from "./g2/SpriteAnimation"
-export { Shape2D } from "./g2/Shape2D"
-export { Physics2D } from "./g2/Physics2D"
-export { Trigger2D } from "./g2/Trigger2D"
-export { CharacterController2D } from "./g2/CharacterController2D"
-export { Tilemap } from "./g2/Tilemap"
-export { Texture2D } from "./g2/Texture2D"
-// sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
-export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
-export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
-// tilesets as data (.tiles.ts files — autotile materials, see src/g2/Tileset.ts + autotile.ts)
-export { Tileset, defineTileset, Autotile2D } from "./g2/Tileset"
-export { rawCell, isRawCell, rawIndex } from "./g2/autotile"
-export { rot90, rot180, rot270, flipX, packTile, tileIndex, tileTurns, tileFlip, tileOriented } from "./g2/autotile"
-export type {
-  TilesetDef, TileMaterial, PatchMaterial, PathMaterial, PatchSlots, EdgeSlot, FillBlock, BlockEntry,
-  TileBlock, TilePart,
-} from "./g2/autotile"
-// 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
-export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
-export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
-export { cells, encodeCells, type CellsData } from "./g2/cells"
-// no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
-export { CameraFollow } from "./g2/scenarios2d"
-
-// ---- UI (creator-ui) ----
-export {
-  UIScreen, type UIScreenStyle,
-  UIRow, UIColumn, UIBox, type UIContainerStyle,
-  UIText, type UITextStyle,
-  UIButton, type UIButtonStyle,
-  UIImage, type UIImageStyle,
-  UIVideo, type UIVideoStyle,
-  UIInput, UITextArea, type UIInputStyle,
-  UIScrollable, type UIScrollableStyle,
-  UIPager, type UIPagerStyle,
-  UITabs, type UITabDef,
-  defineTabs, type TabDef, type TabsHandle,
-  UIWidget, type UIWidgetStyle,
-  UIModal, type UIModalStyle,
-  UIBottomSheet, type UIBottomSheetStyle,
-  UIPopover, type UIPopoverStyle,
-  UISpacer, type UISpacerStyle,
-  UIVirtualizedList,
-  Router,
-  NativeView, type UINativeViewStyle,
-  registerFont,
-  __uiMap,
-  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
-} from "./ui/UI"
-// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
-// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
-export { Presentable } from "./ui/UI"
-export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
-// The base node type + the union a container accepts as children — documented as the signature of
-// UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
-export type { UINode, UINodeChild } from "./ui/UINode"
-// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
-// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
-export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
-
-// ---- animate ----
-export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
-export { cubicBezier } from "./animate/bezier"
-export { easeIn, easeOut, easeInOut } from "./animate/easings"
-
-// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
-export { QRScanner } from "./plugins/qr"
-export { CameraView, type CameraFacing } from "./plugins/camera"
-export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
-export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
-export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
-export { Service } from "./plugins/service"
-
-// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
-export { defineScene, use, ref, make, SceneHandle, applyEditorPose as __applyEditorPose } from "./scene/defineScene"
-export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene, SceneInstance } from "./scene/defineScene"
-export { CameraPlace } from "./gl/CameraPlace"
-export type { FieldMeta } from "./core/fields"
-// Editor-only line drawing from generator rebuild() / make() factories / tool hooks — drawn by the
-// scene editor's viewport overlay, a no-op everywhere else (see src/scene/gizmos.ts).
-export { Gizmos, GizmoBuffer as __GizmoBuffer, withGizmoScope as __withGizmoScope } from "./scene/gizmos"
-export type { GizmoStyle } from "./scene/gizmos"
-
-// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
-export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
-
-// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
-export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
-export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
-
-// ---- 3D engine (creator-gl) ----
-export { Scene, ARScene, VRScene } from "./gl/Scene"
-export { Node } from "./gl/Node"
-export { Mesh } from "./gl/Mesh"
-export { Model } from "./gl/Model"
-export { Shape } from "./gl/Shape"
-export { Physics } from "./gl/Physics"
-export { Trigger } from "./gl/Trigger"
-export { CharacterController } from "./gl/CharacterController"
-export { Vehicle } from "./gl/Vehicle"
-export type { WheelConfig, WheelState, DriveLayout, SuspensionConfig, EngineConfig } from "./gl/Vehicle"
-export { AnimationClip } from "./gl/animation/AnimationClip"
-export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
-export { Animator } from "./gl/animation/Animator"
-export { Playback } from "./gl/animation/Playback"
-export { Loop } from "./gl/animation/Loop"
-export { Layer } from "./gl/animation/Layer"
-export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition } from "./gl/animation/core"
-export { IK } from "./gl/IK"
-export type { IKTwoBone, IKLookAt } from "./gl/IK"
-export { Light } from "./gl/Light"
-export { Material } from "./gl/Material"
-export { Geometry } from "./gl/Geometry"
-export { InstancedMesh } from "./gl/InstancedMesh"
-export type { InstanceTransform } from "./gl/InstancedMesh"
-export { Texture } from "./gl/Texture"
-export { Camera } from "./gl/Camera"
-export { Ray } from "./gl/Ray"
-export { Plane } from "./gl/Plane"
-export { Noise } from "./gl/Noise"
-export { Particles, Trail, curve, colorCurve } from "./gl/Particles"
+// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
+// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
+// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
+// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
+//
+// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
+// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
+// they live in src/host.d.ts as declarations and stay as free references at runtime.
+
+// ---- math ----
+export { Mathf } from "./math/Mathf"
+export { Vec2, Vec3 } from "./math/vec"
+export { Quat } from "./math/quat"
+export { Mat4 } from "./math/mat4"
+export { Color } from "./core/color"
+
+// ---- aspects (attachable node capabilities) ----
+export { Aspect, System, type With, type SystemHost } from "./core/Aspect"
+export { type EventMap } from "./core/events"
+export { Time } from "./core/time"
+export { InspectorUI } from "./core/InspectorUI"
+
+// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
+export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
+export { __compWrite, __compOp, type CompAxis, type CompWriter } from "./core/compWrite"
+
+// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
+export { Canvas, Bitmap } from "./canvas/Canvas"
+
+// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
+export { toast, openURL, SvgSource } from "./runtime/misc"
+export { app, type AppState, type OrientationLock } from "./runtime/app"
+export { clipboard } from "./runtime/clipboard"
+export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
+export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
+export { localStorage } from "./runtime/storage"
+export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
+export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
+export { WebSocket } from "./runtime/net"
+// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
+// only ever imports its server functions (docs/backend-plan.md §4).
+export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
+export { AudioPlayer, VideoPlayer } from "./runtime/media"
+export { openFilePicker } from "./runtime/files"
+export { share } from "./runtime/share"
+export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
+
+// ---- 2D engine (creator-2d) ----
+export { Scene2D } from "./g2/Scene2D"
+export { Node2D } from "./g2/Node2D"
+export { Camera2D } from "./g2/Camera2D"
+export { Sprite } from "./g2/Sprite"
+export { SpriteAnimation } from "./g2/SpriteAnimation"
+export { Shape2D } from "./g2/Shape2D"
+export { Physics2D } from "./g2/Physics2D"
+export { Trigger2D } from "./g2/Trigger2D"
+export { CharacterController2D } from "./g2/CharacterController2D"
+export { OneWay2D } from "./g2/OneWay2D"
+export { PhysicsGroup2D } from "./g2/groups2d"
+export { Tilemap } from "./g2/Tilemap"
+export { Texture2D } from "./g2/Texture2D"
+// sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
+export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
+export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
+// tilesets as data (.tiles.ts files — autotile materials, see src/g2/Tileset.ts + autotile.ts)
+export { Tileset, defineTileset, Autotile2D } from "./g2/Tileset"
+export { rawCell, isRawCell, rawIndex } from "./g2/autotile"
+export { rot90, rot180, rot270, flipX, packTile, tileIndex, tileTurns, tileFlip, tileOriented } from "./g2/autotile"
+export type {
+  TilesetDef, TileMaterial, PatchMaterial, PathMaterial, PatchSlots, EdgeSlot, FillBlock, BlockEntry,
+  TileBlock, TilePart,
+} from "./g2/autotile"
+// 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
+export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
+export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
+export { cells, encodeCells, type CellsData } from "./g2/cells"
+// no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
+export { CameraFollow } from "./g2/scenarios2d"
+
+// ---- UI (creator-ui) ----
+export {
+  UIScreen, type UIScreenStyle,
+  UIRow, UIColumn, UIBox, type UIContainerStyle,
+  UIText, type UITextStyle,
+  UIButton, type UIButtonStyle,
+  UIImage, type UIImageStyle,
+  UIVideo, type UIVideoStyle,
+  UIInput, UITextArea, type UIInputStyle,
+  UIScrollable, type UIScrollableStyle,
+  UIPager, type UIPagerStyle,
+  UITabs, type UITabDef,
+  defineTabs, type TabDef, type TabsHandle,
+  UIWidget, type UIWidgetStyle,
+  UIModal, type UIModalStyle,
+  UIBottomSheet, type UIBottomSheetStyle,
+  UIPopover, type UIPopoverStyle,
+  UISpacer, type UISpacerStyle,
+  UIVirtualizedList,
+  Router,
+  NativeView, type UINativeViewStyle,
+  registerFont,
+  __uiMap,
+  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
+} from "./ui/UI"
+// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
+// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
+export { Presentable } from "./ui/UI"
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
+// The base node type + the union a container accepts as children — documented as the signature of
+// UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
+export type { UINode, UINodeChild } from "./ui/UINode"
+// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
+// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
+export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
+
+// ---- animate ----
+export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
+export { cubicBezier } from "./animate/bezier"
+export { easeIn, easeOut, easeInOut } from "./animate/easings"
+
+// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
+export { QRScanner } from "./plugins/qr"
+export { CameraView, type CameraFacing } from "./plugins/camera"
+export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
+export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
+export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
+export { Service } from "./plugins/service"
+
+// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
+export { defineScene, use, ref, make, SceneHandle, applyEditorPose as __applyEditorPose } from "./scene/defineScene"
+export {
+  defineMaterial, MaterialHandle,
+  // editor-harness helpers (the scene editor's live material paths — not app API)
+  assignMaterialDef as __assignMaterialDef, applyMaterialParam as __applyMaterialParam,
+} from "./scene/material"
+export type { MaterialData, MaterialParamValue, ShaderMaterialDef, LitMaterialDef, UnlitMaterialDef } from "./scene/material"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene, SceneInstance } from "./scene/defineScene"
+export { CameraPlace } from "./gl/CameraPlace"
+export type { FieldMeta } from "./core/fields"
+// Editor-only line drawing from generator rebuild() / make() factories / tool hooks — drawn by the
+// scene editor's viewport overlay, a no-op everywhere else (see src/scene/gizmos.ts).
+export { Gizmos, GizmoBuffer as __GizmoBuffer, withGizmoScope as __withGizmoScope } from "./scene/gizmos"
+export type { GizmoStyle, GizmoAnchor } from "./scene/gizmos"
+
+// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
+export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
+
+// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
+export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
+export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
+
+// ---- 3D engine (creator-gl) ----
+export { Scene, ARScene, VRScene } from "./gl/Scene"
+export { Node } from "./gl/Node"
+export { Mesh } from "./gl/Mesh"
+export { Model } from "./gl/Model"
+export { Shape } from "./gl/Shape"
+export { Physics } from "./gl/Physics"
+export { Trigger } from "./gl/Trigger"
+export { CharacterController } from "./gl/CharacterController"
+export { Vehicle } from "./gl/Vehicle"
+export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle"
+export { Wheel } from "./gl/Wheel"
+export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel"
+export { Gearbox } from "./gl/Gearbox"
+export { AnimationClip } from "./gl/animation/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
+export { Animator } from "./gl/animation/Animator"
+export { Playback } from "./gl/animation/Playback"
+export { Loop } from "./gl/animation/Loop"
+export { Layer } from "./gl/animation/Layer"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition } from "./gl/animation/core"
+export { IK } from "./gl/IK"
+export type { IKTwoBone, IKLookAt } from "./gl/IK"
+export { Light } from "./gl/Light"
+export { Lightmap } from "./gl/Lightmap"
+export { Material } from "./gl/Material"
+export { Geometry } from "./gl/Geometry"
+export { InstancedMesh } from "./gl/InstancedMesh"
+export type { InstanceTransform } from "./gl/InstancedMesh"
+export { Texture } from "./gl/Texture"
+export { Camera } from "./gl/Camera"
+export { Ray } from "./gl/Ray"
+export { Plane } from "./gl/Plane"
+export { Noise } from "./gl/Noise"
+export { Particles, Trail, curve, colorCurve } from "./gl/Particles"

package/runtime/sdk/runtime/device.ts

@@ -7,12 +7,17 @@ import { appEventsOn, appEventsOff } from "./appEvents"
 
 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
 }
 
 const resizeListeners: ResizeCallback[] = []
@@ -22,6 +27,25 @@ const onResize = (width: number, height: number): void => {
   for (const cb of resizeListeners.slice()) cb(width, height)
 }
 
+// --- device.hdr state ---
+// The 3D bridge is a free global that a 2D-only bundle never defines — reach it defensively. Hosts
+// without the methods are SDR by definition; the look setters are remembered so the getters read
+// back what the app asked for.
+const gl = (): typeof _creator | undefined => (typeof _creator !== "undefined" ? _creator : undefined)
+let hdrStrengthLocal = 0.35
+let hdrPaperWhiteLocal = 1
+// `hdrchange` is a poll: the engine quantises the headroom to half-stops, so a change is rare and
+// a 4 Hz timer (only while someone listens) is cheaper than a per-frame bridge call.
+const hdrListeners: HdrChangeCallback[] = []
+let hdrPollTimer: ReturnType<typeof setInterval> | undefined
+let hdrLastHeadroom = 1
+const pollHdr = (): void => {
+  const h = device.hdr.headroom
+  if (h === hdrLastHeadroom) return
+  hdrLastHeadroom = h
+  for (const cb of hdrListeners.slice()) cb(h)
+}
+
 /** 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
@@ -66,7 +90,10 @@ const orientedAttitude = (s: ArrayLike<number>): Quat => {
 }
 
 export const device = {
-  get platform(): "web" | "android" | "ios" | string {
+  /** 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). */
+  get platform(): "web" | "android" | "ios" | "desktop" | string {
     return _creatorUtils.platform
   },
   get language(): string {
@@ -162,6 +189,63 @@ export const device = {
       return new Vec3(g.x, -g.y, g.z)
     },
   },
+  /** 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`). */
+    get available(): boolean {
+      return device.hdr.maxHeadroom > 1
+    },
+    /** 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. */
+    get maxHeadroom(): number {
+      const v = gl()?.getDisplayMaxHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** 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. */
+    get headroom(): number {
+      const v = gl()?.getDisplayHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** 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`). */
+    get strength(): number {
+      return gl()?.getHdrStrength?.() ?? hdrStrengthLocal
+    },
+    set strength(v: number) {
+      const s = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.35
+      hdrStrengthLocal = s
+      gl()?.setHdrStrength?.(s)
+    },
+    /** 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`). */
+    get paperWhite(): number {
+      return gl()?.getHdrPaperWhite?.() ?? hdrPaperWhiteLocal
+    },
+    set paperWhite(v: number) {
+      const p = Number.isFinite(v) ? Math.min(8, Math.max(1, v)) : 1
+      hdrPaperWhiteLocal = p
+      gl()?.setHdrPaperWhite?.(p)
+    },
+  },
   /** 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"`. */
@@ -173,6 +257,14 @@ export const device = {
       appEventsOn(channel, callback as () => void)
       return
     }
+    if (channel === "hdrchange") {
+      hdrListeners.push(callback as HdrChangeCallback)
+      if (hdrPollTimer === undefined) {
+        hdrLastHeadroom = device.hdr.headroom
+        hdrPollTimer = setInterval(pollHdr, 250)
+      }
+      return
+    }
     if (channel !== "resize") return
     resizeListeners.push(callback as ResizeCallback)
     if (!resizeRegistered) {
@@ -185,6 +277,15 @@ export const device = {
       appEventsOff(channel, callback as () => void)
       return
     }
+    if (channel === "hdrchange") {
+      const i = hdrListeners.indexOf(callback as HdrChangeCallback)
+      if (i >= 0) hdrListeners.splice(i, 1)
+      if (hdrListeners.length === 0 && hdrPollTimer !== undefined) {
+        clearInterval(hdrPollTimer)
+        hdrPollTimer = undefined
+      }
+      return
+    }
     if (channel !== "resize") return
     const i = resizeListeners.indexOf(callback as ResizeCallback)
     if (i >= 0) resizeListeners.splice(i, 1)