lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/compile/shaderSchema.ts

@@ -1,202 +0,0 @@
-// .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

@@ -1,81 +0,0 @@
-// 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]
-}

package/runtime/sdk/compile/sourcemap.ts

@@ -1,25 +0,0 @@
-// 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}`
-}