lecodes-web-shared 2.0.0

package/src/canvas/gen/spec.ts

@@ -0,0 +1,201 @@
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ ae6bc30b952b — do not edit here.
+// Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
+// GENERATED by spec/generate.ts from spec/*.h — do not edit.
+
+export const SPEC_VERSION = 1
+
+export const LineJoin = {
+  MITER: 0,
+  ROUND: 1,
+  BEVEL: 2,
+} as const
+export type LineJoin = (typeof LineJoin)[keyof typeof LineJoin]
+export const LineJoinName: readonly string[] = ["miter", "round", "bevel"]
+
+export const LineCap = {
+  BUTT: 0,
+  ROUND: 1,
+  SQUARE: 2,
+} as const
+export type LineCap = (typeof LineCap)[keyof typeof LineCap]
+export const LineCapName: readonly string[] = ["butt", "round", "square"]
+
+export const TextAlign = {
+  LEFT: 0,
+  CENTER: 1,
+  RIGHT: 2,
+  START: 3,
+  END: 4,
+} as const
+export type TextAlign = (typeof TextAlign)[keyof typeof TextAlign]
+export const TextAlignName: readonly string[] = ["left", "center", "right", "start", "end"]
+
+export const TextBaseline = {
+  ALPHABETIC: 0,
+  TOP: 1,
+  MIDDLE: 2,
+  BOTTOM: 3,
+  HANGING: 4,
+  IDEOGRAPHIC: 5,
+} as const
+export type TextBaseline = (typeof TextBaseline)[keyof typeof TextBaseline]
+export const TextBaselineName: readonly string[] = ["alphabetic", "top", "middle", "bottom", "hanging", "ideographic"]
+
+export const FillRule = {
+  NONZERO: 0,
+  EVENODD: 1,
+} as const
+export type FillRule = (typeof FillRule)[keyof typeof FillRule]
+export const FillRuleName: readonly string[] = ["nonzero", "evenodd"]
+
+export const Spread = {
+  PAD: 0,
+  REFLECT: 1,
+  REPEAT: 2,
+} as const
+export type Spread = (typeof Spread)[keyof typeof Spread]
+export const SpreadName: readonly string[] = ["pad", "reflect", "repeat"]
+
+export const Gradient = {
+  LINEAR: 0,
+  RADIAL: 1,
+} as const
+export type Gradient = (typeof Gradient)[keyof typeof Gradient]
+export const GradientName: readonly string[] = ["linear", "radial"]
+
+export const Paint = {
+  COLOR: 0,
+  LINEAR: 1,
+  RADIAL: 2,
+} as const
+export type Paint = (typeof Paint)[keyof typeof Paint]
+export const PaintName: readonly string[] = ["color", "linear", "radial"]
+
+export const PathVerb = {
+  MOVE: 0,
+  LINE: 1,
+  QUAD: 2,
+  CUBIC: 3,
+  CLOSE: 4,
+} as const
+export type PathVerb = (typeof PathVerb)[keyof typeof PathVerb]
+export const PathVerbName: readonly string[] = ["move", "line", "quad", "cubic", "close"]
+
+export const ImageFormat = {
+  PNG: 0,
+  JPEG: 1,
+} as const
+export type ImageFormat = (typeof ImageFormat)[keyof typeof ImageFormat]
+export const ImageFormatName: readonly string[] = ["png", "jpeg"]
+
+/** The opcode stream: op id → the word after it. */
+export const OP = {
+  SAVE: 0,
+  RESTORE: 1,
+  TRANSLATE: 2,
+  SCALE: 3,
+  ROTATE: 4,
+  TRANSFORM: 5,
+  SET_TRANSFORM: 6,
+  RESET_TRANSFORM: 7,
+  GLOBAL_ALPHA: 8,
+  FILL_STYLE: 9,
+  STROKE_STYLE: 10,
+  FILL_GRADIENT: 11,
+  STROKE_GRADIENT: 12,
+  LINE_WIDTH: 13,
+  LINE_JOIN: 14,
+  LINE_CAP: 15,
+  MITER_LIMIT: 16,
+  LINE_DASH: 17,
+  LINE_DASH_OFFSET: 18,
+  FONT: 19,
+  TEXT_ALIGN: 20,
+  TEXT_BASELINE: 21,
+  LETTER_SPACING: 22,
+  PATH_BEGIN: 23,
+  PATH_CLOSE: 24,
+  MOVE_TO: 25,
+  LINE_TO: 26,
+  QUADRATIC_TO: 27,
+  BEZIER_TO: 28,
+  ARC: 29,
+  ARC_TO: 30,
+  ELLIPSE: 31,
+  RECT: 32,
+  ROUND_RECT: 33,
+  FILL: 34,
+  STROKE: 35,
+  CLIP: 36,
+  FILL_RECT: 37,
+  STROKE_RECT: 38,
+  CLEAR_RECT: 39,
+  FILL_TEXT: 40,
+  STROKE_TEXT: 41,
+  DRAW_IMAGE: 42,
+} as const
+export type OP = (typeof OP)[keyof typeof OP]
+/** Operand layout per op: `args` is one letter per fixed word (f float, i int, r string ref);
+ *  `repeat` is the group that follows the trailing count. */
+export const OP_ARGS: Record<number, { args: string, repeat: string }> = {
+  0: { args: "", repeat: "" },
+  1: { args: "", repeat: "" },
+  2: { args: "ff", repeat: "" },
+  3: { args: "ff", repeat: "" },
+  4: { args: "f", repeat: "" },
+  5: { args: "ffffff", repeat: "" },
+  6: { args: "ffffff", repeat: "" },
+  7: { args: "", repeat: "" },
+  8: { args: "f", repeat: "" },
+  9: { args: "r", repeat: "" },
+  10: { args: "r", repeat: "" },
+  11: { args: "iffffffi", repeat: "fr" },
+  12: { args: "iffffffi", repeat: "fr" },
+  13: { args: "f", repeat: "" },
+  14: { args: "i", repeat: "" },
+  15: { args: "i", repeat: "" },
+  16: { args: "f", repeat: "" },
+  17: { args: "i", repeat: "f" },
+  18: { args: "f", repeat: "" },
+  19: { args: "r", repeat: "" },
+  20: { args: "i", repeat: "" },
+  21: { args: "i", repeat: "" },
+  22: { args: "f", repeat: "" },
+  23: { args: "", repeat: "" },
+  24: { args: "", repeat: "" },
+  25: { args: "ff", repeat: "" },
+  26: { args: "ff", repeat: "" },
+  27: { args: "ffff", repeat: "" },
+  28: { args: "ffffff", repeat: "" },
+  29: { args: "fffffi", repeat: "" },
+  30: { args: "fffff", repeat: "" },
+  31: { args: "fffffffi", repeat: "" },
+  32: { args: "ffff", repeat: "" },
+  33: { args: "fffff", repeat: "" },
+  34: { args: "i", repeat: "" },
+  35: { args: "", repeat: "" },
+  36: { args: "i", repeat: "" },
+  37: { args: "ffff", repeat: "" },
+  38: { args: "ffff", repeat: "" },
+  39: { args: "ffff", repeat: "" },
+  40: { args: "rfff", repeat: "" },
+  41: { args: "rfff", repeat: "" },
+  42: { args: "iffffffff", repeat: "" },
+}
+export const OP_NAME: readonly string[] = ["save", "restore", "translate", "scale", "rotate", "transform", "setTransform", "resetTransform", "globalAlpha", "fillStyle", "strokeStyle", "fillGradient", "strokeGradient", "lineWidth", "lineJoin", "lineCap", "miterLimit", "lineDash", "lineDashOffset", "font", "textAlign", "textBaseline", "letterSpacing", "pathBegin", "pathClose", "moveTo", "lineTo", "quadraticTo", "bezierTo", "arc", "arcTo", "ellipse", "rect", "roundRect", "fill", "stroke", "clip", "fillRect", "strokeRect", "clearRect", "fillText", "strokeText", "drawImage"]
+
+/** The draw list: command id → the word after it. */
+export const DRAW = {
+  SET_TRANSFORM: 0,
+  SAVE: 1,
+  RESTORE: 2,
+  CLIP: 3,
+  FILL_PATH: 4,
+  STROKE_PATH: 5,
+  FILL_TEXT: 6,
+  STROKE_TEXT: 7,
+  DRAW_IMAGE: 8,
+  CLEAR_RECT: 9,
+} as const
+export type DRAW = (typeof DRAW)[keyof typeof DRAW]
+export const DRAW_NAME: readonly string[] = ["setTransform", "save", "restore", "clip", "fillPath", "strokePath", "fillText", "strokeText", "drawImage", "clearRect"]

package/src/sourcemapError.ts

@@ -0,0 +1,178 @@
+// Map runtime errors from a compiled bundle back to original source locations.
+//
+// The preview runs the bundle via `new Function(code)`, so the browser won't apply the bundle's
+// inline source map to stack frames automatically — we do it here. Two offsets are involved and both
+// are handled: the bundle carries an inline source map whose generated positions already include the
+// compile header (the backend shifts it), and `new Function` adds a constant wrapper offset that we
+// calibrate at runtime. Self-contained (a tiny VLQ decoder), so there's no extra dependency.
+
+type RawSourceMap = { version: number, sources: string[], mappings: string, sourcesContent?: (string | null)[] }
+type OrigPos = { source: string, line: number, column: number }
+export type MappedFrame = { fn: string | null, source: string, line: number, column: number }
+/** A runtime error from the preview. `native` errors come from the WASM engine (no JS source to map).
+ *  `nativeFrames` are the crash's decoded engine (C++) function names, top-first — filled in by a
+ *  follow-up emit once the wasm host has fetched its symbol map (see viewer's wasmCrashSymbolizer). */
+export type PreviewError = { message: string, frames: MappedFrame[], stack?: string, native?: boolean, detail?: string, nativeFrames?: string[] }
+
+/**
+ * Is this a native (WASM engine) error rather than a JS error from the user's bundle? Emscripten
+ * surfaces C++ exceptions/aborts as a bare number (a pointer), and WebAssembly traps as
+ * `WebAssembly.RuntimeError`; either way there's no JS source position to map. We deliberately do
+ * *not* treat an arbitrary frameless JS `Error` as native (that would hijack unrelated editor errors).
+ */
+export const isNativeError = (e: unknown): boolean => {
+  if (typeof e === "number" || typeof e === "bigint") return true
+  if (typeof WebAssembly !== "undefined" && e instanceof WebAssembly.RuntimeError) return true
+  const stack = e instanceof Error ? (e.stack ?? "") : ""
+  return /\bwasm\b|wasm-function|\.wasm/i.test(stack)
+}
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+const B64_INDEX: Record<string, number> = {}
+for (let i = 0; i < B64.length; i++) B64_INDEX[B64[i]!] = i
+
+/** Decode one comma-segment of base64-VLQ into signed ints. */
+const decodeVlq = (segment: string): number[] => {
+  const out: number[] = []
+  let shift = 0, value = 0
+  for (const ch of segment) {
+    const digit = B64_INDEX[ch]
+    if (digit === undefined) break
+    const more = digit & 32
+    value += (digit & 31) << shift
+    if (more) {
+      shift += 5
+    } else {
+      const negative = value & 1
+      value >>= 1
+      out.push(negative ? -value : value)
+      value = 0
+      shift = 0
+    }
+  }
+  return out
+}
+
+/** A minimal source-map consumer: original position for a generated (1-based line, 0-based column). */
+export class SourceMap {
+  private sources: string[]
+  // Per generated line: sorted segments [genCol, srcIdx, srcLine, srcCol].
+  private lines: number[][][]
+
+  constructor(raw: RawSourceMap) {
+    this.sources = raw.sources
+    this.lines = []
+    let srcIdx = 0, srcLine = 0, srcCol = 0
+    for (const lineStr of raw.mappings.split(";")) {
+      const segs: number[][] = []
+      let genCol = 0
+      if (lineStr) {
+        for (const segStr of lineStr.split(",")) {
+          const v = decodeVlq(segStr)
+          if (v.length === 0) continue
+          genCol += v[0]!
+          if (v.length >= 4) {
+            srcIdx += v[1]!
+            srcLine += v[2]!
+            srcCol += v[3]!
+            segs.push([ genCol, srcIdx, srcLine, srcCol ])
+          }
+        }
+      }
+      this.lines.push(segs)
+    }
+  }
+
+  originalPositionFor(line: number, column: number): OrigPos | null {
+    const segs = this.lines[line - 1]
+    if (!segs || segs.length === 0) return null
+    // Largest segment whose generated column is <= the queried column.
+    let best: number[] | null = null
+    for (const seg of segs) {
+      if (seg[0]! <= column) best = seg
+      else break
+    }
+    best ??= segs[0]!
+    const source = this.sources[best[1]!]
+    if (source === undefined) return null
+    return { source, line: best[2]! + 1, column: best[3]! }
+  }
+}
+
+/** Pull the inline `//# lecodesMap=data:...base64,…` map out of a bundle string (a non-standard
+ *  directive the browser ignores — see inlineSourceMapComment in the SDK for why). */
+export const extractInlineSourceMap = (code: string): SourceMap | null => {
+  const m = code.match(/\/\/# lecodesMap=data:application\/json;(?:charset=[^;]+;)?base64,([A-Za-z0-9+/=]+)\s*$/)
+  if (!m) return null
+  try {
+    const json = typeof atob === "function" ? atob(m[1]!) : Buffer.from(m[1]!, "base64").toString("utf8")
+    return new SourceMap(JSON.parse(json) as RawSourceMap)
+  } catch {
+    return null
+  }
+}
+
+// `new Function(body)` wraps the body in `function anonymous(args\n) {\n<body>\n}`, so the body starts
+// a constant number of lines down. Calibrate once per engine by throwing from a one-line body.
+let functionOffset: number | null = null
+const newFunctionLineOffset = (): number => {
+  if (functionOffset !== null) return functionOffset
+  try {
+    new Function("throw new Error('chisel-calibrate')")()
+  } catch (e) {
+    const stack = (e as Error).stack ?? ""
+    // The body coordinate is the `<anonymous>:line:col` one (V8/Chrome). A one-line body throws at
+    // body line 1, so its reported line minus 1 is the wrapper offset.
+    const m = stack.match(/<anonymous>:(\d+):\d+/)
+    functionOffset = m ? parseInt(m[1]!, 10) - 1 : 2
+    return functionOffset
+  }
+  functionOffset = 2
+  return functionOffset
+}
+
+/** Parse `error.stack`, mapping each `new Function` frame back to original source via `map`. */
+export const mapErrorStack = (error: unknown, map: SourceMap): MappedFrame[] => {
+  const stack = (error instanceof Error ? error.stack : "") ?? ""
+  const offset = newFunctionLineOffset()
+  const frames: MappedFrame[] = []
+  for (const raw of stack.split("\n")) {
+    // The user-bundle position is the `<anonymous>:line:col` coordinate (V8 gives body-relative
+    // lines here; an `eval at … (file:line)` prefix, if present, is the call site — not it).
+    const m = raw.match(/<anonymous>:(\d+):(\d+)/)
+    if (!m) continue
+    const genLine = parseInt(m[1]!, 10) - offset
+    const genCol = parseInt(m[2]!, 10) - 1
+    if (genLine < 1) continue
+    const orig = map.originalPositionFor(genLine, genCol < 0 ? 0 : genCol)
+    if (!orig) continue
+    const fnMatch = raw.match(/at\s+([^\s(]+)\s*\(/)
+    frames.push({ fn: fnMatch ? fnMatch[1]! : null, source: orig.source, line: orig.line, column: orig.column })
+  }
+  return frames
+}
+
+/** Rewrite every `<filename>:line:col` frame in a block of text to its original position.
+ *  This is the shape a host that EVALUATES the bundle as one named file produces — quickjs on the
+ *  native hosts (`module.js:5:51631`, see creatorUtilsHandler) and `vm.runInContext` in the headless
+ *  renderer (`project.js:…`) — as opposed to the preview's `new Function` frames above. Both report
+ *  1-based columns. Frames naming other files (a host's own launcher, `native`) pass through. */
+export const mapNamedFileStack = (text: string, map: SourceMap, filename: string): string => {
+  const escaped = filename.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return text.replace(new RegExp(`\\b${escaped}:(\\d+):(\\d+)`, "g"), (whole, l: string, c: string) => {
+    const orig = map.originalPositionFor(parseInt(l, 10), Math.max(0, parseInt(c, 10) - 1))
+    return orig ? `${orig.source.replace(/^(\.\/|\/)/, "")}:${orig.line}:${orig.column}` : whole
+  })
+}
+
+/** A one-line, human-readable original location for an error, or null if it can't be mapped. */
+export const formatErrorLocation = (error: unknown, code: string): { message: string, frames: MappedFrame[] } | null => {
+  const map = extractInlineSourceMap(code)
+  if (!map) return null
+  const frames = mapErrorStack(error, map)
+  if (frames.length === 0) return null
+  const top = frames[0]!
+  const msg = error instanceof Error ? error.message : String(error)
+  const where = `${top.source}:${top.line}:${top.column}${top.fn ? ` (${top.fn})` : ""}`
+  return { message: `${msg}\n    at ${where}`, frames }
+}

package/src/ui/nativeView.ts

@@ -0,0 +1,12 @@
+// NativeView on the web hosts (docs/navigation-presentable-plan.md): a factory makes the live DOM
+// instance of a view (`NativeView("name", params)`), the channel carries its events to the SDK
+// (`_creatorTree`'s view events), `call` is the method channel. Factories come from the web halves
+// of the plugins (a host is handed them: `host.registerPlugin`). `doc` is the document the app's DOM lives in, so
+// factories create elements in the right realm.
+export type WebViewChannel = { emit(event: string, data?: any): void }
+export type WebViewInstanceHandle = {
+  el: HTMLElement
+  call?(method: string, args: any[]): any | Promise<any>
+  destroy?(): void
+}
+export type WebViewFactory = (params: any, channel: WebViewChannel, doc: Document) => WebViewInstanceHandle

package/src/ui/safeAreaSpec.ts

@@ -0,0 +1,30 @@
+// Device-emulation safe-area override — the editor Simulator's iOS/Android shells. A host without
+// a spec keeps the neutral web defaults it has always used; a spec pins the insets per orientation
+// and declares which edges are exact-height system BARS (Android status/nav bar) — `comfort-*`
+// ADDS its knob past a bar edge instead of flooring against it (creator-ui setSafeAreaBars
+// semantics). Shell inset values live with the embedder (the frontend mirrors lecodes-design's
+// SHELL_SAFE_AREA / `lecodes render --device`).
+
+export type SafeAreaEdge = "top" | "right" | "bottom" | "left"
+
+export type SafeAreaSpec = {
+  /** [top, right, bottom, left] px */
+  portrait: [number, number, number, number]
+  landscape: [number, number, number, number]
+  portraitBars?: SafeAreaEdge[]
+  landscapeBars?: SafeAreaEdge[]
+}
+
+// The neutral defaults both web hosts have always simulated (portrait: top 20 / bottom 8).
+export const DEFAULT_SAFE_AREA: SafeAreaSpec = {
+  portrait: [20, 0, 8, 0],
+  landscape: [0, 8, 0, 20],
+}
+
+export const orientedSafeArea = (spec: SafeAreaSpec, landscape: boolean): {
+  insets: [number, number, number, number]
+  bars: SafeAreaEdge[]
+} => ({
+  insets: landscape ? spec.landscape : spec.portrait,
+  bars: (landscape ? spec.landscapeBars : spec.portraitBars) ?? [],
+})

package/src/ui/viewScale.ts

@@ -0,0 +1,19 @@
+// The effective on-screen scale of a host root, recovered from the DOM.
+//
+// The simulator displays the app at a fixed CSS `zoom` (default 0.75) so the preview matches a real
+// device while the app keeps its true logical viewport. Under `zoom` — and under a legacy
+// `transform: scale()` — an element's getBoundingClientRect() reports VISUAL px (post-scale) while
+// clientWidth/clientHeight stay LAYOUT px (the element's own coordinate space). Their ratio is the
+// effective scale a visual coordinate (e.g. a pointer's `clientX - rect.left`) must be divided by to
+// reach the app's logical space.
+//
+// This is the same computation createUI's getBoundingClientRect bridge already does
+// (appRect.width / displayWidth); factored out so every pointer path shares one definition.
+
+/** Visual-to-layout scale of `el` (guards a zero layout size → 1). */
+export const viewScale = (el: HTMLElement): number => {
+  const layout = el.clientWidth
+  if (!layout) return 1
+  const visual = el.getBoundingClientRect().width
+  return visual > 0 ? visual / layout : 1
+}

package/src/utils/fetch.ts

@@ -0,0 +1,162 @@
+// Slot 0 is reserved: 0 means "no buffer" in the host contract (HostFetch.putBuffer, a form's bufferId > 0).
+const arrayBuffers: ArrayBuffer[] = [null as unknown as ArrayBuffer]
+
+const decoder = new TextDecoder('utf-8');
+
+export const _fetch = async (url: string, fetchOptions: any, onComplete: (systemId: number, statusCode: number) => void, onReject: (err: Error) => void) => {
+  
+  let body: any = undefined
+  if (fetchOptions.body) {
+    if (typeof fetchOptions.body === "object" && Array.isArray(fetchOptions.body._entries)) {
+      const formData = new FormData()
+      for (let [key,value,filename] of fetchOptions.body._entries) {
+        if (typeof value === "object") {
+          formData.append(key, new Blob([ getBuffer(value._id) ]), filename)
+        } else {
+          formData.append(key, value)
+        }
+      }
+      body = formData
+    } else if (typeof fetchOptions.body === "string") {
+      body = fetchOptions.body
+    } else {
+      onReject(new Error("Invalid body"))
+    }
+  }
+  
+  const resp = await fetch(url, {
+    method: fetchOptions.method,
+    body,
+    headers: fetchOptions.headers,
+    mode: "cors",
+    credentials: "omit"
+  })
+
+  const onProgress =
+    typeof fetchOptions.onProgress === 'function'
+      ? fetchOptions.onProgress
+      : null
+
+  // FAST PATH (без стрима)
+  if (!onProgress) {
+    const buffer = await resp.arrayBuffer()
+    arrayBuffers.push(buffer)
+    onComplete(arrayBuffers.length - 1, resp.status)
+    return
+  }
+
+  // STREAMING PATH
+  const reader = resp.body?.getReader()
+
+  // fallback если стрима нет
+  if (!reader) {
+    const buffer = await resp.arrayBuffer()
+    arrayBuffers.push(buffer)
+    onComplete(arrayBuffers.length - 1, resp.status)
+    return
+  }
+
+  const contentLength = Number(resp.headers.get("content-length")) || undefined
+
+  let loaded = 0
+  const chunks: Uint8Array[] = []
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+
+    if (value) {
+      chunks.push(value)
+      loaded += value.length
+
+      onProgress({ loaded, total: contentLength })
+    }
+  }
+
+  // сборка
+  const result = new Uint8Array(loaded)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.length
+  }
+
+  arrayBuffers.push(result.buffer)
+  onComplete(arrayBuffers.length - 1, resp.status)
+}
+
+export const _fetchToJson = (systemId: number) => { 
+  return JSON.parse(decoder.decode(getBuffer(systemId)))
+}
+
+export const _fetchToText = (systemId: number) => {
+  return decoder.decode(getBuffer(systemId))
+}
+
+/** The fetched bytes as a Uint8Array copy (Terrain.load and other SDK-parsed binaries). */
+export const _fetchToBytes = (systemId: number): Uint8Array => {
+  return new Uint8Array(getBuffer(systemId)).slice()
+}
+
+export const _fetchSlice = (systemId: number, start: number, end: number) => {
+  return decoder.decode(getBuffer(systemId).slice(start, end))
+}
+
+export const getUrl = (systemId: number) => {
+  const blob = new Blob([ arrayBuffers[systemId] ])
+  return URL.createObjectURL(blob)
+}
+
+export const getBlob = (systemId: number) => {
+  return new Blob([ arrayBuffers[systemId] ])
+}
+
+export const getBuffer = (systemId: number) => {
+  return arrayBuffers[systemId]
+}
+
+export const _disposeFetch = (id: number) => {
+  arrayBuffers[id] = null as any
+}
+
+export const putBuffer = (buffer: ArrayBuffer) => {
+  arrayBuffers.push(buffer)
+  return arrayBuffers.length - 1
+}
+
+const map = new Map<string, ArrayBuffer>()
+export const putLocalBuffer = (str: string, buf: ArrayBuffer) => {
+  map.set(str, buf)
+  // A name may already be materialized as a systemId (localResources caches forever). Refresh the
+  // buffer behind it, or a later engine sees the stale payload — e.g. the lite engine's empty
+  // built-in registrations must not shadow the real filamat the Filament engine loads on a
+  // lite → filament host switch.
+  const systemId = localResources.get(str)
+  if (systemId !== undefined) arrayBuffers[systemId] = buf
+}
+
+export const hasLocalBuffer = (str: string) => map.has(str)
+
+const localResources = new Map<string, number>()
+
+/** Reverse lookup: the local-resource name a systemId was materialized from (viewer-lite resolves
+ *  material shaders — "lit.filamat" etc — by name instead of compiling the filamat package). */
+export const getLocalName = (systemId: number): string | undefined => {
+  for (const [name, id] of localResources) if (id === systemId) return name
+  return undefined
+}
+
+export const _fetchLocal = (path: string): number => {
+  const existsSystemId = localResources.get(path)
+  if (existsSystemId !== undefined) {
+    return existsSystemId
+  }
+  const buf = map.get(path)
+  if (!buf) return -1
+  
+  arrayBuffers.push(buf)
+  const systemId = arrayBuffers.length-1
+
+  localResources.set(path, systemId)
+  return systemId
+}