lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/compile/index.ts

@@ -28,6 +28,37 @@ export {
   type ScanModule,
 } from "./detectEntry"
 export { sanitizeAssetName, isCanonicalAssetName } from "./assetName"
+export {
+  PLATFORM_BUILD,
+  LOCAL_PLATFORM_BUILD,
+  ALL_PLATFORM_BUILD,
+  LOCAL_ONLY_PLATFORMS,
+  TARGET_MATRIX_GENERATION,
+  externalSamplerReg,
+  matcPlatformsFor,
+  matcArgs,
+  type MatcPlatform,
+  type LocalMatcPlatform,
+  type AnyMatcPlatform,
+  type ShaderPlatform,
+  type AnyShaderPlatform,
+} from "./shaderTargets"
+export {
+  buildLiteMaterialArtifact,
+  extractMatBlocks,
+  parseJsonish,
+  type LiteMaterialArtifact,
+  type LiteMaterialParam,
+  type JsonishValue,
+} from "./liteMaterial"
+export {
+  parseShaderSchema,
+  shaderDefaults,
+  type ShaderSchema,
+  type ShaderParam,
+  type ShaderParamEditor,
+  type ShaderParamValue,
+} from "./shaderSchema"
 export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
 export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {

package/runtime/sdk/compile/liteMaterial.ts

@@ -0,0 +1,247 @@
+// .mat source → Web Lite material artifact.
+//
+// matc validates and compiles the .mat for the native platforms; the lite web runtime
+// (packages/viewer-lite) has no Filament, so it gets this JSON artifact instead: the parsed
+// material definition (parameters, shading model, blending) plus the author's fragment body with
+// `materialParams.x` rewritten to `materialParams_x`. viewer-lite wraps that body in its own GLSL
+// template (src/gl/customMaterial.ts mirrors the artifact type) — GLSL knowledge stays there, this
+// module only owns .mat syntax.
+//
+// The parsed `params`/`samplers` lists are deliberately structured (filament type names kept
+// verbatim): they are also the metadata a future "typed materials" codegen needs — generating a
+// Material subclass with typed uniform setters straight from the shader's parameter list.
+//
+// This module is dependency-free and must never throw: an exotic material becomes an
+// `unsupported` artifact (viewer-lite falls back to unlit + warning), never a failed shader save.
+
+export type LiteMaterialParam = {
+  name: string
+  /** filament type name: float, float2..4, int..4, bool..4, float3x3, float4x4 */
+  type: string
+  /** array parameters ("float[9]") */
+  size?: number
+}
+
+export type LiteMaterialArtifact = {
+  lecodesLiteMaterial: 1
+  shadingModel: "lit" | "unlit"
+  blending: "opaque" | "transparent" | "fade" | "add" | "masked"
+  maskThreshold: number
+  doubleSided: boolean
+  culling: "back" | "front" | "none"
+  depthWrite: boolean
+  /** Filament's shadow-catcher flag (unlit only, transparency mandatory — matc enforces both):
+   *  the fragment shows baseColor scaled by the received shadow amount, transparent elsewhere. */
+  shadowMultiplier: boolean
+  params: LiteMaterialParam[]
+  /** sampler2d / samplerExternal parameters — all become sampler2D in lite */
+  samplers: { name: string }[]
+  /** the author's fragment block body, `materialParams.x` rewritten to `materialParams_x` */
+  fragmentCode: string
+  /** the fragment writes MaterialInputs.normal — the template adds the tangent-frame transform */
+  writesNormal: boolean
+  /** a vertex{} block was present and dropped (lite ignores custom vertex stages) */
+  hasVertexBlock: boolean
+  /** set when the material can't run in lite at all (parse failure, unsupported param type) */
+  unsupported?: string
+}
+
+// ---- .mat block extraction ----------------------------------------------------------------------
+
+/** Split a .mat file into its top-level `name { ... }` blocks (material / fragment / vertex),
+ *  matching braces while skipping comments so `{` inside GLSL or comments can't derail it. */
+export const extractMatBlocks = (text: string): Record<string, string> => {
+  const blocks: Record<string, string> = {}
+  let i = 0
+  const skipNoise = (): void => {
+    for (;;) {
+      while (i < text.length && /\s/.test(text[i]!)) i++
+      if (text[i] === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++ }
+      else if (text[i] === "/" && text[i + 1] === "*") {
+        i += 2
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
+        i += 2
+      } else return
+    }
+  }
+  while (i < text.length) {
+    skipNoise()
+    const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(i))
+    if (!m) { i++; continue }
+    i += m[0].length
+    skipNoise()
+    if (text[i] !== "{") continue
+    // brace-match the block body, comment-aware
+    let depth = 0
+    const start = i
+    while (i < text.length) {
+      const c = text[i]
+      if (c === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++ }
+      else if (c === "/" && text[i + 1] === "*") {
+        i += 2
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
+        i++ // lands on '/', loop increment steps past
+      }
+      else if (c === "{") depth++
+      else if (c === "}") { depth--; if (depth === 0) break }
+      i++
+    }
+    blocks[m[0]] = text.slice(start + 1, i)
+    i++
+  }
+  return blocks
+}
+
+// ---- "jsonish" material-block parser --------------------------------------------------------------
+// matc's material block is relaxed JSON: unquoted keys/values, comments, optional commas, and both
+// `:` and `=` as separators. Small recursive-descent parser over that grammar.
+
+export type JsonishValue = string | number | boolean | JsonishValue[] | { [key: string]: JsonishValue }
+
+export const parseJsonish = (src: string): Record<string, JsonishValue> => {
+  let i = 0
+  const fail = (msg: string): never => { throw new Error(`material block: ${msg} at offset ${i}`) }
+  const skip = (): void => {
+    for (;;) {
+      while (i < src.length && /[\s,]/.test(src[i]!)) i++
+      if (src[i] === "/" && src[i + 1] === "/") { while (i < src.length && src[i] !== "\n") i++ }
+      else if (src[i] === "/" && src[i + 1] === "*") {
+        i += 2
+        while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) i++
+        i += 2
+      } else return
+    }
+  }
+  const quoted = (q: string): string => {
+    i++
+    const start = i
+    while (i < src.length && src[i] !== q) i++
+    return src.slice(start, i++)
+  }
+  const word = (): string => {
+    const m = /^[^\s{}[\]:,="']+/.exec(src.slice(i))
+    if (!m) fail("expected a value")
+    i += m![0].length
+    return m![0]
+  }
+  const value = (): JsonishValue => {
+    skip()
+    const c = src[i]
+    if (c === "{") return object()
+    if (c === "[") return array()
+    if (c === '"' || c === "'") return quoted(c)
+    const w = word()
+    if (w === "true") return true
+    if (w === "false") return false
+    const n = Number(w)
+    return Number.isNaN(n) ? w : n
+  }
+  const array = (): JsonishValue[] => {
+    i++ // [
+    const out: JsonishValue[] = []
+    for (;;) {
+      skip()
+      if (i >= src.length) fail("unterminated array")
+      if (src[i] === "]") { i++; return out }
+      out.push(value())
+    }
+  }
+  const object = (): Record<string, JsonishValue> => {
+    i++ // {
+    const out: Record<string, JsonishValue> = {}
+    for (;;) {
+      skip()
+      if (i >= src.length) fail("unterminated object")
+      if (src[i] === "}") { i++; return out }
+      const key = src[i] === '"' || src[i] === "'" ? quoted(src[i]!) : word()
+      skip()
+      if (src[i] !== ":" && src[i] !== "=") fail(`expected ':' after key "${key}"`)
+      i++
+      out[key] = value()
+    }
+  }
+  skip()
+  if (src[i] !== "{") fail("expected '{'")
+  return object()
+}
+
+// ---- artifact builder -----------------------------------------------------------------------------
+
+const PARAM_TYPES = new Set([
+  "float", "float2", "float3", "float4",
+  "int", "int2", "int3", "int4",
+  "bool", "bool2", "bool3", "bool4",
+  "float3x3", "float4x4",
+])
+const SAMPLER_TYPES = new Set(["sampler2d", "samplerExternal"])
+
+const unsupported = (reason: string): LiteMaterialArtifact => ({
+  lecodesLiteMaterial: 1, unsupported: reason,
+  shadingModel: "unlit", blending: "opaque", maskThreshold: 0.4,
+  doubleSided: false, culling: "back", depthWrite: true, shadowMultiplier: false,
+  params: [], samplers: [], fragmentCode: "", writesNormal: false, hasVertexBlock: false,
+})
+
+export const buildLiteMaterialArtifact = (text: string): LiteMaterialArtifact => {
+  try {
+    const blocks = extractMatBlocks(text)
+    if (blocks.material === undefined) return unsupported("no material block")
+    if (blocks.fragment === undefined) return unsupported("no fragment block")
+    const def = parseJsonish("{" + blocks.material + "}")
+
+    const params: LiteMaterialParam[] = []
+    const samplers: { name: string }[] = []
+    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)) return unsupported("malformed parameter entry")
+      const name = String((raw as Record<string, JsonishValue>).name ?? "")
+      const typeRaw = String((raw as Record<string, JsonishValue>).type ?? "")
+      const typeMatch = /^(\w+)(?:\[(\d+)\])?$/.exec(typeRaw)
+      if (!name || !typeMatch) return unsupported(`malformed parameter "${name || typeRaw}"`)
+      const [, type, size] = typeMatch
+      if (SAMPLER_TYPES.has(type!)) {
+        if (size) return unsupported(`sampler arrays are not supported ("${name}")`)
+        samplers.push({ name })
+      } else if (PARAM_TYPES.has(type!)) {
+        params.push(size ? { name, type: type!, size: Number(size) } : { name, type: type! })
+      } else {
+        return unsupported(`parameter type "${typeRaw}" ("${name}")`)
+      }
+    }
+
+    // cloth/subsurface/specularGlossiness approximate as lit — better than refusing outright.
+    const shadingModel = def.shadingModel === "unlit" ? "unlit" : "lit"
+    const blendingRaw = String(def.blending ?? "opaque")
+    const blending =
+      blendingRaw === "transparent" || blendingRaw === "fade" || blendingRaw === "add" || blendingRaw === "masked"
+        ? blendingRaw
+        : blendingRaw === "multiply" || blendingRaw === "screen" ? "transparent" // approximate
+        : "opaque"
+    const culling = def.culling === "none" ? "none" : def.culling === "front" ? "front" : "back"
+    // Filament defaults: depth write on except for transparent/fade blending.
+    const depthWrite = typeof def.depthWrite === "boolean" ? def.depthWrite
+      : blending !== "transparent" && blending !== "fade" && blending !== "add"
+
+    const fragmentCode = blocks.fragment.replace(/\bmaterialParams\./g, "materialParams_")
+    if (!/\bvoid\s+material\s*\(/.test(fragmentCode)) return unsupported("fragment block has no material() function")
+
+    return {
+      lecodesLiteMaterial: 1,
+      shadingModel,
+      blending,
+      maskThreshold: typeof def.maskThreshold === "number" ? def.maskThreshold : 0.4,
+      doubleSided: def.doubleSided === true,
+      culling,
+      depthWrite,
+      shadowMultiplier: def.shadowMultiplier === true,
+      params,
+      samplers,
+      fragmentCode,
+      writesNormal: /\.normal\s*=/.test(fragmentCode),
+      hasVertexBlock: blocks.vertex !== undefined,
+    }
+  } catch (e) {
+    return unsupported(e instanceof Error ? e.message : String(e))
+  }
+}

package/runtime/sdk/compile/sceneEditor.ts

@@ -66,13 +66,23 @@ export const sceneEditorEntries = (
     .filter((p) => p.endsWith(".editor.ts"))
     .map((p) => `import "${p}"\n`)
     .join("")
+  // Every material asset registers on `__lecodesMaterials` BY PROJECT PATH, so the editor can
+  // resolve a scene's `material: handle` reference (an import the doc sees as an identifier) to
+  // the live handle and edit it in place. Imports dedupe with the scene's own, so a material the
+  // scene uses is the same instance here.
+  const materialPaths = projectPaths.filter((p) => p.endsWith(".material.ts"))
+  const materialImports = materialPaths.map((p, i) => `import __mat${i} from "${p}"\n`).join("")
+  const materialRegister = materialPaths.length === 0 ? ""
+    : `;(globalThis as any).__lecodesMaterials = { ${materialPaths.map((p, i) => `${JSON.stringify(p)}: __mat${i}`).join(", ")} }\n`
   entries.push({
     path: SCENE_ENTRY_PATH,
     type: "text",
     text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
+      + materialImports
       + `import "${scenePath}"\n`
       + editorImports
-      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`,
+      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`
+      + materialRegister,
   })
   return entries
 }

package/runtime/sdk/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/runtime/sdk/compile/shaderTargets.ts

@@ -0,0 +1,81 @@
+// 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.subBackend ??
+// _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. WebGL and the Windows desktop host
+// both run OpenGL without external (OES) sampler support, so they get 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.
+//
+// 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 },
+  webgl:   { profile: "mobile",  api: "opengl", replaceExternal: true },
+  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.
+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 a .mat source needs compiled. WebGL is matc-compiled only when the shader
+ *  has an external sampler: its samplerExternal → sampler2d rewrite makes the output differ from
+ *  the mobile opengl build. Without one the WebGL artifact is byte-identical to the mobile shader,
+ *  so callers copy it from the opengl output instead of running matc again. Either way a _webgl
+ *  artifact must always exist — the web runtime always requests one (via _creator.subBackend).
+ *
+ *  This is the SERVER's contract — it deliberately does not include LOCAL_ONLY_PLATFORMS. The CLI
+ *  appends those itself (lecodes-cli src/compile/shaders.ts). */
+export const matcPlatformsFor = (text: string): MatcPlatform[] => {
+  externalSamplerReg.lastIndex = 0
+  return externalSamplerReg.test(text)
+    ? ["opengl", "metal", "webgl", "desktop"]
+    : ["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]
+}