lecodes-sdk 2.0.8 → 2.0.10

package/src/gl/Light.ts

@@ -1,194 +1,257 @@
-// Lights. A directional sun (the engine's primary light) and punctual point 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 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 }
-
-  /** Live intensity (sun: lux, point: 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/gl/Material.ts

@@ -187,6 +187,9 @@ export class Material {
     } else if ("_h" in (shader as any)) {
       this.shader = shader as FetchResponse
       this._h = _creator.createMaterial((shader as any)._h.id)   // owned: dropped and unused → freed
+      // 0xFFFFFFFF = the engine refused the package: no shader in it for the running backend (a
+      // phone on Vulkan handed the mobile `_opengl` artifact — the host's log names what is missing).
+      if (this._h.id === 0xFFFFFFFF) throw new Error("Material: the engine refused the shader (no variant for its backend — see the host log)")
     } else {
       this.shader = "unknown"
       this._h = shader as Handle           // an instance the runtime already wrapped for us

package/src/gl/Scene.ts

@@ -10,6 +10,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -478,10 +479,19 @@ export class Scene implements Presentable {
 
   /** @internal The destination tuple (ui/presentable.ts). */
   _dest(): DestTuple {
-    // Addressed by the router / an attached widget: make sure the (kind, id) resolves back to us.
+    // Addressed by the router / its content layer: make sure the (kind, id) resolves back to us.
     registerDest(TREE_DEST_SCENE3D, this._id, this)
     return [TREE_DEST_SCENE3D, this._id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. `scene.setContent([hud])`. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */

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/inject.ts

@@ -102,6 +102,7 @@ export {
   UITabs, type UITabDef,
   defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
+  UIOverlay, type UIWidgetContent,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,

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/NativeView.ts

@@ -10,6 +10,7 @@
 // wrapper convention.
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "./UILayer"
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
 import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
@@ -45,6 +46,8 @@ export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableSty
   /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
   on(event: string, callback: (data?: any) => void): this
   off(event: string, callback: (data?: any) => void): this
+  /** The UI over the view when presented: widgets over it (`Presentable.setContent`). */
+  setContent(content: UIWidgetContent): this
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -85,6 +88,14 @@ export class NativeViewElement extends Element<"native"> implements Presentable
 
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_NATIVE, this._viewId, this.viewName, this._paramsJson] }
+  /** @internal The view's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the view when it is presented full screen — widgets (a header, a card, a sheet
+   *  over a map), laid out over it; touches outside a widget's box reach the view. */
+  setContent(content: UIWidgetContent): this {
+    _setSurfaceContent(this, content)
+    return this
+  }
 
   open(options?: PresentOptions): void {
     if (!tree().isViewSupported(this.viewName)) {

package/src/ui/UI.ts

@@ -10,6 +10,7 @@ export { UIVideo, type UIVideoStyle } from './UIVideo'
 export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
 
 export { UIWidget, type UIWidgetStyle } from './UIWidget'
+export { UIOverlay, type UIWidgetContent } from './UILayer'
 export { UIModal, type UIModalStyle } from './UIModal'
 export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
 export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'

package/src/ui/UIBottomSheet.ts

@@ -67,6 +67,7 @@ export class BottomSheetElement extends ModalElement {
     // The inherited show/hide pose animates ONLY the scrim: sheet geometry rides the
     // sheetDetent style key, never the pose system.
     this._transition = { duration: SHEET_ANIM_MS }
+    this._syncPose()
     this._addFlags(TREE_FLAG_DETENT)
   }
 
@@ -97,7 +98,7 @@ export class BottomSheetElement extends ModalElement {
   setDetent(index: number): void {
     const clamped = Math.max(0, Math.min(Math.floor(index), this._detents.length - 1))
     this._detent = clamped
-    if (!this._open) return                     // applied by the next show()
+    if (!this._shown) return                    // applied by the next show()
     this.style({ sheetDetent: clamped } as UIBottomSheetStyle)
     for (const callback of this._detentListeners) callback(clamped)
   }
@@ -107,20 +108,20 @@ export class BottomSheetElement extends ModalElement {
     return this
   }
 
-  show(): void {
-    if (this._open) return
+  override show(): void {
+    if (this._shown) return
     // Before the mount, so the built node carries the target and hosts play the entrance to it.
     this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
     super.show()
   }
 
-  hide(): void {
-    if (!this._open) return
-    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; unmount follows
+  override hide(): void {
+    if (!this._shown) return
+    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; the hide follows
     super.hide()
   }
 
-  dismissible(enabled: boolean): this {
+  override dismissible(enabled: boolean): this {
     super.dismissible(enabled)
     this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
     return this