lecodes-sdk 2.0.12 → 2.1.0

package/src/gl/postProcessing.ts

@@ -0,0 +1,450 @@
+// Post-processing of a 3D scene: the look, as ONE object (`scene.postProcessing`,
+// `SceneOptions.postProcessing`) — what Unity's volume and Unreal's post-process volume hold, so it
+// is where a developer looks for it: tone mapping and colour grading, a LUT, bloom, vignette,
+// ambient occlusion, screen-space reflections, depth of field. The scene's own light (ibl,
+// exposureCompensation, fog) and its QUALITY (antialias, renderScale) stay on the scene.
+//
+// The object is read-only on the scene: a field is written (`scene.postProcessing.contrast = 1.1`),
+// several at once with `apply({ ... })` — NAMED FIELDS ONLY, at every level (`apply({ bloom:
+// { intensity: 0.4 } })` leaves the bloom's other knobs and everything else as they are; `false`
+// turns a feature off) — and `reset()` puts every field back to its default.
+//
+// Two bands inside, because the engine treats them differently:
+//
+//  - The GRADING band — tone mapping, exposure, white balance, contrast / saturation / vibrance,
+//    shadows / midtones / highlights, slope / offset / power, curves, the .cube LUT — is baked by the
+//    engine into the ONE 3D lookup table the frame always samples. Free per frame; a CHANGE re-bakes
+//    a 32³ table on the CPU. So writes here are COALESCED: a field write marks the band dirty and the
+//    whole band goes to the engine once, in a microtask (the end of the current handler), and the
+//    values are quantised to 1/1000 so a tween that barely moves does not re-bake. Not a thing to
+//    animate every frame; a blend between two looks over a second is fine (a few dozen bakes).
+//  - The LIVE band — bloom, vignette, ambient occlusion, screen-space reflections, depth of field —
+//    is a set of view options: written to the engine at once, free to animate (a focus pull every
+//    frame is what depthOfField is for).
+//
+// The wire of the grading band is a fixed float layout (`CG`), mirrored by creator.h's
+// ColorGradingParam: the engine reads by index, so an index here never moves — a field is added at
+// the end. Overlay scenes take their parent's grading (one look per picture); the live band is per
+// scene.
+
+import { Color, type ColorInput } from "../core/color"
+import type { Texture } from "./Texture"
+
+export type ToneMappingOperator = "aces" | "neutral" | "linear" | "filmic"
+/** A linear RGB triple. */
+export type Rgb = readonly [number, number, number]
+export type Quality = "low" | "medium" | "high" | "ultra"
+
+export type BloomOptions = {
+  /** How much of the blurred highlights is added back, 0..1 (default 0.2). */
+  intensity?: number
+  /** Only what is brighter than 1.0 after exposure blooms (default true); false makes everything
+   *  glow a little — the soft "dreamy" look. */
+  threshold?: boolean
+  /** Clamp of one pixel's contribution (default 1000); lower it when a few emissive pixels flicker. */
+  highlight?: number
+  /** Depth of the blur chain, 1..12 (default 6): how far the glow spreads. */
+  levels?: number
+  /** The blur's sample count (default 'medium'). */
+  quality?: Quality
+  /** Ghosts + halo around the brightest spots (default false). */
+  lensFlare?: boolean
+  /** A "dirty lens": this texture multiplied into the bloom (default none). */
+  dirt?: Texture | null
+  /** How much of the dirt shows, 0..1 (default 0.2). */
+  dirtStrength?: number
+}
+
+export type VignetteOptions = {
+  /** How far from the centre the darkening starts, 0..1 (default 0.5). */
+  midPoint?: number
+  /** 0 follows the aspect ratio, 1 is a circle (default 0.5). */
+  roundness?: number
+  /** Softness of the edge, 0..1 (default 0.5). */
+  feather?: number
+  /** The colour at the edge (default black). */
+  color?: ColorInput
+}
+
+/** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
+ *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
+ *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
+ *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
+ *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
+export type AmbientOcclusionOptions = {
+  /** Strength of the darkening (default 1). */
+  intensity?: number
+  /** How far the occlusion reaches, in metres (default 0.3). */
+  radius?: number
+  /** Falloff contrast; >1 tightens it into the crease (default 1). */
+  power?: number
+  /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
+  quality?: Quality
+}
+
+/** Screen-space reflections: glossy surfaces reflect what is ON SCREEN, by a ray march through the
+ *  depth buffer (a wet floor reflecting the lamps above it). Nothing off screen reflects and a
+ *  reflection ends at the frame's edge — the classic limit. A per-pixel ray: a real cost on a
+ *  phone, not measured yet. */
+export type ScreenSpaceReflectionsOptions = {
+  /** Metres a ray travels before giving up (default 3). */
+  maxDistance?: number
+  /** Metres a surface is assumed to extend behind its depth — a hit inside it counts (default 0.1). */
+  thickness?: number
+  /** Pixels per ray step: 1 = exact and slow, 2..4 the usual (default 2). */
+  stride?: number
+}
+
+/** Depth of field: the camera focuses at `focusDistance` and everything else blurs as the lens
+ *  would — as if it were at f/`aperture`, WITHOUT touching the exposure (the camera's own aperture,
+ *  f/16 by default, would show next to no blur; the engine scales the blur instead of opening the
+ *  lens). The physics are honest and therefore mild: a game camera is a WIDE lens (fov 60° is a
+ *  21 mm lens), and a wide lens at f/1.4 still blurs a prop 9 m behind a 2.5 m focus by only ~2 px
+ *  of 600 — `strength` multiplies the blur for the look a 50 mm lens would give (3-4 reads as
+ *  "cinematic" at fov 60°). All live: a focus pull is a `focusDistance` written every frame. */
+export type DepthOfFieldOptions = {
+  /** Metres from the camera to the plane in focus (default 10). */
+  focusDistance?: number
+  /** The f-number the blur should look like (default 2.8; smaller = shallower). */
+  aperture?: number
+  /** Multiplier on the blur (default 1 = the physics of the camera's lens). */
+  strength?: number
+}
+
+export type WhiteBalance = {
+  /** Blue / yellow axis, -1 (cool, 50 000 K) .. 1 (warm, 2 000 K); 0 = none. */
+  temperature?: number
+  /** Green / magenta axis, -1 .. 1; 0 = none. */
+  tint?: number
+}
+
+/** Where the tonal zones of `shadows` / `midtones` / `highlights` fade into each other, in 0..1 of
+ *  the (linear) luminance: `shadows` = (start, end) of the shadows → midtones fade (default 0, 0.333),
+ *  `highlights` = (start, end) of the midtones → highlights fade (default 0.55, 1). */
+export type TonalRanges = {
+  shadows?: readonly [number, number]
+  highlights?: readonly [number, number]
+}
+
+/** Per-channel curves: a gamma on the shadows, the point where shadows stop and highlights start,
+ *  and a scale on the highlights — each per RGB channel, `[1, 1, 1]` = none. */
+export type ColorCurves = {
+  shadowGamma?: Rgb
+  midPoint?: Rgb
+  highlightScale?: Rgb
+}
+
+export type PostProcessingOptions = {
+  /** The operator that folds the scene's HDR light into the display's range (default 'aces').
+   *  `'aces'` (filament's ACES legacy) desaturates bright colours towards white — HDR fire reads
+   *  pale; `'neutral'` (Khronos PBR Neutral) keeps hue and saturation until very bright; `'linear'`
+   *  clips each channel (what an engine without a tonemapper shows — saturated, Unity-without-post
+   *  look); `'filmic'` is the Uncharted curve. */
+  toneMapping?: ToneMappingOperator
+  /** Post-exposure in stops, applied AFTER bloom to the finished picture (default 0). Not the
+   *  camera's `exposureCompensation`, which scales the light itself — what bloom and fog see. */
+  exposure?: number
+  whiteBalance?: WhiteBalance
+  /** 0..2, 1 = none. Applied in log space. */
+  contrast?: number
+  /** 0..2, 1 = none. */
+  saturation?: number
+  /** Saturation that spares what is already saturated, 0..2, 1 = none. */
+  vibrance?: number
+  /** Linear RGB multiplier of the shadows zone, `[1, 1, 1]` = none. */
+  shadows?: Rgb
+  midtones?: Rgb
+  highlights?: Rgb
+  ranges?: TonalRanges
+  /** ASC CDL — the lift / gamma / gain of a grading suite, per channel, applied in log space:
+   *  `slope` multiplies (gain; `[1, 1, 1]` = none), `offset` adds (lift; `[0, 0, 0]` = none),
+   *  `power` is the exponent (gamma; `[1, 1, 1]` = none). */
+  slope?: Rgb
+  offset?: Rgb
+  power?: Rgb
+  curves?: ColorCurves
+  /** A 3D LUT from a grading tool (Resolve, Photoshop, Unity's Color Lookup) applied last, after
+   *  the operator, in display-referred sRGB — a `.cube` file: `asset('./look.cube')`, or a bare
+   *  staged filename. `null` removes it. */
+  lut?: string | null
+  /** `true` = defaults (intensity 0.2), an object = its knobs, `false` = off. */
+  bloom?: boolean | BloomOptions
+  /** `true` = defaults (a soft black edge), an object = its knobs, `false` = off. */
+  vignette?: boolean | VignetteOptions
+  /** `true` = defaults (radius 0.3 m), an object = its knobs, `false` = off. */
+  ambientOcclusion?: boolean | AmbientOcclusionOptions
+  /** `true` = defaults, an object = its knobs, `false` = off. */
+  screenSpaceReflections?: boolean | ScreenSpaceReflectionsOptions
+  /** `true` = focus at 10 m as f/2.8, an object = its knobs, `false` = off. */
+  depthOfField?: boolean | DepthOfFieldOptions
+}
+
+/** The float layout of `_creator.setColorGrading` — creator.h's ColorGradingParam. Indices never
+ *  move; a new field goes at the end and COUNT grows. */
+export const CG = {
+  TONE_MAPPING: 0, EXPOSURE: 1, TEMPERATURE: 2, TINT: 3, CONTRAST: 4, VIBRANCE: 5, SATURATION: 6,
+  SHADOWS: 7, MIDTONES: 10, HIGHLIGHTS: 13, RANGES: 16, SLOPE: 20, OFFSET: 23, POWER: 26,
+  SHADOW_GAMMA: 29, MID_POINT: 32, HIGHLIGHT_SCALE: 35, LUT: 38,
+  COUNT: 39,
+} as const
+
+const TONE_MAPPING_MODE: Record<ToneMappingOperator, number> = { aces: 0, neutral: 1, linear: 2, filmic: 3 }
+const QUALITY = { low: 0, medium: 1, high: 2, ultra: 3 } as const
+const NO_TEXTURE = 0xFFFFFFFF
+
+const ONE: Rgb = [ 1, 1, 1 ]
+const ZERO: Rgb = [ 0, 0, 0 ]
+const rgb = (v: Rgb | undefined, d: Rgb): Rgb => v ? [ v[0], v[1], v[2] ] : d
+const pair = (v: readonly [number, number] | undefined, d: readonly [number, number]): readonly [number, number] => v ? [ v[0], v[1] ] : d
+
+/** The grading band, normalised: every field present. */
+type Grading = {
+  toneMapping: ToneMappingOperator
+  exposure: number
+  temperature: number
+  tint: number
+  contrast: number
+  saturation: number
+  vibrance: number
+  shadows: Rgb
+  midtones: Rgb
+  highlights: Rgb
+  rangeShadows: readonly [number, number]
+  rangeHighlights: readonly [number, number]
+  slope: Rgb
+  offset: Rgb
+  power: Rgb
+  shadowGamma: Rgb
+  midPoint: Rgb
+  highlightScale: Rgb
+  lut: string | null
+}
+
+const defaultGrading = (): Grading => ({
+  toneMapping: "aces", exposure: 0, temperature: 0, tint: 0, contrast: 1, saturation: 1, vibrance: 1,
+  shadows: ONE, midtones: ONE, highlights: ONE, rangeShadows: [ 0, 0.333 ], rangeHighlights: [ 0.55, 1 ],
+  slope: ONE, offset: ZERO, power: ONE, shadowGamma: ONE, midPoint: ONE, highlightScale: ONE, lut: null,
+})
+
+const BLOOM_DEFAULTS: Required<BloomOptions> = { intensity: 0.2, threshold: true, highlight: 1000, levels: 6, quality: "medium", lensFlare: false, dirt: null, dirtStrength: 0.2 }
+const VIGNETTE_DEFAULTS: Required<VignetteOptions> = { midPoint: 0.5, roundness: 0.5, feather: 0.5, color: "#000000" }
+const AO_DEFAULTS: Required<AmbientOcclusionOptions> = { intensity: 1, radius: 0.3, power: 1, quality: "medium" }
+const SSR_DEFAULTS: Required<ScreenSpaceReflectionsOptions> = { maxDistance: 3, thickness: 0.1, stride: 2 }
+const DOF_DEFAULTS: Required<DepthOfFieldOptions> = { focusDistance: 10, aperture: 2.8, strength: 1 }
+
+/** A live feature's new state from a write: `false` = off, `true` = on (the current knobs, or the
+ *  defaults when it was off), an object = on with THOSE knobs changed. */
+const merge = <T extends object>(current: Required<T> | null, v: boolean | T, defaults: Required<T>): Required<T> | null =>
+  v === false ? null : { ...(current ?? defaults), ...(v === true ? {} : v) }
+
+const q = (v: number): number => Math.round(v * 1000) / 1000
+const equal = (a: Float32Array, b: Float32Array): boolean => { for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false; return true }
+let identityPacked: Float32Array | null = null
+const isIdentity = (p: Float32Array): boolean => equal(p, identityPacked ??= new PostProcessing(0)._pack())
+
+/** The scene's post-processing (`scene.postProcessing`). Read a field for the current value, write
+ *  one to change it; `apply(options)` writes the named ones; `reset()` is the defaults. */
+export class PostProcessing {
+  private _g: Grading = defaultGrading()
+  private _bloom: Required<BloomOptions> | null = null
+  private _vignette: Required<VignetteOptions> | null = null
+  private _ao: Required<AmbientOcclusionOptions> | null = null
+  private _ssr: Required<ScreenSpaceReflectionsOptions> | null = null
+  private _dof: Required<DepthOfFieldOptions> | null = null
+  private _dirty = false
+  private _lutDirty = false
+  private _sentLut: string | null = null
+  private _sent: Float32Array | null = null   // the last array the engine got; a scene nobody graded sends none
+
+  private readonly _sceneId: number
+  /** @internal */
+  constructor(sceneId: number) { this._sceneId = sceneId }
+
+  /** Write the fields named in `options`, nothing else — at every level: `{ bloom: { intensity:
+   *  0.4 } }` changes one bloom knob, `{ whiteBalance: { tint: 0.1 } }` keeps the temperature.
+   *  The grading band goes to the engine at once (one bake), not in a microtask. */
+  apply(options: PostProcessingOptions): this {
+    if (options.toneMapping !== undefined) this.toneMapping = options.toneMapping
+    if (options.exposure !== undefined) this.exposure = options.exposure
+    if (options.whiteBalance !== undefined) this.whiteBalance = options.whiteBalance
+    if (options.contrast !== undefined) this.contrast = options.contrast
+    if (options.saturation !== undefined) this.saturation = options.saturation
+    if (options.vibrance !== undefined) this.vibrance = options.vibrance
+    if (options.shadows !== undefined) this.shadows = options.shadows
+    if (options.midtones !== undefined) this.midtones = options.midtones
+    if (options.highlights !== undefined) this.highlights = options.highlights
+    if (options.ranges !== undefined) this.ranges = options.ranges
+    if (options.slope !== undefined) this.slope = options.slope
+    if (options.offset !== undefined) this.offset = options.offset
+    if (options.power !== undefined) this.power = options.power
+    if (options.curves !== undefined) this.curves = options.curves
+    if (options.lut !== undefined) this.lut = options.lut
+    this.flush()
+    if (options.bloom !== undefined) this.bloom = options.bloom
+    if (options.vignette !== undefined) this.vignette = options.vignette
+    if (options.ambientOcclusion !== undefined) this.ambientOcclusion = options.ambientOcclusion
+    if (options.screenSpaceReflections !== undefined) this.screenSpaceReflections = options.screenSpaceReflections
+    if (options.depthOfField !== undefined) this.depthOfField = options.depthOfField
+    return this
+  }
+
+  /** Every field back to its default: the engine's own look, every live feature off. */
+  reset(): this {
+    const g = defaultGrading()
+    this._lutDirty = g.lut !== this._sentLut
+    this._g = g
+    this._dirty = true
+    this.flush()
+    if (this._bloom) this.bloom = false
+    if (this._vignette) this.vignette = false
+    if (this._ao) this.ambientOcclusion = false
+    if (this._ssr) this.screenSpaceReflections = false
+    if (this._dof) this.depthOfField = false
+    return this
+  }
+
+  // ---- the grading band: coalesced, quantised, baked by the engine ----
+
+  get toneMapping(): ToneMappingOperator { return this._g.toneMapping }
+  set toneMapping(v: ToneMappingOperator) { this._g.toneMapping = v; this._touch() }
+  get exposure(): number { return this._g.exposure }
+  set exposure(v: number) { this._g.exposure = v; this._touch() }
+  get whiteBalance(): Required<WhiteBalance> { return { temperature: this._g.temperature, tint: this._g.tint } }
+  set whiteBalance(v: WhiteBalance) {
+    if (v.temperature !== undefined) this._g.temperature = v.temperature
+    if (v.tint !== undefined) this._g.tint = v.tint
+    this._touch()
+  }
+  get contrast(): number { return this._g.contrast }
+  set contrast(v: number) { this._g.contrast = v; this._touch() }
+  get saturation(): number { return this._g.saturation }
+  set saturation(v: number) { this._g.saturation = v; this._touch() }
+  get vibrance(): number { return this._g.vibrance }
+  set vibrance(v: number) { this._g.vibrance = v; this._touch() }
+  get shadows(): Rgb { return this._g.shadows }
+  set shadows(v: Rgb) { this._g.shadows = rgb(v, ONE); this._touch() }
+  get midtones(): Rgb { return this._g.midtones }
+  set midtones(v: Rgb) { this._g.midtones = rgb(v, ONE); this._touch() }
+  get highlights(): Rgb { return this._g.highlights }
+  set highlights(v: Rgb) { this._g.highlights = rgb(v, ONE); this._touch() }
+  get ranges(): Required<TonalRanges> { return { shadows: this._g.rangeShadows, highlights: this._g.rangeHighlights } }
+  set ranges(v: TonalRanges) {
+    this._g.rangeShadows = pair(v.shadows, this._g.rangeShadows)
+    this._g.rangeHighlights = pair(v.highlights, this._g.rangeHighlights)
+    this._touch()
+  }
+  get slope(): Rgb { return this._g.slope }
+  set slope(v: Rgb) { this._g.slope = rgb(v, ONE); this._touch() }
+  get offset(): Rgb { return this._g.offset }
+  set offset(v: Rgb) { this._g.offset = rgb(v, ZERO); this._touch() }
+  get power(): Rgb { return this._g.power }
+  set power(v: Rgb) { this._g.power = rgb(v, ONE); this._touch() }
+  get curves(): Required<ColorCurves> { return { shadowGamma: this._g.shadowGamma, midPoint: this._g.midPoint, highlightScale: this._g.highlightScale } }
+  set curves(v: ColorCurves) {
+    this._g.shadowGamma = rgb(v.shadowGamma, this._g.shadowGamma)
+    this._g.midPoint = rgb(v.midPoint, this._g.midPoint)
+    this._g.highlightScale = rgb(v.highlightScale, this._g.highlightScale)
+    this._touch()
+  }
+  get lut(): string | null { return this._g.lut }
+  set lut(v: string | null) { this._g.lut = v; this._lutDirty = v !== this._sentLut; this._touch() }
+
+  // ---- the live band: view options, written at once ----
+
+  get bloom(): Required<BloomOptions> | false { return this._bloom ?? false }
+  set bloom(v: boolean | BloomOptions) {
+    const b = this._bloom = merge(this._bloom, v, BLOOM_DEFAULTS)
+    if (b) {
+      _creator.setBloomOptions(this._sceneId, true, b.intensity, b.threshold, b.highlight, b.levels,
+        QUALITY[b.quality], b.lensFlare, b.dirt ? b.dirt._h.id : NO_TEXTURE, b.dirtStrength)
+    } else {
+      _creator.setBloomOptions(this._sceneId, false, 0, true, 1000, 6, 1, false, NO_TEXTURE, 0)
+    }
+  }
+
+  get vignette(): Required<VignetteOptions> | false { return this._vignette ?? false }
+  set vignette(v: boolean | VignetteOptions) {
+    const g = this._vignette = merge(this._vignette, v, VIGNETTE_DEFAULTS)
+    if (g) _creator.setVignetteOptions?.(this._sceneId, true, g.midPoint, g.roundness, g.feather, Color.toPackedRgba(g.color))
+    else _creator.setVignetteOptions?.(this._sceneId, false, 0.5, 0.5, 0.5, 0x000000FF)
+  }
+
+  get ambientOcclusion(): Required<AmbientOcclusionOptions> | false { return this._ao ?? false }
+  set ambientOcclusion(v: boolean | AmbientOcclusionOptions) {
+    const o = this._ao = merge(this._ao, v, AO_DEFAULTS)
+    if (o) _creator.setAmbientOcclusionOptions?.(this._sceneId, true, o.intensity, o.radius, o.power, QUALITY[o.quality])
+    else _creator.setAmbientOcclusionOptions?.(this._sceneId, false, 1, 0.3, 1, 1)
+  }
+
+  get screenSpaceReflections(): Required<ScreenSpaceReflectionsOptions> | false { return this._ssr ?? false }
+  set screenSpaceReflections(v: boolean | ScreenSpaceReflectionsOptions) {
+    const o = this._ssr = merge(this._ssr, v, SSR_DEFAULTS)
+    if (o) _creator.setScreenSpaceReflections?.(this._sceneId, true, o.maxDistance, o.thickness, o.stride)
+    else _creator.setScreenSpaceReflections?.(this._sceneId, false, 3, 0.1, 2)
+  }
+
+  get depthOfField(): Required<DepthOfFieldOptions> | false { return this._dof ?? false }
+  set depthOfField(v: boolean | DepthOfFieldOptions) {
+    const o = this._dof = merge(this._dof, v, DOF_DEFAULTS)
+    if (o) _creator.setDepthOfField?.(this._sceneId, true, o.focusDistance, o.aperture, o.strength)
+    else _creator.setDepthOfField?.(this._sceneId, false, 0, 0, 1)
+  }
+
+  // ---- the flush ----
+
+  private _touch(): void {
+    if (this._dirty) return
+    this._dirty = true
+    Promise.resolve().then(() => this.flush())
+  }
+
+  /** Send the grading band now (it is sent on its own at the end of the current handler). */
+  flush(): void {
+    if (!this._dirty) return
+    this._dirty = false
+    const g = this._g
+    if (this._lutDirty) {
+      // The LUT goes first, under the OLD flag, so the engine stores it and bakes ONCE on the
+      // parameter write that follows (creator.h setColorLut). Removal is the flag alone.
+      this._lutDirty = false
+      this._sentLut = g.lut
+      if (g.lut !== null) {
+        // `asset()` hands back "id:<n>" (already staged); a bare name is resolved on the spot.
+        const id = g.lut.startsWith("id:") ? Number(g.lut.slice(3)) : _creatorFetch.local(g.lut)
+        _creator.setColorLut?.(this._sceneId, id)
+      }
+    }
+    const packed = this._pack()
+    if (this._sent === null && isIdentity(packed)) return   // never graded and still the default: nothing to say
+    if (this._sent !== null && equal(this._sent, packed)) return
+    this._sent = packed
+    _creator.setColorGrading?.(this._sceneId, packed)
+  }
+
+  /** @internal The wire form of the grading band (tests). */
+  _pack(): Float32Array {
+    const g = this._g
+    const p = new Float32Array(CG.COUNT)
+    const put3 = (at: number, v: Rgb) => { p[at] = q(v[0]); p[at + 1] = q(v[1]); p[at + 2] = q(v[2]) }
+    p[CG.TONE_MAPPING] = TONE_MAPPING_MODE[g.toneMapping] ?? 0
+    p[CG.EXPOSURE] = q(g.exposure)
+    p[CG.TEMPERATURE] = q(g.temperature)
+    p[CG.TINT] = q(g.tint)
+    p[CG.CONTRAST] = q(g.contrast)
+    p[CG.VIBRANCE] = q(g.vibrance)
+    p[CG.SATURATION] = q(g.saturation)
+    put3(CG.SHADOWS, g.shadows)
+    put3(CG.MIDTONES, g.midtones)
+    put3(CG.HIGHLIGHTS, g.highlights)
+    p[CG.RANGES] = q(g.rangeShadows[0]); p[CG.RANGES + 1] = q(g.rangeShadows[1])
+    p[CG.RANGES + 2] = q(g.rangeHighlights[0]); p[CG.RANGES + 3] = q(g.rangeHighlights[1])
+    put3(CG.SLOPE, g.slope)
+    put3(CG.OFFSET, g.offset)
+    put3(CG.POWER, g.power)
+    put3(CG.SHADOW_GAMMA, g.shadowGamma)
+    put3(CG.MID_POINT, g.midPoint)
+    put3(CG.HIGHLIGHT_SCALE, g.highlightScale)
+    p[CG.LUT] = g.lut !== null ? 1 : 0
+    return p
+  }
+}

package/src/runtime/app.ts

@@ -27,11 +27,50 @@ type AppEventMap = {
   keyboard: (height: number, duration: number) => void
 }
 
+/** The installed app this bundle runs in — see `app.host`. */
+export interface AppHost {
+  /** The store build's version string (Android versionName, iOS CFBundleShortVersionString; app.json
+   *  `version` in a `lecodes app` shell). `undefined` where the host is not an installed app. */
+  version?: string
+  /** The store build's build number (versionCode / CFBundleVersion; app.json `buildNumber` /
+   *  `versionCode`). `undefined` where the host is not an installed app, `0` when not numeric. */
+  build?: number
+  /** The SDK embedded in the host — the lecodes-ios-sdk / lecodes-android-sdk release a shell pins,
+   *  the runtime's version elsewhere. */
+  sdk: string
+}
+
+/** The bundle that is running — see `app.bundle`. */
+export interface AppBundle {
+  /** The SDK this bundle was compiled with (`app.sdkVersion`). */
+  sdk: string
+  /** When it was compiled (ISO 8601) — the `// last-updated:` header line; `undefined` on a bundle
+   *  without it. */
+  updatedAt?: string
+}
+
 export const app = {
   /** The SDK this app was compiled with (semver, e.g. `"2.0.0"`). Its major is the bundle ↔ runtime
    *  contract: a host runs only bundles of its own major, and the launchers send it as `?sdk=` when
-   *  they fetch a published bundle — the platform keeps one bundle per major. */
+   *  they fetch a published bundle — the platform keeps one bundle per major. Also `app.bundle.sdk`. */
   sdkVersion: SDK_VERSION,
+  /** The INSTALLED app: the store build this bundle runs in. After an over-the-air update the code
+   *  is newer than the binary, so a feature that needs native support added in a later store build
+   *  (a plugin, an SDK method) branches on `app.host.sdk` / `app.host.build` — and on `typeof` of
+   *  the method itself, which is the final word. Minor and patch of the SDK never gate anything. */
+  get host(): AppHost {
+    return {
+      version: _creatorApp.appVersion?.(),
+      build: _creatorApp.appBuild?.(),
+      sdk: _creatorApp.runtimeVersion?.() ?? SDK_VERSION,
+    }
+  },
+  /** The RUNNING code: what the compiler stamped into this bundle's header. `updatedAt` is the
+   *  compile time — what the updater compares before replacing a bundle (an older one never
+   *  replaces a newer one), useful for an "about" screen or a support log. */
+  get bundle(): AppBundle {
+    return { sdk: SDK_VERSION, updatedAt: _creatorApp.bundleUpdatedAt?.() ?? undefined }
+  },
   /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
    *  hidden. `"active"` on hosts that don't track it. */
   get state(): AppState {

package/src/server/db/defineDb.ts

@@ -339,6 +339,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
   Object.defineProperties(db, {
     $schema: { get: () => seal().schema },
     $models: { get: () => seal().models },
+    $given: { get: () => own },
     $auth: { get: () => seal().auth },
     $files: { get: () => seal().files },
   })

package/src/server/db/types.ts

@@ -203,7 +203,11 @@ type DbBase<S extends Schema> = {
   $transaction<P extends readonly Op<any>[]>(ops: [...P]): Promise<{ [K in keyof P]: P[K] extends Op<infer T> ? T : never }>
   /** The `.marci` schema text this db syncs with. */
   readonly $schema: string
-  /** @internal */ readonly $models: Record<string, Model>
+  /** @internal the models as the schema has them — a model with a `t.file()` field carries the files' relation. */
+  readonly $models: Record<string, Model>
+  /** @internal the models as `defineDb` received them, by their names here — the objects the project holds,
+   *  so a host can tell which name the project gave a model it knows by identity. */
+  readonly $given: Record<string, Model>
   /** @internal the collections sign-in works on; null = a db without `withAuth`. */
   readonly $auth: AuthBinding | null
   /** @internal the schema's `t.file()` fields (../files/models.ts). */

package/src/server/runtime.ts

@@ -40,9 +40,12 @@ export const loadServerModules = (
   if (!reg) throw new Error("loadServerModules: no server bundle registered (globalThis.__lecodesServer)")
   const out: LoadedServer = { endpoints: new Map(), channels: new Map(), dbs: [], manifest: reg.manifest }
   for (const [mod, exports] of Object.entries(reg.modules)) {
+    // the compile's word on each export (serverSplit.ts): a function that is not async is the
+    // server's helper, never an endpoint — an old manifest without kinds counts every function
+    const kinds = new Map((reg.manifest?.modules?.[mod] ?? []).map(e => [e.name, e.kind]))
     for (const [name, value] of Object.entries(exports)) {
       const id = `${mod}#${name}`
-      if (typeof value === "function") out.endpoints.set(id, value as (...args: any[]) => unknown)
+      if (typeof value === "function") { if (kinds.get(name) !== "other") out.endpoints.set(id, value as (...args: any[]) => unknown) }
       else if (isChannel(value)) { value.__id = id; out.channels.set(id, value) }
       else if (isDb(value)) out.dbs.push(value)
     }

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.0.12"
+export const SDK_VERSION = "2.1.0"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/tests/helpers/hostStubs.ts

@@ -15,13 +15,22 @@ export const storageStub: any = {}
 export const mediaStub: any = {}
 export const inputStub: any = {}
 
-const g = globalThis as any
-g._creatorApp = appStub
-g._creatorDevice = deviceStub
-g._creatorFetch = fetchStub
-g._creatorStorage = storageStub
-g._creatorMedia = mediaStub
-g._creatorInput = inputStub
+// Installed as accessors whose setter THROWS: a file that assigns the global (instead of mutating
+// the stub) fails on its own line, not fifteen files later in whoever reads `_creatorFetch.fetch`
+// next (the symptom of 2026-10-10: a replaced `_creatorFetch` broke rpc, channel, image and scene
+// tests under every other seed).
+const tables: [string, any][] = [
+  ["_creatorApp", appStub], ["_creatorDevice", deviceStub], ["_creatorFetch", fetchStub],
+  ["_creatorStorage", storageStub], ["_creatorMedia", mediaStub], ["_creatorInput", inputStub],
+]
+for (const [name, stub] of tables) {
+  Object.defineProperty(globalThis, name, {
+    get: () => stub,
+    set: () => { throw new Error(`${name} is a shared stub: mutate it (Object.assign / set a member, resetHostStubs()), never replace the global — tests/helpers/hostStubs.ts`) },
+    configurable: false,
+    enumerable: true,
+  })
+}
 
 /** Empty every stub table (the members a previous test / file installed). */
 export const resetHostStubs = () => {