lecodes-sdk 2.0.9 → 2.0.11

package/src/gl/Light.ts

@@ -1,270 +1,257 @@
-// Lights. A directional sun (the engine's primary light), punctual point lights and spot lights. Add one to a
-// scene like any node; `intensity` and `color` stay writable so a light can be animated.
-
-import { Color, type ColorInput } from "../core/color"
-import type { Vec3Like } from "../math/vec"
-import { Node, type NodeTweenProps } from "./Node"
-import { DOM_GL_LIGHT, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
-import type { Animation } from "../animate/tween/Animation"
-
-/** Animatable light props on top of the node transform. */
-export type LightTweenProps = NodeTweenProps & {
-  intensity?: number | number[],
-  color?: ColorInput | ColorInput[],
-}
-
-export type SunOptions = {
-  /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
-  direction?: Vec3Like
-  /** Luminous intensity. */
-  intensity?: number
-  color?: ColorInput
-  /**
-   * Shadow quality (default 1):
-   *   0 - no shadows
-   *   1 - 1024 map, hard edges (one filtered tap; the cheap level, ~3 % of a frame on an iGPU)
-   *   2 - 1024 map, soft edges (variance shadows + blur; ~+15 % of a frame on an iGPU)
-   *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
-   *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
-   * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
-   * On a level with a baked light grid the variance / PCSS filters cannot be used (they need every
-   * receiver in the shadow map, and the baked statics are kept out of it): 3 renders as PCSS on the
-   * depth map - the same contact-hardening look - and 2 renders as 1.
-   */
-  shadowsQuality?: 0 | 1 | 2 | 3
-  /**
-   * Metres from the camera within which the sun casts shadows (default 100). Shadows fade out by
-   * this distance and the shadow map covers only this range, so a shorter distance is crisper for
-   * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
-   */
-  shadowDistance?: number
-  /**
-   * How many shadow-map cascades split `shadowDistance` (default 1). One map over the whole range gives a tall
-   * tree 5-10 cm shadow texels on its own trunk; 3 cascades put a tight map on the first metres and coarser
-   * ones behind, fit to their texel grids so the shadow does not swim as the camera moves. Each cascade is
-   * another caster pass, so it costs in proportion to what casts: forests, not a lightmapped level.
-   */
-  shadowCascades?: 1 | 2 | 3 | 4
-}
-
-export type PointOptions = {
-  /**
-   * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
-   * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
-   * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
-   */
-  intensity?: number
-  color?: ColorInput
-  /**
-   * Metres of influence — past it the light contributes nothing. This is the performance knob:
-   * overlapping point lights are the expensive case, so keep it as small as the look allows.
-   * Default 10.
-   */
-  range?: number
-  /** Point-light shadows are a cubemap render per light; off by default. */
-  castShadows?: boolean
-  /**
-   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap. A baked lamp lights the statics
-   * from the atlas and the MOVERS from the level's light grid, and is held dark in real time while that grid is
-   * loaded (without a grid it keeps lighting the movers live); a light
-   * that must reach the statics live too — a flicker, a lamp the player can shoot out, a muzzle flash —
-   * says `baked: false`: it is kept out of the bake and put on the statics' light channel. Default true.
-   */
-  baked?: boolean
-  /**
-   * THE BAKE'S SHAPE of this lamp: `[width, height]` in metres = an AREA light - a rectangle in the light's local XZ
-   * plane, emitting along its local -Y (down, for an unrotated node) with the same lumens: a ceiling panel. The bake
-   * lights from the whole rectangle (soft shadows, light from where the panel is and not from a point inside the
-   * fixture). Real time it is still the point light above. Ignored with `baked: false`.
-   */
-  bakeArea?: readonly [number, number]
-}
-
-export type SpotOptions = {
-  /**
-   * Luminous power in lumens, as a point light's. The cone does not change the brightness: widen it and the
-   * same lumens light a larger patch at the same level. On its axis a spot is 4x brighter than a point light of
-   * the same lumens (its light is not spread over the whole sphere). Default 1000.
-   */
-  intensity?: number
-  color?: ColorInput
-  /** Metres of influence along the cone, the performance knob as for a point light. Default 10. */
-  range?: number
-  /** The cone's full angle in degrees, up to 180: past it the light contributes nothing. Default 45. */
-  angle?: number
-  /** The full angle in degrees of the cone's fully lit core; the light fades from it out to `angle`. Default 0.75 x `angle`. */
-  innerAngle?: number
-  /** A spot's shadow is one 2D shadow map (a point light's is a cubemap); off by default. */
-  castShadows?: boolean
-}
-
-export class Light extends Node {
-  private _intensity = 0
-
-  /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
-  override animateTo(props: LightTweenProps & TweenMeta): Animation { return super.animateTo(props) }
-  override animateFrom(props: LightTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
-  /** @internal */
-  override _tweenChannel(prop: string): TweenChannel | null {
-    const id = () => this.id
-    if (prop === "intensity") return { domain: DOM_GL_LIGHT, id, value: floatValue, commit: (v) => { this._intensity = v as number } }
-    if (prop === "color") return { domain: DOM_GL_LIGHT, id, value: (v) => colorValue(v, Color.toRgba01) }
-    return super._tweenChannel(prop)
-  }
-  /** @internal PointOptions.baked — a candidate for the lightmap bake (default true). */
-  _baked = true
-  /** @internal every live point light, for the bake / the switch-off; a destroyed one leaves. */
-  static _points = new Set<Light>()
-  /** @internal sun direction as created (the engine keeps it). */
-  _direction: [number, number, number] = [ 0, -1, 0 ]
-  /** The most recently created sun. */
-  static lastSun: Light | null = null
-  /** @internal the colour as created / last set (a settings menu recreates a sun from these). */
-  _color: ColorInput = 0xffffff
-  /** @internal sun shadow options as created (creation-time in the engine). */
-  _shadowsQuality = 1
-  _shadowDistance = 100
-  _shadowCascades = 1
-
-  /** A directional sun light. */
-  static sun(options: SunOptions = {}): Light {
-    const light = new Light()
-    const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
-    light._direction = [ dx, dy, dz ]
-    light._intensity = options.intensity ?? 100000
-    light._color = options.color ?? 0xffffff
-    light._shadowsQuality = options.shadowsQuality ?? 1
-    light._shadowDistance = options.shadowDistance ?? 100
-    light._shadowCascades = options.shadowCascades ?? 1
-    Light.lastSun = light
-    _creator.createSunLight(
-      light.id, dx, dy, dz,
-      light._intensity,
-      Color.toPackedRgb(options.color ?? 0xffffff),
-      options.shadowsQuality ?? 1,
-      options.shadowDistance ?? 100,
-      light._shadowCascades,
-    )
-    return light
-  }
-
-  /**
-   * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
-   *
-   * Feature-detected: hosts that predate it create the node and light nothing, which keeps a scene
-   * that adds atmosphere on top of its sun renderable everywhere. Check `Light.supportsPoint`
-   * before making one carry the scene.
-   */
-  static point(options: PointOptions = {}): Light {
-    const light = new Light()
-    light._intensity = options.intensity ?? 1000
-    light._color = options.color ?? 0xffffff
-    light._baked = options.baked ?? true
-    Light._points.add(light)
-    _creator.createPointLight?.(
-      light.id,
-      light._intensity,
-      Color.toPackedRgb(options.color ?? 0xffffff),
-      options.range ?? 10,
-      options.castShadows ?? false,
-    )
-    if (options.bakeArea && light._baked) _creator.setLightBakeArea?.(light.id, options.bakeArea[0], options.bakeArea[1])
-    // an unbaked lamp lights the baked statics live: Filament channel 1 (see Lightmap)
-    if (!light._baked) _creator.setLightChannel?.(light.id, 1, true)
-    return light
-  }
-
-  /** Whether this host can create point lights at all. */
-  static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
-
-  /** @internal a spot's cone, full angles in degrees (the engine takes half-angles in radians). */
-  _angle = 0
-  _innerAngle = 0
-
-  /**
-   * A spot light — a flashlight, a headlight, a stage light. It shines along the node's forward (-Z): position
-   * it like any node and aim it with `lookAt`. Real time only: the lightmap bake takes no spot lights, so a spot
-   * lights the baked statics live too.
-   *
-   * Feature-detected like `Light.point`: on a host without it the node exists and lights nothing
-   * (`Light.supportsSpot`).
-   */
-  static spot(options: SpotOptions = {}): Light {
-    const light = new Light()
-    light._intensity = options.intensity ?? 1000
-    light._color = options.color ?? 0xffffff
-    light._baked = false
-    light._angle = options.angle ?? 45
-    light._innerAngle = options.innerAngle ?? light._angle * 0.75
-    const [ inner, outer ] = light._cone()
-    _creator.createSpotLight?.(
-      light.id,
-      light._intensity,
-      Color.toPackedRgb(light._color),
-      options.range ?? 10,
-      inner, outer,
-      options.castShadows ?? false,
-    )
-    // the statics of a lightmapped level are on Filament channel 1 alone (see Lightmap)
-    _creator.setLightChannel?.(light.id, 1, true)
-    return light
-  }
-
-  /** Whether this host can create spot lights. */
-  static get supportsSpot(): boolean { return _creator.createSpotLight !== undefined }
-
-  /** @internal the cone as the engine takes it: half-angles in radians, outer in (0, 90°], inner in [0, outer]. */
-  _cone(): [number, number] {
-    const rad = Math.PI / 360
-    const outer = Math.min(Math.max(this._angle, 0.1), 180) * rad
-    const inner = Math.min(Math.max(this._innerAngle, 0), this._angle) * rad
-    return [ Math.min(inner, outer), outer ]
-  }
-
-  /** A spot's full cone angle in degrees — live (a flashlight's focus). */
-  get angle(): number { return this._angle }
-  set angle(value: number) {
-    this._innerAngle *= this._angle > 0 ? value / this._angle : 0
-    this._angle = value
-    _creator.setLightCone?.(this.id, ...this._cone())
-  }
-  /** A spot's fully lit core, full angle in degrees — live. Setting `angle` scales it along. */
-  get innerAngle(): number { return this._innerAngle }
-  set innerAngle(value: number) {
-    this._innerAngle = value
-    _creator.setLightCone?.(this.id, ...this._cone())
-  }
-
-  /** Live intensity (sun: lux, point / spot: lumens) — animate a flash without rebuilding the light. */
-  get intensity(): number { return this._intensity }
-  set intensity(value: number) {
-    this._intensity = value
-    if (!this._heldDark) _creator.setLightIntensity?.(this.id, value)
-  }
-
-  /** @internal A BAKED lamp is held dark while the level's LIGHT GRID is loaded (Lightmap): the statics have it in the
-   *  atlas and the movers in the grid's ambient cubes - left burning it lit every mover and unbaked prop a second time,
-   *  without a shadow (through walls), and put a hot spot on its own fixture. `intensity` keeps the authored value. */
-  _heldDark = false
-  _holdDark(dark: boolean): void {
-    if (this._heldDark === dark) return
-    this._heldDark = dark
-    _creator.setLightIntensity?.(this.id, dark ? 0 : this._intensity)
-  }
-
-  destroy(): void {
-    Light._points.delete(this)
-    super.destroy()
-  }
-
-  set color(value: ColorInput) {
-    this._color = value
-    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
-  }
-  get color(): ColorInput { return this._color }
-  /** Sun direction as created (the engine keeps it; a settings menu rebuilds a sun from it). */
-  get direction(): [number, number, number] { return this._direction }
-  /** Sun shadow options as created — creation-time in the engine, so a change means a new sun. */
-  get shadowsQuality(): number { return this._shadowsQuality }
-  get shadowDistance(): number { return this._shadowDistance }
-}
+// Lights. A directional sun (the engine's primary light), punctual point lights and spot lights. Add one to a
+// scene like any node; `intensity` and `color` stay writable so a light can be animated.
+
+import { Color, type ColorInput } from "../core/color"
+import type { Vec3Like } from "../math/vec"
+import { Node, type NodeTweenProps } from "./Node"
+import { DOM_GL_LIGHT, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable light props on top of the node transform. */
+export type LightTweenProps = NodeTweenProps & {
+  intensity?: number | number[],
+  color?: ColorInput | ColorInput[],
+}
+
+export type SunOptions = {
+  /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
+  direction?: Vec3Like
+  /** Luminous intensity. */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Shadow quality (default 1):
+   *   0 - no shadows
+   *   1 - 1024 map, hard edges (one filtered tap; the cheap level, ~3 % of a frame on an iGPU)
+   *   2 - 1024 map, soft edges (variance shadows + blur; ~+15 % of a frame on an iGPU)
+   *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
+   *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
+   * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
+   * On a level with a baked light grid the variance / PCSS filters cannot be used (they need every
+   * receiver in the shadow map, and the baked statics are kept out of it): 3 renders as PCSS on the
+   * depth map - the same contact-hardening look - and 2 renders as 1.
+   */
+  shadowsQuality?: 0 | 1 | 2 | 3
+  /**
+   * Metres from the camera within which the sun casts shadows (default 100). Shadows fade out by
+   * this distance and the shadow map covers only this range, so a shorter distance is crisper for
+   * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
+   */
+  shadowDistance?: number
+  /**
+   * How many shadow-map cascades split `shadowDistance` (default 1). One map over the whole range gives a tall
+   * tree 5-10 cm shadow texels on its own trunk; 3 cascades put a tight map on the first metres and coarser
+   * ones behind, fit to their texel grids so the shadow does not swim as the camera moves. Each cascade is
+   * another caster pass, so it costs in proportion to what casts: forests, not a lightmapped level.
+   */
+  shadowCascades?: 1 | 2 | 3 | 4
+}
+
+export type PointOptions = {
+  /**
+   * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
+   * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
+   * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Metres of influence — past it the light contributes nothing. This is the performance knob:
+   * overlapping point lights are the expensive case, so keep it as small as the look allows.
+   * Default 10.
+   */
+  range?: number
+  /** Point-light shadows are a cubemap render per light; off by default. */
+  castShadows?: boolean
+  /**
+   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap. A baked lamp lights the statics
+   * from the atlas and the MOVERS from the level's light grid, and is held dark in real time while that grid is
+   * loaded (without a grid it keeps lighting the movers live); a light
+   * that must reach the statics live too — a flicker, a lamp the player can shoot out, a muzzle flash —
+   * says `baked: false`: it is kept out of the bake and put on the statics' light channel. Default true.
+   */
+  baked?: boolean
+  /**
+   * THE BAKE'S SHAPE of this lamp: `[width, height]` in metres = an AREA light - a rectangle in the light's local XZ
+   * plane, emitting along its local -Y (down, for an unrotated node) with the same lumens: a ceiling panel. The bake
+   * lights from the whole rectangle (soft shadows, light from where the panel is and not from a point inside the
+   * fixture). Real time it is still the point light above. Ignored with `baked: false`.
+   */
+  bakeArea?: readonly [number, number]
+}
+
+export type SpotOptions = {
+  /**
+   * Luminous power in lumens, as a point light's. The cone does not change the brightness: widen it and the
+   * same lumens light a larger patch at the same level. On its axis a spot is 4x brighter than a point light of
+   * the same lumens (its light is not spread over the whole sphere). Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /** Metres of influence along the cone, the performance knob as for a point light. Default 10. */
+  range?: number
+  /** The cone's full angle in degrees, up to 180: past it the light contributes nothing. Default 45. */
+  angle?: number
+  /** The full angle in degrees of the cone's fully lit core; the light fades from it out to `angle`. Default 0.75 x `angle`. */
+  innerAngle?: number
+  /** A spot's shadow is one 2D shadow map (a point light's is a cubemap); off by default. */
+  castShadows?: boolean
+}
+
+export class Light extends Node {
+  private _intensity = 0
+
+  /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
+  override animateTo(props: LightTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: LightTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    if (prop === "intensity") return { domain: DOM_GL_LIGHT, id, value: floatValue, commit: (v) => { this._intensity = v as number } }
+    if (prop === "color") return { domain: DOM_GL_LIGHT, id, value: (v) => colorValue(v, Color.toRgba01) }
+    return super._tweenChannel(prop)
+  }
+  /** @internal PointOptions.baked — a candidate for the lightmap bake (default true). */
+  _baked = true
+  /** @internal every live point light, for the bake / the switch-off; a destroyed one leaves. */
+  static _points = new Set<Light>()
+  /** @internal sun direction as created (the engine keeps it). */
+  _direction: [number, number, number] = [ 0, -1, 0 ]
+  /** The most recently created sun. */
+  static lastSun: Light | null = null
+  /** @internal the colour as created / last set (a settings menu recreates a sun from these). */
+  _color: ColorInput = 0xffffff
+  /** @internal sun shadow options as created (creation-time in the engine). */
+  _shadowsQuality = 1
+  _shadowDistance = 100
+  _shadowCascades = 1
+
+  /** A directional sun light. */
+  static sun(options: SunOptions = {}): Light {
+    const light = new Light()
+    const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
+    light._direction = [ dx, dy, dz ]
+    light._intensity = options.intensity ?? 100000
+    light._color = options.color ?? 0xffffff
+    light._shadowsQuality = options.shadowsQuality ?? 1
+    light._shadowDistance = options.shadowDistance ?? 100
+    light._shadowCascades = options.shadowCascades ?? 1
+    Light.lastSun = light
+    _creator.createSunLight(
+      light.id, dx, dy, dz,
+      light._intensity,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.shadowsQuality ?? 1,
+      options.shadowDistance ?? 100,
+      light._shadowCascades,
+    )
+    return light
+  }
+
+  /**
+   * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
+   */
+  static point(options: PointOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    light._color = options.color ?? 0xffffff
+    light._baked = options.baked ?? true
+    Light._points.add(light)
+    _creator.createPointLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.range ?? 10,
+      options.castShadows ?? false,
+    )
+    if (options.bakeArea && light._baked) _creator.setLightBakeArea?.(light.id, options.bakeArea[0], options.bakeArea[1])
+    // an unbaked lamp lights the baked statics live: Filament channel 1 (see Lightmap)
+    if (!light._baked) _creator.setLightChannel?.(light.id, 1, true)
+    return light
+  }
+
+  /** @internal a spot's cone, full angles in degrees (the engine takes half-angles in radians). */
+  _angle = 0
+  _innerAngle = 0
+
+  /**
+   * A spot light — a flashlight, a headlight, a stage light. It shines along the node's forward (-Z): position
+   * it like any node and aim it with `lookAt`. Real time only: the lightmap bake takes no spot lights, so a spot
+   * lights the baked statics live too.
+   */
+  static spot(options: SpotOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    light._color = options.color ?? 0xffffff
+    light._baked = false
+    light._angle = options.angle ?? 45
+    light._innerAngle = options.innerAngle ?? light._angle * 0.75
+    const [ inner, outer ] = light._cone()
+    _creator.createSpotLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(light._color),
+      options.range ?? 10,
+      inner, outer,
+      options.castShadows ?? false,
+    )
+    // the statics of a lightmapped level are on Filament channel 1 alone (see Lightmap)
+    _creator.setLightChannel?.(light.id, 1, true)
+    return light
+  }
+
+  /** @internal the cone as the engine takes it: half-angles in radians, outer in (0, 90°], inner in [0, outer]. */
+  _cone(): [number, number] {
+    const rad = Math.PI / 360
+    const outer = Math.min(Math.max(this._angle, 0.1), 180) * rad
+    const inner = Math.min(Math.max(this._innerAngle, 0), this._angle) * rad
+    return [ Math.min(inner, outer), outer ]
+  }
+
+  /** A spot's full cone angle in degrees — live (a flashlight's focus). */
+  get angle(): number { return this._angle }
+  set angle(value: number) {
+    this._innerAngle *= this._angle > 0 ? value / this._angle : 0
+    this._angle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+  /** A spot's fully lit core, full angle in degrees — live. Setting `angle` scales it along. */
+  get innerAngle(): number { return this._innerAngle }
+  set innerAngle(value: number) {
+    this._innerAngle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+
+  /** Live intensity (sun: lux, point / spot: lumens) — animate a flash without rebuilding the light. */
+  get intensity(): number { return this._intensity }
+  set intensity(value: number) {
+    this._intensity = value
+    if (!this._heldDark) _creator.setLightIntensity?.(this.id, value)
+  }
+
+  /** @internal A BAKED lamp is held dark while the level's LIGHT GRID is loaded (Lightmap): the statics have it in the
+   *  atlas and the movers in the grid's ambient cubes - left burning it lit every mover and unbaked prop a second time,
+   *  without a shadow (through walls), and put a hot spot on its own fixture. `intensity` keeps the authored value. */
+  _heldDark = false
+  _holdDark(dark: boolean): void {
+    if (this._heldDark === dark) return
+    this._heldDark = dark
+    _creator.setLightIntensity?.(this.id, dark ? 0 : this._intensity)
+  }
+
+  destroy(): void {
+    Light._points.delete(this)
+    super.destroy()
+  }
+
+  set color(value: ColorInput) {
+    this._color = value
+    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
+  }
+  get color(): ColorInput { return this._color }
+  /** Sun direction as created (the engine keeps it; a settings menu rebuilds a sun from it). */
+  get direction(): [number, number, number] { return this._direction }
+  /** Sun shadow options as created — creation-time in the engine, so a change means a new sun. */
+  get shadowsQuality(): number { return this._shadowsQuality }
+  get shadowDistance(): number { return this._shadowDistance }
+}

package/src/host.d.ts

@@ -1,6 +1,10 @@
 // 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.
 
+// The one SDK type the macros return: an SVG image source, the same `SvgSource` a project has as
+// a global (build-types.ts points this import into dist/types when it copies the file).
+import type { SvgSource } from "./runtime/misc"
+
 declare global {
   function setTimeout(handler: (...args: any[]) => void, timeout?: number): number
   function setInterval(handler: (...args: any[]) => void, timeout?: number): number
@@ -33,7 +37,7 @@ declare global {
   function asset(path: `${string}.json`): any
   /** Compile-time macro: `asset('./logo.svg')` yields the file as an SVG image source — for
    *  `UIImage(...)` and `bgImage`. */
-  function asset(path: `${string}.svg`): { readonly svg: string, tintColor: string | null }
+  function asset(path: `${string}.svg`): SvgSource
   /** 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
@@ -53,7 +57,7 @@ declare global {
    *  (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 }
+  function assetIcon(id: string, opts?: { color?: string }): SvgSource
 
   /** 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

package/src/runtime/misc.ts

@@ -18,3 +18,7 @@ export type SvgSourceValue = {
 
 /** Wrap raw SVG XML so it can be used as an image source. */
 export const SvgSource = (svg: string): SvgSourceValue => ({ svg, tintColor: null })
+/** The type of the value: what `SvgSource(xml)`, `assetIcon("lucide:bell")` and `asset("./logo.svg")`
+ *  all return, and what `UIImage` / `bgImage` take — ONE name for an SVG image source, global to a
+ *  project like the function (host.d.ts names it for the macros). */
+export type SvgSource = SvgSourceValue

package/src/ui/UIPager.ts

@@ -31,6 +31,8 @@ export type UIPagerStyle = ElementStyle & DrawableStyle
 /** The pagers whose screen is currently visible, outermost → innermost. `UIPager.current` is the
  *  last (innermost). Maintained by each owned screen's onOpen/onClose via _activate/_deactivate. */
 const _activeStack: PagerElement[] = []
+/** @internal The active pagers, outermost → innermost — what `UITabs.current` searches. */
+export const _activePagers = (): readonly PagerElement[] => _activeStack
 
 /**
  * The screen-navigation element: sibling **tabs** that swipe natively side to side, each with its