lecodes-sdk 0.19.0

package/README.md

@@ -0,0 +1,114 @@
+# sdk — the unified, import-free scripting API
+
+One coherent, **import-free** syntax for le.codes projects across **2D** (creator-2d), **3D**
+(creator-gl), **UI** (creator-ui), and the platform runtime. The whole library is delivered through
+esbuild's `inject()`, so user code uses globals (`Scene`, `Sprite`, `Mesh`, `UIScreen`, `setLoop`, …)
+with **no imports**; tree-shaking drops whatever a project doesn't use.
+
+Replaces the `worker` package. See [PLAN.md](./PLAN.md) for the full design and build log.
+
+**API reference:** the complete, curated docs live in [docs/](./docs/index.md) — every global, every
+method, example-first. Run `bun run docs:check` to verify coverage + links.
+
+```ts
+// 2D — no imports
+const scene = new Scene2D({ background: '#10131a' })
+const player = new Sprite({ texture: await Texture2D.load(asset('hero.png')), anchor: [0.5, 1] })
+  .clips({ size: [32, 48], idle: [0, 1, 2, 3], walk: [4, 5, 6, 7] })
+player.play('idle')
+scene.add(player); scene.open()
+scene.camera.follow(player, { smooth: 0.15 })
+setLoop(dt => { if (Input.key('ArrowRight')) { player.x += 120 * dt; player.play('walk') } })
+
+// 3D — no imports
+const world = new Scene({ bloom: true })
+const ball = Mesh.sphere({ radius: 0.5, material: Material.lit({ color: '#e33' }), position: [0, 5, 0] })
+  .physics({ motion: 'dynamic', shape: { type: 'sphere', radius: 0.5 } })
+world.add(ball, Light.sun({ castShadows: true }))
+world.camera.position = [0, 6, 12]; world.camera.lookAt([0, 0, 0])
+world.open()
+setLoop(() => { if (Input.key('Space')) ball.body.applyImpulse([0, 6, 0]) })
+```
+
+## Fluent math (`Vec2` / `Vec3` / `Quat` / `Mat4`)
+
+Per-frame math reads like the formula — no imports, no out-params. Vectors are *mutable structs with
+pure methods*: fields are settable (`v.x = 3`, `v.set(…)`), but every method returns a NEW value and
+never mutates its source. They're iterable and accept raw tuples anywhere, so `[0, 1, 0]` works wherever
+a vector does.
+
+```ts
+const dir  = target.position.sub(self.position).normalize()
+self.position = self.position.add(dir.scale(speed * dt))
+if (a.distanceTo(b) < 2) explode()
+node.quaternion = node.quaternion.mul(Quat.fromAxisAngle(Vec3.up, turn))
+
+// the node API returns fresh copies (value semantics, like Unity):
+node.x = 3                                   // loud single-axis nudge
+const p = node.position; p.y = 5; node.position = p   // local-mutate, then assign back
+// node.position.x = 3  ← a no-op (mutates a discarded copy); use node.x instead
+
+// Mat4 keeps the metal exposed (public .m) for low-level surgery:
+let m = node.matrix.translate(pivot).rotateY(yaw * dt).translate(pivot.negate())
+m.m[12] += vx * dt
+node.matrix = m
+```
+
+`Quat`/`Mat4` cover the rest: `Quat.fromEuler/lookRotation/slerp`, `Mat4.compose/decompose/lookAt/
+perspective`. All of it is fuzz-tested against gl-matrix (dev-only oracle) in `tests/math.oracle.test.ts`.
+
+## Design rules
+
+- **No ECS / no components.** Built-in behaviors are chainable node methods (`.physics()`,
+  `.collider()`, `.clips()/.play()`); reuse is a factory function. Per-frame logic is `setLoop(dt => …)`.
+- **Few globals.** Variants are static factory methods (`Mesh.box()`, `Material.lit()`,
+  `Texture2D.load()`), not free functions.
+- **Pure re-skin.** Calls the existing `_creator` / `_creator2d` / `_creatorUI` / `_creatorUtils`
+  host bridges — no native engine changes.
+
+## Layout
+
+```
+src/
+  inject.ts         # THE aggregation point — the only file that exports public globals
+  bridges.d.ts      # ambient host ABI (_creator*, declared, never bundled)
+  host.d.ts         # ambient host runtime globals (setLoop, console, DEG2RAD, asset)
+  core/             # handle registry, color, event Emitter
+  math/             # Mathf (scalar) + fluent Vec2/Vec3 (vec), Quat (quat), Mat4 (mat4) — no gl-matrix shipped
+  runtime/          # fetch, storage, device, input, media, net, files, touch, misc
+  g2/               # 2D: Scene2D, Node2D, Sprite, Tilemap, Texture2D, Camera2D
+  gl/               # 3D: Scene, ARScene, Node, Mesh, Light, Material, Geometry, Texture,
+                    #     Camera, Ray, Plane, Noise, Particles
+  ui/               # UIScreen/Row/Column/Text/Button/… + Router + registerFont
+  animate/          # animate, cubicBezier, easings
+  plugins/          # optional, host-provided capabilities (QRScanner, CameraView) — gated on host support
+  compile/          # the user-project compiler (bundler + header + compileProject) — backend/CLI use it
+```
+
+## Build & test
+
+```sh
+bun run build       # → dist/inject.js (runtime), dist/global.d.ts + host.d.ts + types.json (editor types)
+bun test            # compile/parity + math/color + 2D + 3D-runtime + UI tests
+bun run typecheck   # tsc --noEmit
+```
+
+`tests/headless/` holds live WebGL2 render harnesses (manual; need chrome-headless-shell). The 2D
+harness is green: a project compiled through the real `compileProject` renders correct pixels.
+
+## How it integrates
+
+The backend (`backend/src/utils/compileProject.ts`) and CLI (`lecodes-cli`) compile **every** user
+project through this SDK (`sdk/compile`) — the legacy `worker` path was removed from user-project
+compilation. A bare `import` from a runtime module (`creator`/`ui`/`animate`/`utils`/`2d`) is no longer
+special-cased; it's just an unresolved import, so the build fails loudly and points at the file. The
+`worker` package still exists for internal tooling (scene-viewer / model-preview), not for user code.
+
+## Deferred (API present, native pending)
+
+- 2D physics / collider triggers (`.collider()` is a no-op stub; `Node2D.add()` hierarchy).
+- Live 2D↔3D engine switching is wired in the viewer host (two canvases) but pending a real dual
+  project to verify.
+
+`ARScene.addControls(target, options?)` ports the AR object-placement gesture recipe (one-finger drag,
+two-finger pinch-scale + twist-rotate) onto the fluent math; returns a `{ remove() }` handle.

package/dist/global.d.ts

@@ -0,0 +1,503 @@
+// AUTO-GENERATED by build-types.ts. The import-free type surface for le.codes projects:
+// every SDK global declared ambiently, so user code uses Scene / Sprite / UIScreen / … 
+// with no imports and full editor autocomplete.
+
+import type * as SDK from "./types/inject"
+import type * as SERVER from "./types/server/inject"
+
+declare global {
+  const ARScene: typeof SDK.ARScene
+  const AnimationClip: typeof SDK.AnimationClip
+  const Animator: typeof SDK.Animator
+  const Aspect: typeof SDK.Aspect
+  const AudioPlayer: typeof SDK.AudioPlayer
+  const Autotile2D: typeof SDK.Autotile2D
+  const Bitmap: typeof SDK.Bitmap
+  const Camera: typeof SDK.Camera
+  const Camera2D: typeof SDK.Camera2D
+  const CameraFollow: typeof SDK.CameraFollow
+  const CameraPlace: typeof SDK.CameraPlace
+  const CameraView: typeof SDK.CameraView
+  const Canvas: typeof SDK.Canvas
+  const CharacterController: typeof SDK.CharacterController
+  const CharacterController2D: typeof SDK.CharacterController2D
+  const ClickEvent: typeof SDK.ClickEvent
+  const Color: typeof SDK.Color
+  const DateValue: typeof SDK.DateValue
+  const File: typeof SDK.File
+  const FollowPath: typeof SDK.FollowPath
+  const FormData: typeof SDK.FormData
+  const Gearbox: typeof SDK.Gearbox
+  const Geolocation: typeof SDK.Geolocation
+  const Geometry: typeof SDK.Geometry
+  const Gizmos: typeof SDK.Gizmos
+  const IK: typeof SDK.IK
+  const Input: typeof SDK.Input
+  const InputChannel: typeof SDK.InputChannel
+  const InspectorUI: typeof SDK.InspectorUI
+  const InstancedMesh: typeof SDK.InstancedMesh
+  const Layer: typeof SDK.Layer
+  const Level: typeof SDK.Level
+  const Light: typeof SDK.Light
+  const Lightmap: typeof SDK.Lightmap
+  const Locomotion: typeof SDK.Locomotion
+  const LongPressEvent: typeof SDK.LongPressEvent
+  const LookAt: typeof SDK.LookAt
+  const Loop: typeof SDK.Loop
+  const Mat4: typeof SDK.Mat4
+  const Material: typeof SDK.Material
+  const MaterialHandle: typeof SDK.MaterialHandle
+  const Mathf: typeof SDK.Mathf
+  const Mesh: typeof SDK.Mesh
+  const Model: typeof SDK.Model
+  const MoveTo: typeof SDK.MoveTo
+  const NativeView: typeof SDK.NativeView
+  const NavAgent: typeof SDK.NavAgent
+  const NavCrowd: typeof SDK.NavCrowd
+  const NavMesh: typeof SDK.NavMesh
+  const Net: typeof SDK.Net
+  const NetEntity: typeof SDK.NetEntity
+  const NetPlayer: typeof SDK.NetPlayer
+  const Node: typeof SDK.Node
+  const Node2D: typeof SDK.Node2D
+  const Noise: typeof SDK.Noise
+  const OAuth: typeof SDK.OAuth
+  const OneWay2D: typeof SDK.OneWay2D
+  const Particles: typeof SDK.Particles
+  const Physics: typeof SDK.Physics
+  const Physics2D: typeof SDK.Physics2D
+  const PhysicsGroup2D: typeof SDK.PhysicsGroup2D
+  const Plane: typeof SDK.Plane
+  const PlayAnimation: typeof SDK.PlayAnimation
+  const Playback: typeof SDK.Playback
+  const Presentable: typeof SDK.Presentable
+  const Push: typeof SDK.Push
+  const QRScanner: typeof SDK.QRScanner
+  const Quat: typeof SDK.Quat
+  const Ragdoll: typeof SDK.Ragdoll
+  const Ray: typeof SDK.Ray
+  const Replicated: typeof SDK.Replicated
+  const Router: typeof SDK.Router
+  const RpcError: typeof SDK.RpcError
+  const Scene: typeof SDK.Scene
+  const Scene2D: typeof SDK.Scene2D
+  const Scene2dHandle: typeof SDK.Scene2dHandle
+  const SceneHandle: typeof SDK.SceneHandle
+  const Service: typeof SDK.Service
+  const Shape: typeof SDK.Shape
+  const Shape2D: typeof SDK.Shape2D
+  const Spin: typeof SDK.Spin
+  const Sprite: typeof SDK.Sprite
+  const SpriteAnimation: typeof SDK.SpriteAnimation
+  const SpriteSheet: typeof SDK.SpriteSheet
+  const StateMachine: typeof SDK.StateMachine
+  const SvgSource: typeof SDK.SvgSource
+  const System: typeof SDK.System
+  const Terrain: typeof SDK.Terrain
+  const Texture: typeof SDK.Texture
+  const Texture2D: typeof SDK.Texture2D
+  const Tilemap: typeof SDK.Tilemap
+  const Tileset: typeof SDK.Tileset
+  const Time: typeof SDK.Time
+  const TouchStartEvent: typeof SDK.TouchStartEvent
+  const Trail: typeof SDK.Trail
+  const Trigger: typeof SDK.Trigger
+  const Trigger2D: typeof SDK.Trigger2D
+  const UIBottomSheet: typeof SDK.UIBottomSheet
+  const UIBox: typeof SDK.UIBox
+  const UIButton: typeof SDK.UIButton
+  const UIColumn: typeof SDK.UIColumn
+  const UIImage: typeof SDK.UIImage
+  const UIInput: typeof SDK.UIInput
+  const UIModal: typeof SDK.UIModal
+  const UIPager: typeof SDK.UIPager
+  const UIPopover: typeof SDK.UIPopover
+  const UIRow: typeof SDK.UIRow
+  const UIScreen: typeof SDK.UIScreen
+  const UIScrollable: typeof SDK.UIScrollable
+  const UISpacer: typeof SDK.UISpacer
+  const UITabs: typeof SDK.UITabs
+  const UIText: typeof SDK.UIText
+  const UITextArea: typeof SDK.UITextArea
+  const UIVideo: typeof SDK.UIVideo
+  const UIVirtualizedList: typeof SDK.UIVirtualizedList
+  const UIWidget: typeof SDK.UIWidget
+  const VRScene: typeof SDK.VRScene
+  const Vec2: typeof SDK.Vec2
+  const Vec3: typeof SDK.Vec3
+  const Vehicle: typeof SDK.Vehicle
+  const VideoPlayer: typeof SDK.VideoPlayer
+  const WebSocket: typeof SDK.WebSocket
+  const Wheel: typeof SDK.Wheel
+  const __GizmoBuffer: typeof SDK.__GizmoBuffer
+  const __UIBox: typeof SDK.__UIBox
+  const __UIButton: typeof SDK.__UIButton
+  const __UIColumn: typeof SDK.__UIColumn
+  const __UIRow: typeof SDK.__UIRow
+  const __UIScreen: typeof SDK.__UIScreen
+  const __UIScrollable: typeof SDK.__UIScrollable
+  const __UIWidget: typeof SDK.__UIWidget
+  const __applyEditorPose: typeof SDK.__applyEditorPose
+  const __applyMaterialParam: typeof SDK.__applyMaterialParam
+  const __assignMaterialDef: typeof SDK.__assignMaterialDef
+  const __channel: typeof SDK.__channel
+  const __compOp: typeof SDK.__compOp
+  const __compWrite: typeof SDK.__compWrite
+  const __editorPlugins: typeof SDK.__editorPlugins
+  const __rpc: typeof SDK.__rpc
+  const __serverOnly: typeof SDK.__serverOnly
+  const __uiMap: typeof SDK.__uiMap
+  const __withGizmoScope: typeof SDK.__withGizmoScope
+  const animate: typeof SDK.animate
+  const animateMat4: typeof SDK.animateMat4
+  const app: typeof SDK.app
+  const cells: typeof SDK.cells
+  const clipboard: typeof SDK.clipboard
+  const colorCurve: typeof SDK.colorCurve
+  const computed: typeof SDK.computed
+  const cubicBezier: typeof SDK.cubicBezier
+  const curve: typeof SDK.curve
+  const date: typeof SDK.date
+  const defineMaterial: typeof SDK.defineMaterial
+  const defineScene: typeof SDK.defineScene
+  const defineScene2d: typeof SDK.defineScene2d
+  const defineSpriteSheet: typeof SDK.defineSpriteSheet
+  const defineStates: typeof SDK.defineStates
+  const defineTabs: typeof SDK.defineTabs
+  const defineTileset: typeof SDK.defineTileset
+  const device: typeof SDK.device
+  const easeIn: typeof SDK.easeIn
+  const easeInOut: typeof SDK.easeInOut
+  const easeOut: typeof SDK.easeOut
+  const effect: typeof SDK.effect
+  const encodeCells: typeof SDK.encodeCells
+  const fetch: typeof SDK.fetch
+  const fetchLocal: typeof SDK.fetchLocal
+  const files: typeof SDK.files
+  const flipX: typeof SDK.flipX
+  const isRawCell: typeof SDK.isRawCell
+  const localStorage: typeof SDK.localStorage
+  const make: typeof SDK.make
+  const openFilePicker: typeof SDK.openFilePicker
+  const openURL: typeof SDK.openURL
+  const packTile: typeof SDK.packTile
+  const pauseAnimation: typeof SDK.pauseAnimation
+  const rawCell: typeof SDK.rawCell
+  const rawIndex: typeof SDK.rawIndex
+  const ref: typeof SDK.ref
+  const registerEditorTool: typeof SDK.registerEditorTool
+  const registerEditorWindow: typeof SDK.registerEditorWindow
+  const registerFont: typeof SDK.registerFont
+  const resumeAnimation: typeof SDK.resumeAnimation
+  const rot180: typeof SDK.rot180
+  const rot270: typeof SDK.rot270
+  const rot90: typeof SDK.rot90
+  const share: typeof SDK.share
+  const signal: typeof SDK.signal
+  const stopAnimation: typeof SDK.stopAnimation
+  const theme: typeof SDK.theme
+  const tileFlip: typeof SDK.tileFlip
+  const tileIndex: typeof SDK.tileIndex
+  const tileOriented: typeof SDK.tileOriented
+  const tileTurns: typeof SDK.tileTurns
+  const toast: typeof SDK.toast
+  const use: typeof SDK.use
+  type ARScene<T extends ARMode = "default"> = SDK.ARScene<T>
+  type ActiveClip = SDK.ActiveClip
+  type AeroConfig = SDK.AeroConfig
+  type AnimationClip = SDK.AnimationClip
+  type Animator = SDK.Animator
+  type AppState = SDK.AppState
+  type Aspect<K extends string, P = Node, E extends EventMap = {}> = SDK.Aspect<K, P, E>
+  type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = SDK.AspectEntry<A>
+  type AudioPlayer = SDK.AudioPlayer
+  type AutoPaintRules = SDK.AutoPaintRules
+  type Autotile2D = SDK.Autotile2D
+  type Bitmap = SDK.Bitmap
+  type BlendPosition = SDK.BlendPosition
+  type BlockEntry = SDK.BlockEntry
+  type Camera = SDK.Camera
+  type Camera2D = SDK.Camera2D
+  type Camera2dNodeDef = SDK.Camera2dNodeDef
+  type CameraFacing = SDK.CameraFacing
+  type CameraFollow = SDK.CameraFollow
+  type CameraNodeDef = SDK.CameraNodeDef
+  type CameraPlace = SDK.CameraPlace
+  type CameraView = SDK.CameraView
+  type Canvas = SDK.Canvas
+  type CellsData = SDK.CellsData
+  type CharacterController = SDK.CharacterController
+  type CharacterController2D = SDK.CharacterController2D
+  type ClickEvent<T = any> = SDK.ClickEvent<T>
+  type ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> = SDK.ClientChannel<E>
+  type ClipDef = SDK.ClipDef
+  type ClipKey<V> = SDK.ClipKey<V>
+  type ClipTrackDef = SDK.ClipTrackDef
+  type CompAxis = SDK.CompAxis
+  type CompWriter = SDK.CompWriter
+  type Computed<T> = SDK.Computed<T>
+  type ConformOptions = SDK.ConformOptions
+  type DateInput = SDK.DateInput
+  type DateValue = SDK.DateValue
+  type DifferentialMode = SDK.DifferentialMode
+  type Displacement = SDK.Displacement
+  type DriveLayout = SDK.DriveLayout
+  type EdgeSlot = SDK.EdgeSlot
+  type EditorApi = SDK.EditorApi
+  type EditorRayHit = SDK.EditorRayHit
+  type EditorToolHooks = SDK.EditorToolHooks
+  type EditorWindowFn = SDK.EditorWindowFn
+  type EngineConfig = SDK.EngineConfig
+  type EventMap = SDK.EventMap
+  type FeetOptions = SDK.FeetOptions
+  type FetchResponse = SDK.FetchResponse
+  type FieldMeta<T = unknown> = SDK.FieldMeta<T>
+  type File = SDK.File
+  type FileData = SDK.FileData
+  type FillBlock = SDK.FillBlock
+  type FollowPath = SDK.FollowPath
+  type FootState = SDK.FootState
+  type FormData = SDK.FormData
+  type Gait = SDK.Gait
+  type GamepadAxisName = SDK.GamepadAxisName
+  type GamepadState = SDK.GamepadState
+  type Gearbox = SDK.Gearbox
+  type GeoOptions = SDK.GeoOptions
+  type GeoPosition = SDK.GeoPosition
+  type GeoWatch = SDK.GeoWatch
+  type Geometry = SDK.Geometry
+  type GizmoAnchor = SDK.GizmoAnchor
+  type GizmoStyle = SDK.GizmoStyle
+  type HapticStyle = SDK.HapticStyle
+  type IKLookAt = SDK.IKLookAt
+  type IKTwoBone = SDK.IKTwoBone
+  type InputEventName = SDK.InputEventName
+  type InputGamepadEvent = SDK.InputGamepadEvent
+  type InputKeyEvent = SDK.InputKeyEvent
+  type InspectorUI = SDK.InspectorUI
+  type InstanceTransform = SDK.InstanceTransform
+  type InstancedMesh = SDK.InstancedMesh
+  type Layer = SDK.Layer
+  type LayerOptions = SDK.LayerOptions
+  type LevelBuild = SDK.LevelBuild
+  type LevelCollider = SDK.LevelCollider
+  type LevelGridOptions = SDK.LevelGridOptions
+  type LevelLineOptions = SDK.LevelLineOptions
+  type LevelPlaceOptions = SDK.LevelPlaceOptions
+  type LevelRingOptions = SDK.LevelRingOptions
+  type LevelScatterOptions = SDK.LevelScatterOptions
+  type LevelSpot = SDK.LevelSpot
+  type Light = SDK.Light
+  type LightDef = SDK.LightDef
+  type Lightmap = SDK.Lightmap
+  type LitMaterialDef = SDK.LitMaterialDef
+  type LoadedScene<D extends SceneDef> = SDK.LoadedScene<D>
+  type LoadedScene2d<D extends Scene2dDef> = SDK.LoadedScene2d<D>
+  type Locale = SDK.Locale
+  type Locomotion = SDK.Locomotion
+  type LocomotionClip = SDK.LocomotionClip
+  type LocomotionEvents = SDK.LocomotionEvents
+  type LocomotionSet = SDK.LocomotionSet
+  type LocomotionState = SDK.LocomotionState
+  type LocomotionTuning = SDK.LocomotionTuning
+  type LongPressEvent<T = any> = SDK.LongPressEvent<T>
+  type LookAt = SDK.LookAt
+  type Loop = SDK.Loop
+  type LoopDef = SDK.LoopDef
+  type LoopOptions = SDK.LoopOptions
+  type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>> = SDK.MakeEntry<A>
+  type Mat4 = SDK.Mat4
+  type Material = SDK.Material
+  type MaterialData = SDK.MaterialData
+  type MaterialDef = SDK.MaterialDef
+  type MaterialHandle = SDK.MaterialHandle
+  type MaterialParamValue = SDK.MaterialParamValue
+  type Mesh = SDK.Mesh
+  type MeshDef = SDK.MeshDef
+  type Model = SDK.Model
+  type MotionOptions = SDK.MotionOptions
+  type MoveTo = SDK.MoveTo
+  type NativeView = SDK.NativeView
+  type NavAgent = SDK.NavAgent
+  type NavAgentAvoidance = SDK.NavAgentAvoidance
+  type NavAgentDrive = SDK.NavAgentDrive
+  type NavAgentEvents = SDK.NavAgentEvents
+  type NavAgentSize = SDK.NavAgentSize
+  type NavAgentState = SDK.NavAgentState
+  type NavCrowd = SDK.NavCrowd
+  type NavMesh = SDK.NavMesh
+  type NavMeshInfo = SDK.NavMeshInfo
+  type NavMeshLoadOptions = SDK.NavMeshLoadOptions
+  type NavPath = SDK.NavPath
+  type NavQueryOptions = SDK.NavQueryOptions
+  type NavRaycastHit = SDK.NavRaycastHit
+  type NetEntity<S extends object = any> = SDK.NetEntity<S>
+  type NetEvents = SDK.NetEvents
+  type NetInput<T extends object = any> = SDK.NetInput<T>
+  type NetKind<S extends object = any> = SDK.NetKind<S>
+  type NetLaunch = SDK.NetLaunch
+  type NetMessage<T = unknown> = SDK.NetMessage<T>
+  type NetPlayer = SDK.NetPlayer
+  type NetRole = SDK.NetRole
+  type NetStatus = SDK.NetStatus
+  type NetTransform = SDK.NetTransform
+  type Node = SDK.Node
+  type Node2D = SDK.Node2D
+  type Noise = SDK.Noise
+  type OAuthCredential = SDK.OAuthCredential
+  type OAuthProviderName = SDK.OAuthProviderName
+  type OneWay2D = SDK.OneWay2D
+  type OrientationLock = SDK.OrientationLock
+  type Particles = SDK.Particles
+  type PatchMaterial = SDK.PatchMaterial
+  type PatchSlots = SDK.PatchSlots
+  type PathMaterial = SDK.PathMaterial
+  type Physics = SDK.Physics
+  type Physics2D = SDK.Physics2D
+  type PhysicsGroup2D = SDK.PhysicsGroup2D
+  type Plane = SDK.Plane
+  type PlayAnimation = SDK.PlayAnimation
+  type PlayOptions = SDK.PlayOptions
+  type Playback = SDK.Playback
+  type PresentOptions = SDK.PresentOptions
+  type Presentable = SDK.Presentable
+  type PushEvent = SDK.PushEvent
+  type PushPayload = SDK.PushPayload
+  type PushRegisterOptions = SDK.PushRegisterOptions
+  type PushStatus = SDK.PushStatus
+  type QRScanner = SDK.QRScanner
+  type Quat = SDK.Quat
+  type Ragdoll = SDK.Ragdoll
+  type RagdollHinge = SDK.RagdollHinge
+  type RagdollPart = SDK.RagdollPart
+  type Ray = SDK.Ray
+  type Replicated = SDK.Replicated
+  type RibbonOptions = SDK.RibbonOptions
+  type RpcError = SDK.RpcError
+  type Scene = SDK.Scene
+  type Scene2D = SDK.Scene2D
+  type Scene2dDef = SDK.Scene2dDef
+  type Scene2dEnv = SDK.Scene2dEnv
+  type Scene2dHandle<D extends Scene2dDef = Scene2dDef> = SDK.Scene2dHandle<D>
+  type Scene2dNodeDef = SDK.Scene2dNodeDef
+  type SceneDef = SDK.SceneDef
+  type SceneHandle<D extends SceneDef = SceneDef> = SDK.SceneHandle<D>
+  type SceneInstance<D extends SceneDef> = SDK.SceneInstance<D>
+  type SceneNodeDef = SDK.SceneNodeDef
+  type SculptOptions = SDK.SculptOptions
+  type Service = SDK.Service
+  type ShaderMaterialDef = SDK.ShaderMaterialDef
+  type Shape = SDK.Shape
+  type Shape2D = SDK.Shape2D
+  type SheetSprite = SDK.SheetSprite
+  type Signal<T> = SDK.Signal<T>
+  type Spin = SDK.Spin
+  type Sprite = SDK.Sprite
+  type SpriteAnimation = SDK.SpriteAnimation
+  type SpriteMakeOptions = SDK.SpriteMakeOptions
+  type SpriteSheet = SDK.SpriteSheet
+  type SpriteSheetDef = SDK.SpriteSheetDef
+  type SpriteSourceDef = SDK.SpriteSourceDef
+  type StateDef<C> = SDK.StateDef<C>
+  type StateGuard<C> = SDK.StateGuard<C>
+  type StateHandler<C> = SDK.StateHandler<C>
+  type StateMachine<C> = SDK.StateMachine<C>
+  type StateMachineEvents = SDK.StateMachineEvents
+  type StatesDef<C> = SDK.StatesDef<C>
+  type SteeringConfig = SDK.SteeringConfig
+  type StopOptions = SDK.StopOptions
+  type System<K extends string, S extends SystemHost = Scene, E extends EventMap = {}> = SDK.System<K, S, E>
+  type SystemHost = SDK.SystemHost
+  type TabDef = SDK.TabDef
+  type TabsHandle<T extends Record<string, TabDef>> = SDK.TabsHandle<T>
+  type Terrain = SDK.Terrain
+  type TerrainHit = SDK.TerrainHit
+  type TerrainLayer = SDK.TerrainLayer
+  type TerrainOptions = SDK.TerrainOptions
+  type TerrainRegion = SDK.TerrainRegion
+  type TerrainSnapshot = SDK.TerrainSnapshot
+  type Texture = SDK.Texture
+  type Texture2D = SDK.Texture2D
+  type ThemeAccessors<T> = SDK.ThemeAccessors<T>
+  type ThemeValues = SDK.ThemeValues
+  type TileBlock = SDK.TileBlock
+  type TileMaterial = SDK.TileMaterial
+  type TilePart = SDK.TilePart
+  type Tilemap = SDK.Tilemap
+  type TilemapSourceDef = SDK.TilemapSourceDef
+  type Tileset = SDK.Tileset
+  type TilesetDef = SDK.TilesetDef
+  type TireCurve = SDK.TireCurve
+  type TouchStartEvent<T = any> = SDK.TouchStartEvent<T>
+  type Trail = SDK.Trail
+  type Transition = SDK.Transition
+  type TransitionName = SDK.TransitionName
+  type TransitionSpec = SDK.TransitionSpec
+  type TransitionTransform = SDK.TransitionTransform
+  type Trigger = SDK.Trigger
+  type Trigger2D = SDK.Trigger2D
+  type UIBottomSheet = SDK.UIBottomSheet
+  type UIBottomSheetStyle = SDK.UIBottomSheetStyle
+  type UIBox = SDK.UIBox
+  type UIButton = SDK.UIButton
+  type UIButtonStyle = SDK.UIButtonStyle
+  type UIColumn = SDK.UIColumn
+  type UIContainerStyle = SDK.UIContainerStyle
+  type UIImage = SDK.UIImage
+  type UIImageStyle = SDK.UIImageStyle
+  type UIInput = SDK.UIInput
+  type UIInputStyle = SDK.UIInputStyle
+  type UIModal = SDK.UIModal
+  type UIModalStyle = SDK.UIModalStyle
+  type UINativeViewStyle = SDK.UINativeViewStyle
+  type UINode = SDK.UINode
+  type UINodeChild = SDK.UINodeChild
+  type UIPager = SDK.UIPager
+  type UIPagerStyle = SDK.UIPagerStyle
+  type UIPopover = SDK.UIPopover
+  type UIPopoverStyle = SDK.UIPopoverStyle
+  type UIRow = SDK.UIRow
+  type UIScreen = SDK.UIScreen
+  type UIScreenStyle = SDK.UIScreenStyle
+  type UIScrollable = SDK.UIScrollable
+  type UIScrollableStyle = SDK.UIScrollableStyle
+  type UISpacer = SDK.UISpacer
+  type UISpacerStyle = SDK.UISpacerStyle
+  type UITabDef = SDK.UITabDef
+  type UITabs = SDK.UITabs
+  type UIText = SDK.UIText
+  type UITextArea = SDK.UITextArea
+  type UITextStyle = SDK.UITextStyle
+  type UIVideo = SDK.UIVideo
+  type UIVideoStyle = SDK.UIVideoStyle
+  type UIVirtualizedList<T = unknown> = SDK.UIVirtualizedList<T>
+  type UIWidget = SDK.UIWidget
+  type UIWidgetStyle = SDK.UIWidgetStyle
+  type Unit = SDK.Unit
+  type UnlitMaterialDef = SDK.UnlitMaterialDef
+  type VRScene = SDK.VRScene
+  type Vec2 = SDK.Vec2
+  type Vec3 = SDK.Vec3
+  type Vehicle = SDK.Vehicle
+  type VideoPlayer = SDK.VideoPlayer
+  type WarpOptions = SDK.WarpOptions
+  type WebSocket = SDK.WebSocket
+  type Wheel = SDK.Wheel
+  type WheelSuspension = SDK.WheelSuspension
+  type WheelTire = SDK.WheelTire
+  type WheelVisual = SDK.WheelVisual
+  type With<N, A extends Aspect<any, any, any>> = SDK.With<N, A>
+  type __GizmoBuffer = SDK.__GizmoBuffer
+  // ---- server globals (available in *.server.ts; using them in client code is a build error) ----
+  const ApiError: typeof SERVER.ApiError
+  const auth: typeof SERVER.auth
+  const channel: typeof SERVER.channel
+  const defineDb: typeof SERVER.defineDb
+  const model: typeof SERVER.model
+  const ref: typeof SERVER.ref
+  const request: typeof SERVER.request
+  const t: typeof SERVER.t
+  type ApiError = SERVER.ApiError
+}
+
+export {}

package/dist/host.d.ts

@@ -0,0 +1,61 @@
+// JS-runtime globals provided by the host engine (web viewer / desktop / iOS), NOT by the SDK.
+// Declared only so SDK and user code type-check — never bundled or injected. Mirrors
+// packages/projects/src/global.d.ts.
+
+declare global {
+  function setTimeout(handler: (...args: any[]) => void, timeout?: number): number
+  function setInterval(handler: (...args: any[]) => void, timeout?: number): number
+  function clearTimeout(id: number): void
+  function clearInterval(id: number): void
+  /** Per-frame loop, driven by the host (viewer RAF / desktop runTick). `dt` is **seconds** since
+   *  the previous frame. */
+  function setLoop(handler: (dt: number) => void): number
+  function clearLoop(id: number): void
+
+  /** π/180 — substituted at compile time (bundler `define`). */
+  var DEG2RAD: number
+  /** 180/π — substituted at compile time (bundler `define`). */
+  var RAD2DEG: number
+
+  /** Compile-time boolean: `true` in scene-editor bundles, `false` (const-folded + DCE'd) in
+   *  shipped ones — `if (EDITOR) { … }` costs zero bytes in production. `*.editor.ts` files are
+   *  the file-level form. */
+  var EDITOR: boolean
+
+  var console: {
+    log(...data: any[]): void
+    warn(...data: any[]): void
+    info(...data: any[]): void
+    error(...data: any[]): void
+  }
+
+  /** Compile-time macro: `asset('./hero.png')` is desugared by the bundler into the module import
+   *  for that resource. The file must exist — a path that resolves to nothing fails the compile
+   *  (`asset not found: ./hero.png (main.ts:3)`); there is no runtime fallback. Calls inside
+   *  comments and string literals are text, not macros. */
+  function asset(path: string): string
+
+  /** Compile-time macro: installs a font and returns its family name — using a font IS declaring
+   *  it. A registry id (`font("manrope")`) resolves against the font registry; a project path
+   *  (`font("./fonts/Brand.ttf")`) reads family/weight/italic from the file itself. `opts`
+   *  narrows/extends the face set (default: the family's standard weights). String-literal
+   *  argument only. No awaiting — faces load with app boot and the host holds first paint for
+   *  them. */
+  function font(id: string, opts?: { weights?: number[], italic?: boolean }): string
+
+  /** Compile-time macro: resolves one icon from the icon registry at build time and inlines it as
+   *  an image source for `UIImage(...)` — offline, identical on every host. `id` is `"pack:name"`
+   *  (e.g. `"lucide:bell"`), string literal only. Recolor via `{ color }`: a hex LITERAL is baked
+   *  into the SVG at compile time, a token/expression is applied as a tint (as is the `tintColor`
+   *  style prop). */
+  function assetIcon(id: string, opts?: { color?: string }): { readonly svg: string, tintColor: string | null }
+
+  /** Type-only editor convenience: the style object type of a UI element. `Style<UIButton>` (or
+   *  `Style<typeof myButton>`) is what you'd pass to `el.style(...)` — for typing reusable style
+   *  presets. Deliberately no `Partial<>` wrapper: every style prop is already optional, and
+   *  Partial over ClassStyles' `$`-index signature adds `| undefined`, breaking assignability back
+   *  into `.style(...)`. Round-trip guarded by sdk/tests/ui-types.test.ts. */
+  type Style<T> = T extends { style: (s: infer S) => any } ? S : never
+}
+
+export {}