lecodes-sdk 2.2.14 → 2.3.1

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.14",
+  "version": "2.3.1",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -127,9 +127,11 @@ declare global {
     setVignetteOptions?(sceneId: u32, enabled: boolean, midPoint: f32, roundness: f32, feather: f32, color: u32): void
     /** Colour grading: the operator and every adjustment baked into the view's ONE 3D LUT. `params` is
      *  the fixed layout of `sdk/src/gl/postProcessing.ts` (`CG_*`, mirrored by creator.h's
-     *  ColorGradingParam; 39 floats, the last one = apply the LUT of setColorLut). A change re-bakes a 32³ table on the CPU, so the SDK coalesces
-     *  its writes per tick and quantises; an identical array is a no-op in the engine. Optional: a
-     *  host that predates it renders filament's default (ACES legacy). */
+     *  ColorGradingParam; 41 floats: [38] = apply the LUT of setColorLut, [39] / [40] = the HDR look,
+     *  strength 0..1 and paper white 1..8, read only while the output is extended range). The engine
+     *  takes an older bundle's 39 with the HDR look at its defaults. A change re-bakes a 32³ table on
+     *  the CPU, so the SDK coalesces its writes per tick and quantises; an identical array is a no-op
+     *  in the engine. Optional: a host that predates it renders filament's default (ACES legacy). */
     setColorGrading?(sceneId: u32, params: Float32Array): void
     /** A custom 3D LUT after the operator, in display-referred sRGB: the TEXT of a `.cube` file
      *  (`LUT_3D_SIZE n` + n³ `r g b` lines, red fastest), parsed by the engine once and applied while
@@ -156,17 +158,7 @@ declare global {
      *  (1 = SDR), constant once the surface exists: the value to branch content on. Optional: hosts
      *  that predate it, or render 8-bit, are SDR. */
     getDisplayHeadroom?(): f64
-    /** @c getDisplayHeadroom */
     getDisplayMaxHeadroom?(): f64
-    /** HDR look, engine-wide (creator.h `setHdrStrength` / `setHdrPaperWhite`): `strength` 0..1 =
-     *  how much of the picture reaches for the headroom (0 only what SDR clipped, 1 nearly
-     *  everything), `paperWhite` 1..8 = where the operator's white lands as a multiple of SDR white
-     *  (the "HDR brightness" of a console calibration screen; clamped to the headroom). A host may
-     *  pin either from its environment — the getters report what is in force. Optional. */
-    setHdrStrength?(strength: f32): void
-    getHdrStrength?(): f64
-    setHdrPaperWhite?(paperWhite: f32): void
-    getHdrPaperWhite?(): f64
     /** Screen-space ambient occlusion: the contact darkening in creases and where objects meet the
      *  ground. `radius` is world-space metres, `power` the falloff contrast, `quality` 0 LOW … 3
      *  ULTRA (sample count — not the buffer resolution, which stays half-res).

package/src/compile/serverSplit.ts

@@ -13,6 +13,7 @@
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
+import { CODE_EXT } from "./assetMacro"
 import { bundleProjectWithMap, SERVER_INJECT, type MemoryFiles } from "./bundler"
 import type { CompileEntry } from "./compileProject"
 import { deriveEndpointParams } from "./serverTypes"
@@ -271,12 +272,18 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   // with a Figma-exported design next to app.server.ts). A stub's value is the resource's PATH: a
   // row of shared data that names a picture (`photo: "images/a.jpg"`) reaches the server as the
   // path of that picture, which a seed stores into a file field (files/db.ts). The board's `design/`
-  // files are never server code and stay out entirely.
+  // files are never server code and stay out entirely. A text file that is not code follows the
+  // app bundle's rules (compileProject.ts entriesToFiles): a `.json` is its parsed data — a shared
+  // module of a price list the person gave does `import raw from "./price.json"`, and the seed
+  // that imports the module ran into "raw is not defined" while the text went in as code — and any
+  // other text (.csv, .txt, .md) is its string.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
     const path = normalizePath(e.path)
     if (/^\/design\//.test(path)) continue
     if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ${JSON.stringify(path)}`; continue }
+    if (path.toLowerCase().endsWith(".json")) { files[path] = `export default ${e.text?.trim() || "null"}`; continue }
+    if (!CODE_EXT.test(path)) { files[path] = `export default ${JSON.stringify(e.text ?? "")}`; continue }
     files[path] = e.text ?? ""
   }
   let params = opts.params

package/src/gl/Scene.ts

@@ -12,7 +12,6 @@ import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOp
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
 import { _surfaceWidgets, type LayerElement, type WidgetSet } from "../ui/UILayer"
-import { device } from "../runtime/device"
 import { File } from "../runtime/fetch"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera } from "./Camera"
@@ -142,14 +141,6 @@ export type SceneOptions = {
    *  loses its top mip levels on load, a glTF image is downsampled. Applied before this scene's
    *  assets load; like `anisotropy` it does not touch textures already loaded. */
   maxTextureSize?: number
-  /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
-   *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
-   *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
-   *  1..8 is where white lands as a multiple of SDR white — the "HDR brightness" of a console
-   *  calibration screen, where 1.5–2 is the norm; default 1 keeps a white wall at the UI's white,
-   *  faithful but dim next to what "HDR on" is expected to look like. Engine-wide like `anisotropy`;
-   *  `device.hdr` is the runtime form and tells you whether the display has any headroom at all. */
-  hdr?: { strength?: number; paperWhite?: number }
 }
 
 // Route aspect update(dt) through the render-synced native phases (render() early = before physics,
@@ -253,10 +244,6 @@ export class Scene implements Presentable {
     // place by the time assets bind their samplers.
     if (options.anisotropy !== undefined) Texture.anisotropy = options.anisotropy
     if (options.maxTextureSize !== undefined) Texture.maxSize = options.maxTextureSize
-    if (options.hdr) {
-      if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
-      if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
-    }
     if (options.renderScale !== undefined || options.dynamicResolution) {
       this.setRenderOptions(options.renderScale ?? 1, options.dynamicResolution ?? false)
     }

package/src/gl/postProcessing.ts

@@ -12,12 +12,13 @@
 // 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).
+//    shadows / midtones / highlights, slope / offset / power, curves, the .cube LUT, the HDR look —
+//    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 (the HDR look to 0.05) 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).
@@ -134,6 +135,26 @@ export type ColorCurves = {
   highlightScale?: Rgb
 }
 
+/** The look on an HDR display — a screen with headroom above SDR white (Apple's XDR panels, an
+ *  external display in HDR mode), where the operator is stretched past SDR white toward the peak.
+ *  Ignored on SDR: stored, read back, nothing changes on screen (`device.hdr.available` says which
+ *  display this is). Part of the grading band — a change is a bake — and quantised to 0.05 steps. */
+export type HdrLook = {
+  /** How much of the picture reaches for the display's headroom, 0..1 (default 0.35). 0 touches only
+   *  what SDR clipped — the SDR grade kept exactly, but a mostly-mid-tone frame then looks flat next
+   *  to its one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit
+   *  exterior takes 1, a dim interior wants less. */
+  strength?: number
+  /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
+   *  console game's calibration screen, where 1.5–2 is the norm. It scales the WHOLE picture: at 1
+   *  a white wall is as bright as the UI's white (faithful, and dim next to what "HDR on" is
+   *  expected to look like), at 2 twice that, and highlights still climb above it (the engine keeps
+   *  `headroom / paperWhite` for them, clamped at the peak). `strength` decides how much of the
+   *  picture reaches for the peak; this decides where the picture starts — a game that wants to read
+   *  as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. */
+  paperWhite?: number
+}
+
 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
@@ -167,6 +188,11 @@ export type PostProcessingOptions = {
    *  the operator, in display-referred sRGB — a `.cube` file: `asset('./look.cube')`, or a bare
    *  staged filename. `null` removes it. */
   lut?: string | null
+  /** The look on an HDR display: `strength` 0..1 (how much of the picture reaches for the peak:
+   *  0 only what SDR clipped … 1 nearly everything; default 0.35), `paperWhite` 1..8 (where white
+   *  lands × SDR white — the console "HDR brightness", 1.5–2 the norm; default 1). Ignored on SDR.
+   *  An overlay takes its parent's, like the rest of the grading. */
+  hdr?: HdrLook
   /** `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. */
@@ -180,12 +206,13 @@ export type PostProcessingOptions = {
 }
 
 /** The float layout of `_creator.setColorGrading` — creator.h's ColorGradingParam. Indices never
- *  move; a new field goes at the end and COUNT grows. */
+ *  move; a new field goes at the end and COUNT grows (the engine takes an older bundle's shorter
+ *  array, down to the 39 before HDR_*, with the tail at its defaults). */
 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,
+  SHADOW_GAMMA: 29, MID_POINT: 32, HIGHLIGHT_SCALE: 35, LUT: 38, HDR_STRENGTH: 39, HDR_PAPER_WHITE: 40,
+  COUNT: 41,
 } as const
 
 const TONE_MAPPING_MODE: Record<ToneMappingOperator, number> = { aces: 0, neutral: 1, linear: 2, filmic: 3 }
@@ -196,6 +223,10 @@ 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 HDR look on the wire: clamped to its range and quantised to 0.05 — a slider must not re-bake a
+ *  32³ LUT per pixel of travel (the quantum is the SDK's; the engine only clamps). */
+const hdrStep = (v: number, min: number, max: number, d: number): number =>
+  Number.isFinite(v) ? Math.round(Math.min(max, Math.max(min, v)) * 20) / 20 : d
 
 /** The grading band, normalised: every field present. */
 type Grading = {
@@ -218,12 +249,15 @@ type Grading = {
   midPoint: Rgb
   highlightScale: Rgb
   lut: string | null
+  hdrStrength: number
+  hdrPaperWhite: number
 }
 
 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,
+  hdrStrength: 0.35, hdrPaperWhite: 1,
 })
 
 const BLOOM_DEFAULTS: Required<BloomOptions> = { intensity: 0.2, threshold: true, highlight: 1000, levels: 6, quality: "medium", lensFlare: false, dirt: null, dirtStrength: 0.2 }
@@ -279,6 +313,7 @@ export class PostProcessing {
     if (options.power !== undefined) this.power = options.power
     if (options.curves !== undefined) this.curves = options.curves
     if (options.lut !== undefined) this.lut = options.lut
+    if (options.hdr !== undefined) this.hdr = options.hdr
     this.flush()
     if (options.bloom !== undefined) this.bloom = options.bloom
     if (options.vignette !== undefined) this.vignette = options.vignette
@@ -348,6 +383,12 @@ export class PostProcessing {
   }
   get lut(): string | null { return this._g.lut }
   set lut(v: string | null) { this._g.lut = v; this._lutDirty = v !== this._sentLut; this._touch() }
+  get hdr(): Required<HdrLook> { return { strength: this._g.hdrStrength, paperWhite: this._g.hdrPaperWhite } }
+  set hdr(v: HdrLook) {
+    if (v.strength !== undefined) this._g.hdrStrength = v.strength
+    if (v.paperWhite !== undefined) this._g.hdrPaperWhite = v.paperWhite
+    this._touch()
+  }
 
   // ---- the live band: view options, written at once ----
 
@@ -445,6 +486,8 @@ export class PostProcessing {
     put3(CG.MID_POINT, g.midPoint)
     put3(CG.HIGHLIGHT_SCALE, g.highlightScale)
     p[CG.LUT] = g.lut !== null ? 1 : 0
+    p[CG.HDR_STRENGTH] = hdrStep(g.hdrStrength, 0, 1, 0.35)
+    p[CG.HDR_PAPER_WHITE] = hdrStep(g.hdrPaperWhite, 1, 8, 1)
     return p
   }
 }

package/src/runtime/device.ts

@@ -30,11 +30,8 @@ const onResize = (width: number, height: number): void => {
 
 // --- device.hdr state ---
 // The 3D bridge is a free global that a 2D-only bundle never defines — reach it defensively. Hosts
-// without the methods are SDR by definition; the look setters are remembered so the getters read
-// back what the app asked for.
+// without the methods are SDR by definition.
 const gl = (): typeof _creator | undefined => (typeof _creator !== "undefined" ? _creator : undefined)
-let hdrStrengthLocal = 0.35
-let hdrPaperWhiteLocal = 1
 // `hdrchange` is a poll: the engine quantises the headroom to half-stops, so a change is rare and
 // a 4 Hz timer (only while someone listens) is cheaper than a per-frame bridge call.
 const hdrListeners: HdrChangeCallback[] = []
@@ -202,11 +199,13 @@ export const device = {
       return new Vec3(g.x, -g.y, g.z)
     },
   },
-  /** The display's extended dynamic range — HDR. On a screen with headroom above SDR white (Apple's
-   *  XDR panels; the macOS host today) the 3D surface is float and the engine renders past 1.0:
-   *  1.0 is the white of the UI and of a diffuse white surface, and the sun, emissives and speculars
-   *  climb up to `headroom` times that. Everywhere else it is SDR: `available` false, `headroom` 1,
-   *  the look setters remembered but invisible.
+  /** The display's extended dynamic range — HDR: the FACTS about the display. On the macOS desktop
+   *  host, in a visible window on a screen with headroom above SDR white (Apple's XDR panels, an HDR
+   *  external display), the 3D surface is float and the engine renders past 1.0: 1.0 is the white of
+   *  the UI and of a diffuse white surface, and the sun, emissives and speculars climb up to
+   *  `headroom` times that. Everywhere else it is SDR (the other hosts, a hidden window, a render to
+   *  PNG): `available` false, `headroom` 1. The LOOK on such a display — how much of the picture
+   *  reaches for the peak, where white lands — is the scene's: `scene.postProcessing.hdr`.
    *
    *  Branch content on `available`, not on `headroom` — the live value ramps up from 1 over the
    *  first seconds after launch and follows the brightness keys. Particle `emissive` is the thing
@@ -230,34 +229,6 @@ export const device = {
       const v = gl()?.getDisplayHeadroom?.() ?? 1
       return v > 1 ? v : 1
     },
-    /** How much of the picture reaches for the headroom, 0..1 (default 0.35). 0 touches only what
-     *  SDR clipped — faithful to the SDR grade, but a mostly-mid-tone frame then looks flat next to
-     *  the one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit exterior
-     *  takes 1, a dim interior wants less. A host may pin it (`LECODES_HDR_STRENGTH`). */
-    get strength(): number {
-      return gl()?.getHdrStrength?.() ?? hdrStrengthLocal
-    },
-    set strength(v: number) {
-      const s = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.35
-      hdrStrengthLocal = s
-      gl()?.setHdrStrength?.(s)
-    },
-    /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
-     *  console game's calibration screen, where paper white sits at ~200 nits against SDR's ~100.
-     *  It scales the WHOLE picture: at 1 a white wall is as bright as the UI's white, at 2 it is
-     *  twice that, and highlights still climb above it (the engine keeps `headroom / paperWhite` for
-     *  them, clamped at the peak). `strength` decides how much of the picture reaches for the
-     *  peak; this decides where the picture starts. 1.5–2 is the console norm; a game that wants to
-     *  read as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. A host may
-     *  pin it (`LECODES_HDR_PAPER_WHITE`). */
-    get paperWhite(): number {
-      return gl()?.getHdrPaperWhite?.() ?? hdrPaperWhiteLocal
-    },
-    set paperWhite(v: number) {
-      const p = Number.isFinite(v) ? Math.min(8, Math.max(1, v)) : 1
-      hdrPaperWhiteLocal = p
-      gl()?.setHdrPaperWhite?.(p)
-    },
   },
   /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
    *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /

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.2.14"
+export const SDK_VERSION = "2.3.1"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {