lecodes-sdk 0.19.0

package/src/compile/shaderSchema.ts

@@ -0,0 +1,202 @@
+// .mat source → the shader's PARAMETER SCHEMA: what the scene editor's material card renders and
+// what `lecodes shaders` prints. Filament's material block carries name + type only, so the rest
+// (widget kind, range, default, tooltip) comes from ANNOTATIONS in the comment that follows each
+// parameter entry — the same trailing comments shader authors already write:
+//
+//   parameters : [
+//       { type : float3,    name : tint },     // @color what the coating does to the world behind it
+//       { type : float,     name : opacity },  // @range(0, 1) @default(0.22) how much the glass darkens
+//       { type : sampler2d, name : mask },     // the reticle mask, white on alpha
+//   ]
+//
+// Tags: `@color` (float3/float4 = a colour picker; `@vec` forces the plain vector — without either,
+// a float3/float4 whose NAME reads like a colour is one), `@range(min, max)` (slider), `@step(s)`,
+// `@default(v)` (a number, `#hex`, `[x, y, z]`, `true`/`false`). Whatever text is left is the
+// tooltip. A full-line comment directly above the entry counts too. Unknown tags are ignored; a
+// malformed one lands in `errors` and the parameter still lists.
+//
+// Built on liteMaterial's block extraction + relaxed-JSON parser (the ONLY .mat syntax knowledge
+// in the repo — do not fork it). Dependency-free, browser-safe, never throws.
+
+import { extractMatBlocks, parseJsonish, type JsonishValue } from "./liteMaterial"
+
+export type ShaderParamEditor =
+  | "number" | "int" | "switch" | "vec2" | "vec3" | "vec4" | "color" | "texture" | "matrix" | "array"
+
+export type ShaderParamValue = number | boolean | string | number[] | null
+
+export type ShaderParam = {
+  name: string
+  /** filament type name, verbatim (float, float3, sampler2d, …) */
+  type: string
+  /** array parameters ("float[9]") */
+  size?: number
+  editor: ShaderParamEditor
+  /** The value a new material starts with (from `@default`, else the type's zero — white for a colour). */
+  default: ShaderParamValue
+  min?: number
+  max?: number
+  step?: number
+  tooltip?: string
+}
+
+export type ShaderSchema = {
+  name: string
+  shadingModel: string
+  blending: string
+  params: ShaderParam[]
+  errors: string[]
+}
+
+const SAMPLER_TYPES = new Set([ "sampler2d", "samplerExternal", "sampler2dArray", "samplerCubemap", "sampler3d" ])
+const COLOR_NAME = /colou?r|tint|albedo|emissive|glare|glow/i
+
+const zeroFor = (type: string, editor: ShaderParamEditor): ShaderParamValue => {
+  switch (editor) {
+    case "number": return 0
+    case "int": return 0
+    case "switch": return false
+    case "vec2": return [ 0, 0 ]
+    case "vec3": return [ 0, 0, 0 ]
+    case "vec4": return [ 0, 0, 0, 0 ]
+    case "color": return type === "float4" ? "#ffffffff" : "#ffffff"
+    case "texture": return null
+    default: return null
+  }
+}
+
+/** Parse one `@default(...)` payload. */
+const parseDefault = (raw: string, editor: ShaderParamEditor): ShaderParamValue | undefined => {
+  const s = raw.trim()
+  if (s === "true") return true
+  if (s === "false") return false
+  if (/^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(s)) return s.toLowerCase()
+  if (/^-?\d+(\.\d+)?$/.test(s)) return editor === "switch" ? Number(s) !== 0 : Number(s)
+  const arr = /^\[(.*)\]$/.exec(s)
+  if (arr) {
+    const nums = arr[1]!.split(",").map((p) => Number(p.trim()))
+    if (nums.length > 0 && nums.every((n) => Number.isFinite(n))) return nums
+  }
+  return undefined
+}
+
+type Annotation = { color?: boolean, vec?: boolean, range?: [number, number], step?: number, default?: string, tooltip: string, errors: string[] }
+
+/** Split a comment into tags + the remaining tooltip text. */
+const parseAnnotation = (comment: string): Annotation => {
+  const out: Annotation = { tooltip: "", errors: [] }
+  let rest = comment
+  rest = rest.replace(/@(color|vec)\b/g, (_m, tag: string) => { out[tag as "color" | "vec"] = true; return " " })
+  rest = rest.replace(/@(range|step|default)\s*\(([^)]*)\)/g, (_m, tag: string, body: string) => {
+    if (tag === "range") {
+      const parts = body.split(",").map((p) => Number(p.trim()))
+      if (parts.length === 2 && parts.every((n) => Number.isFinite(n))) out.range = [ parts[0]!, parts[1]! ]
+      else out.errors.push(`@range expects two numbers, got "${body.trim()}"`)
+    } else if (tag === "step") {
+      const n = Number(body.trim())
+      if (Number.isFinite(n) && n > 0) out.step = n
+      else out.errors.push(`@step expects a positive number, got "${body.trim()}"`)
+    } else {
+      out.default = body
+    }
+    return " "
+  })
+  rest = rest.replace(/@\w+(\([^)]*\))?/g, " ")   // unknown tags: dropped
+  out.tooltip = rest.replace(/\s+/g, " ").trim()
+  return out
+}
+
+/** The comment attached to each parameter entry, by parameter name: the trailing `//` on the
+ *  entry's line, else the full-line comment(s) directly above it. Scans the raw block text
+ *  (the relaxed-JSON parser drops comments). */
+const collectComments = (materialBlock: string): Map<string, string> => {
+  const out = new Map<string, string>()
+  const start = materialBlock.search(/\bparameters\s*[:=]/)
+  if (start < 0) return out
+  const lines = materialBlock.slice(start).split("\n")
+  let above: string[] = []
+  for (const line of lines) {
+    const trimmed = line.trim()
+    const name = /\bname\s*[:=]\s*"?([A-Za-z_]\w*)"?/.exec(line)?.[1]
+    if (name) {
+      const trailing = /\}[^/\n]*\/\/(.*)$/.exec(line)?.[1] ?? /\/\/(.*)$/.exec(line.slice(line.indexOf("}") + 1))?.[1]
+      const text = trailing !== undefined ? trailing : above.join(" ")
+      if (text.trim() !== "") out.set(name, text.trim())
+      above = []
+    } else if (trimmed.startsWith("//")) {
+      above.push(trimmed.slice(2).trim())
+    } else if (trimmed !== "" && trimmed !== "[" && trimmed !== "],") {
+      above = []
+    }
+  }
+  return out
+}
+
+/** Parse a `.mat` source into its parameter schema. Never throws: an unreadable file yields an
+ *  empty schema whose `errors` say why. */
+export const parseShaderSchema = (text: string): ShaderSchema => {
+  const schema: ShaderSchema = { name: "", shadingModel: "lit", blending: "opaque", params: [], errors: [] }
+  let block: string | undefined
+  let def: Record<string, JsonishValue>
+  try {
+    block = extractMatBlocks(text).material
+    if (block === undefined) { schema.errors.push("no material block"); return schema }
+    def = parseJsonish("{" + block + "}")
+  } catch (e) {
+    schema.errors.push(e instanceof Error ? e.message : String(e))
+    return schema
+  }
+  schema.name = typeof def.name === "string" ? def.name : ""
+  schema.shadingModel = typeof def.shadingModel === "string" ? def.shadingModel : "lit"
+  schema.blending = typeof def.blending === "string" ? def.blending : "opaque"
+
+  const comments = collectComments(block)
+  const rawParams = def.parameters === undefined ? [] : Array.isArray(def.parameters) ? def.parameters : [ def.parameters ]
+  for (const raw of rawParams) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) { schema.errors.push("malformed parameter entry"); continue }
+    const entry = raw as Record<string, JsonishValue>
+    const name = String(entry.name ?? "")
+    const typeRaw = String(entry.type ?? "")
+    const typeMatch = /^(\w+)(?:\[(\d+)\])?$/.exec(typeRaw)
+    if (!name || !typeMatch) { schema.errors.push(`malformed parameter "${name || typeRaw}"`); continue }
+    const type = typeMatch[1]!
+    const size = typeMatch[2] ? Number(typeMatch[2]) : undefined
+    const ann = parseAnnotation(comments.get(name) ?? "")
+    for (const e of ann.errors) schema.errors.push(`${name}: ${e}`)
+
+    let editor: ShaderParamEditor
+    if (size !== undefined) editor = "array"
+    else if (SAMPLER_TYPES.has(type)) editor = "texture"
+    else if (type === "float") editor = "number"
+    else if (type === "int" || type === "uint") editor = "int"
+    else if (type === "bool") editor = "switch"
+    else if (type === "float2") editor = "vec2"
+    else if (type === "float3" || type === "float4") {
+      const isColor = ann.color === true || (ann.vec !== true && COLOR_NAME.test(name))
+      editor = isColor ? "color" : type === "float3" ? "vec3" : "vec4"
+    } else if (/^(int|uint|bool)[234]$/.test(type)) editor = `vec${type.slice(-1)}` as ShaderParamEditor
+    else if (/^float[234]x[234]$/.test(type)) editor = "matrix"
+    else editor = "array"
+
+    const param: ShaderParam = { name, type, editor, default: zeroFor(type, editor) }
+    if (size !== undefined) param.size = size
+    if (ann.range) { param.min = ann.range[0]; param.max = ann.range[1] }
+    if (ann.step !== undefined) param.step = ann.step
+    if (ann.default !== undefined) {
+      const v = parseDefault(ann.default, editor)
+      if (v === undefined) schema.errors.push(`${name}: unreadable @default(${ann.default.trim()})`)
+      else param.default = v
+    }
+    if (ann.tooltip) param.tooltip = ann.tooltip
+    schema.params.push(param)
+  }
+  return schema
+}
+
+/** The parameter values a NEW material starts with for this shader (the schema defaults, textures
+ *  left out — an unset sampler stays the engine's white). */
+export const shaderDefaults = (schema: ShaderSchema): Record<string, ShaderParamValue> => {
+  const out: Record<string, ShaderParamValue> = {}
+  for (const p of schema.params) if (p.editor !== "texture" && p.default !== null) out[p.name] = p.default
+  return out
+}

package/src/compile/shaderTargets.ts

@@ -0,0 +1,77 @@
+// The one shader-compile target matrix, shared by the backend's server-side compile
+// (backend/src/utils/compileShader.ts) and the CLI's local compile (lecodes-cli
+// src/compile/shaders.ts). Both must produce the SAME artifact family for a .mat source —
+// the compiled bundle derives per-backend URLs by substituting `_creator.backend` into the
+// opengl src (compileProject.ts), so the set of names is ABI.
+
+export const externalSamplerReg = /type\s*:\s*samplerExternal/g
+
+// matc invocation per target. `profile` is matc's -p (mobile = shader model MOBILE / ESSL3,
+// desktop = shader model DESKTOP / GLSL 4.1); `api` is -a. The Windows desktop host runs OpenGL
+// without external (OES) sampler support, so it gets samplerExternal rewritten to sampler2d. The
+// desktop variant exists because the desktop Filament engine rejects the mobile _opengl shader
+// ("not built for desktop"); _creator.backend returns "desktop" there.
+//
+// The web runtime (Filament wasm) loads the mobile `_opengl` artifact as-is: the engine rewrites
+// `samplerExternalOES` to `sampler2D` at shader-compile time on contexts without
+// OES_EGL_image_external_essl3 (fork commit `lecodes 0020`), so WebGL needs no artifact of its own.
+// The former `webgl` target (a source-rewritten copy of the mobile build) is gone since 2026-08-29.
+//
+// These names are opaque identities for a (profile, api, rewrite) triple, not API names — hence
+// "opengl" (mobile profile) and "desktop" (desktop profile) both being OpenGL. Their only job is to
+// be stable and unique: the runtime substitutes one into `<hash>_<name>.filamat`.
+export const PLATFORM_BUILD = {
+  opengl:  { profile: "mobile",  api: "opengl", replaceExternal: false },
+  metal:   { profile: "mobile",  api: "metal",  replaceExternal: false },
+  desktop: { profile: "desktop", api: "opengl", replaceExternal: true },
+} as const
+export type MatcPlatform = keyof typeof PLATFORM_BUILD
+
+// Targets the CLI compiles LOCALLY and the platform does not. Deliberately a separate table, not
+// another PLATFORM_BUILD entry: `MatcPlatform` feeds the backend's `Platform` type, which is checked
+// against the `shaderPlatform` pg enum — widening it would break the backend's inserts at compile
+// time for a value the server never produces. Keep local-only targets here until the platform grows
+// the matching enum value (docs/desktop-vulkan-release-plan.md §4 "Known limitation").
+//
+// 'desktop-vulkan' = the Windows Vulkan desktop host: same DESKTOP shader model as 'desktop' but
+// SPIR-V, and the two are not interchangeable — Filament rejects a foreign one outright ("not built
+// for any of the OpenGL backend's supported shader languages"). `_creator.backend` returns
+// "desktop-vulkan" on that host.
+export const LOCAL_PLATFORM_BUILD = {
+  "desktop-vulkan": { profile: "desktop", api: "vulkan", replaceExternal: true },
+} as const
+export type LocalMatcPlatform = keyof typeof LOCAL_PLATFORM_BUILD
+
+/** Every matc target, local-only ones included — the lookup table for matcArgs. */
+export const ALL_PLATFORM_BUILD = { ...PLATFORM_BUILD, ...LOCAL_PLATFORM_BUILD }
+export type AnyMatcPlatform = MatcPlatform | LocalMatcPlatform
+
+/** The local-only targets, as a list (order matters where it feeds an artifact family). */
+export const LOCAL_ONLY_PLATFORMS: LocalMatcPlatform[] = ["desktop-vulkan"]
+
+// 'webgl-lite' is not a matc target: viewer-lite gets a JSON artifact (parsed .mat — see
+// liteMaterial.ts) that it wraps in its own GLSL template at runtime. `_creator.backend` is
+// "webgl-lite" on that host.
+export type ShaderPlatform = MatcPlatform | "webgl-lite"
+
+/** Every platform the LOCAL compile can produce (matc targets + the lite JSON). */
+export type AnyShaderPlatform = AnyMatcPlatform | "webgl-lite"
+
+/** Bump when the matc invocation for an EXISTING target name changes (a different -p/-a/rewrite for
+ *  a name that already exists). The CLI folds this into its artifact cache key, so such a change
+ *  invalidates caches that would otherwise look complete — adding or removing a target name is
+ *  already caught by the artifact-family check, but changing the argv behind a name is not.
+ *  1 = 'desktop-vulkan' added (2026-08-24). */
+export const TARGET_MATRIX_GENERATION = 1
+
+/** The matc platforms every .mat source is compiled for — the SERVER's contract. It deliberately
+ *  does not include LOCAL_ONLY_PLATFORMS; the CLI appends those itself (lecodes-cli
+ *  src/compile/shaders.ts). opengl leads: its src is the template the bundle substitutes the
+ *  runtime backend into. */
+export const MATC_PLATFORMS: MatcPlatform[] = ["opengl", "metal", "desktop"]
+
+/** The matc argv (without the executable) for one target. */
+export const matcArgs = (platform: AnyMatcPlatform, outPath: string, inPath: string): string[] => {
+  const build = ALL_PLATFORM_BUILD[platform]
+  return ["-p", build.profile, "--no-essl1", "-a", build.api, "-o", outPath, inPath]
+}

package/src/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}