lecodes-cli 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -20,15 +20,17 @@
     "node": ">=18"
   },
   "scripts": {
+    "icon": "bun scripts/make-icon.ts",
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
     "sync-peers": "bun scripts/sync-peer-versions.ts",
     "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --banner=\"#!/usr/bin/env node\"",
+    "build:bin": "bun scripts/build-bin.ts",
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run sync-peers && bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.2.0"
+    "@letary/chisel": "^0.3.0"
   },
   "peerDependencies": {
     "lecodes-design": "^0.3.1",
@@ -45,6 +47,7 @@
   "devDependencies": {
     "lecodes-design": "workspace:*",
     "lecodes-renderer": "^0.4.1",
+    "qrcode-terminal": "^0.12.0",
     "sdk": "workspace:*"
   }
 }

package/runtime/sdk/compile/index.ts

@@ -10,3 +10,9 @@ export {
   type CompileOptions,
   type CompileFileType,
 } from "./compileProject"
+export {
+  loadSceneHarness,
+  sceneEditorEntries,
+  SCENE_ENTRY_PATH,
+  SCENE_HARNESS_DIR,
+} from "./sceneEditor"

package/runtime/sdk/compile/sceneEditor.ts

@@ -0,0 +1,66 @@
+// The scene-editor compile composition, shared by every host that compiles an edit-mode bundle
+// for a .scene.ts file: the platform backend (src/scene/compileSceneEditor.ts), the standalone
+// scene-editor dev server, and (later) the lecodes CLI. One bundle on purpose: chisel's
+// method-granular DCE trims each bundle's SDK copy to its own calls, so a separately-compiled
+// harness could not call scene methods on objects the scene bundle created.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { CompileEntry } from "./compileProject"
+
+/** Where the harness sources land in the compile's file map. The dotfolder can't collide with
+ *  project assets (the tree forbids leading-dot names) and reads clearly in compile errors. */
+export const SCENE_HARNESS_DIR = "./.scene-editor"
+
+/** The virtual entrypoint path (`entryOverride`). */
+export const SCENE_ENTRY_PATH = "./.scene-entry.ts"
+
+/**
+ * Read the harness sources (packages/projects/src/scene-editor) from a directory:
+ * `LECODES_SCENE_HARNESS_DIR` env override first (deployments vendor the sources, like
+ * LECODES_SDK_INJECT does for the SDK), else the given fallback dir. Returns name → source.
+ */
+export const loadSceneHarness = (fallbackDir?: string): Record<string, string> => {
+  const override = process.env.LECODES_SCENE_HARNESS_DIR
+  const dir = override && existsSync(override) ? override
+    : fallbackDir && existsSync(fallbackDir) ? fallbackDir
+    : null
+  if (!dir) throw new Error("scene-editor harness sources not found (set LECODES_SCENE_HARNESS_DIR)")
+  const out: Record<string, string> = {}
+  for (const f of readdirSync(dir)) {
+    if (f.endsWith(".ts")) out[f] = readFileSync(join(dir, f), "utf8")
+  }
+  return out
+}
+
+/**
+ * The extra entries that turn a project compile into a scene-editor compile: the harness modules
+ * plus a virtual entry that (1) sets the edit-mode flag in its own module — imports hoist, so the
+ * flag must run as a module, first — (2) imports the scene, which registers its handle on
+ * `__lecodesScenes`, and (3) imports the harness main, which installs `__lecodesSceneHarness`.
+ * FULL extensions everywhere — exact-match specifiers need no resolver guesswork on dotted names,
+ * so even the unpatched published chisel resolves the `.scene.ts` import.
+ *
+ * `scenePath` is the project path of the scene file ("./scenes/city.scene.ts"). Compile with
+ * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`.
+ */
+export const sceneEditorEntries = (scenePath: string, harness: Record<string, string>): CompileEntry[] => {
+  const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
+    path: `${SCENE_HARNESS_DIR}/${name}`,
+    type: "text" as const,
+    text,
+  }))
+  entries.push({
+    path: `${SCENE_HARNESS_DIR}/.edit-mode.ts`,
+    type: "text",
+    text: `;(globalThis as any).__lecodesSceneEdit = true\nexport {}\n`,
+  })
+  entries.push({
+    path: SCENE_ENTRY_PATH,
+    type: "text",
+    text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
+      + `import "${scenePath}"\n`
+      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`,
+  })
+  return entries
+}

package/runtime/sdk/core/fields.ts

@@ -0,0 +1,108 @@
+// Field introspection for the scene-editor inspector: what's editable on an aspect, and with which
+// editor widget. Engine-agnostic (works for 2D and 3D aspects alike).
+//
+// The editable surface of an aspect is its public class fields with defaults — the same convention
+// aspects already follow for `node.aspect(Ctor, opts)` configuration. Editors are layered:
+//   1. inference from the default value's shape (number → number field, '#rrggbb' → color, …), free
+//      for every user aspect with zero ceremony;
+//   2. optional `static fields: FieldMeta<T>` on the class for ranges/labels/options/overrides
+//      (mirrors how `static aspect` declares the accessor name).
+
+/** Editor widget kinds the inspector knows how to render. */
+export type FieldEditor =
+  | "number" | "text" | "color" | "switch" | "select"
+  | "vec2" | "vec3" | "vec4"
+
+export type FieldMetaEntry = {
+  /** Inspector label (default: the field name). */
+  label?: string
+  min?: number
+  max?: number
+  step?: number
+  /** Allowed values — renders a dropdown (editor "select"). */
+  options?: readonly (string | number)[]
+  /** Override the editor inferred from the default value. */
+  editor?: FieldEditor
+  /** Exclude the field from the inspector. */
+  hidden?: boolean
+}
+
+/** Declared on an aspect class as `static fields: FieldMeta<MyAspect> = { … }`. All optional. */
+export type FieldMeta<T = unknown> = { [K in Extract<keyof T, string>]?: FieldMetaEntry }
+
+/** One editable field: key + default value + resolved editor + merged metadata. */
+export type FieldDescriptor = {
+  key: string
+  label: string
+  /** The default value (from a freshly constructed instance; undefined if only declared in meta). */
+  value: unknown
+  /** Resolved editor kind; undefined = no editor known (inspector shows it read-only). */
+  editor: FieldEditor | undefined
+  min?: number
+  max?: number
+  step?: number
+  options?: readonly (string | number)[]
+}
+
+export type AspectClassInfo = {
+  /** The accessor name (`static aspect`, injected by chisel for user aspects). */
+  name: string
+  className: string
+  fields: FieldDescriptor[]
+}
+
+// Instance fields every aspect inherits from the Aspect base — configuration plumbing, not content.
+const BASE_FIELDS = new Set([ "node", "updateBeforePhysics", "order", "updateWhenVisible" ])
+
+/** Infer the editor widget from a default value's shape. */
+export const inferFieldEditor = (value: unknown): FieldEditor | undefined => {
+  if (typeof value === "boolean") return "switch"
+  if (typeof value === "number") return "number"
+  if (typeof value === "string") return value.startsWith("#") ? "color" : "text"
+  if (Array.isArray(value) && value.length >= 2 && value.length <= 4 && value.every((n) => typeof n === "number")) {
+    return value.length === 2 ? "vec2" : value.length === 3 ? "vec3" : "vec4"
+  }
+  return undefined
+}
+
+const cloneValue = (v: unknown): unknown => (Array.isArray(v) ? [ ...v ] : v)
+
+/**
+ * Enumerate the editable fields of a class: construct a default instance, take its own enumerable
+ * non-underscore fields (minus the Aspect base plumbing), infer editors from the default values, and
+ * merge the class's optional `static fields` metadata (which can also add keys that have no runtime
+ * default, e.g. fields declared without an initializer).
+ */
+export const describeFields = (ctor: abstract new () => unknown): FieldDescriptor[] => {
+  let defaults: Record<string, unknown> = {}
+  // Aspects have no-arg constructors by convention (the engine creates them via node.aspect()); a
+  // class that throws here just loses default-value inference, it doesn't break the inspector.
+  try { defaults = new (ctor as new () => Record<string, unknown>)() } catch { /* meta-only */ }
+
+  const meta = ((ctor as { fields?: FieldMeta }).fields ?? {}) as Record<string, FieldMetaEntry>
+
+  const keys = new Set<string>()
+  for (const k of Object.keys(defaults)) {
+    if (BASE_FIELDS.has(k) || k.startsWith("_")) continue
+    if (typeof defaults[k] === "function") continue
+    keys.add(k)
+  }
+  for (const k of Object.keys(meta)) keys.add(k)
+
+  const out: FieldDescriptor[] = []
+  for (const key of keys) {
+    const m = meta[key] ?? {}
+    if (m.hidden) continue
+    const value = defaults[key]
+    const editor = m.editor ?? (m.options ? "select" : inferFieldEditor(value))
+    out.push({ key, label: m.label ?? key, value: cloneValue(value), editor, min: m.min, max: m.max, step: m.step, options: m.options })
+  }
+  return out
+}
+
+/** Describe an aspect class for the inspector: accessor name + class name + editable fields. */
+export const describeAspect = (ctor: abstract new () => unknown): AspectClassInfo => ({
+  name: (ctor as { aspect?: string }).aspect ?? "",
+  className: (ctor as { name?: string }).name ?? "",
+  fields: describeFields(ctor),
+})

package/runtime/sdk/gl/Material.ts

@@ -36,6 +36,14 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
 
 export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
+/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+export type LitMaterialOptions = MaterialColorOptions & {
+  /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
+  roughness?: number
+  /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
+  metallic?: number
+}
+
 export class Material {
   /** @internal native material-instance handle. */
   _id: number
@@ -84,12 +92,14 @@ export class Material {
   // --- factories ---
 
   /** PBR lit material. */
-  static lit(options: MaterialColorOptions = {}): Material {
+  static lit(options: LitMaterialOptions = {}): Material {
     // The fetchLocal literal must be inline so the compiler's preload header captures the shader name.
     const m = new Material({ _id: _creatorUtils.fetchLocal("lit.filamat") } as any)
     m._colorKey = "baseColor"
     if (options.color !== undefined) m.color = options.color
     if (options.map) m.map = options.map
+    if (options.roughness !== undefined) m.uniforms.roughness = options.roughness
+    if (options.metallic !== undefined) m.uniforms.metallic = options.metallic
     return m
   }
 

package/runtime/sdk/gl/Scene.ts

@@ -66,11 +66,16 @@ export class Scene {
     if (parent) {
       this.camera = parent.camera
       this._id = _creator.createOverlayScene(parent._id)
+      // No camera re-attach: the native createOverlayScene wires the parent's camera into the
+      // overlay view. Re-attaching would (a) point camera._sceneId — the source for getRay /
+      // getViewDirection / fov — at the overlay's view, whose viewport/projection aren't
+      // maintained like the render view's, and (b) create a second native camera component on
+      // the shared entity. (Found via the scene editor: gizmo pick rays came out distorted.)
     } else {
       this.camera = new Camera()
       this._id = _creator.createScene()
+      this.camera._attach(this._id)
     }
-    this.camera._attach(this._id)
 
     if (options.ibl !== false) _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000)
     if (options.bloom) _creator.setBloomOptions(this._id, true, options.bloomIntensity ?? 0.2, 1)
@@ -195,3 +200,25 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
     super.close()
   }
 }
+
+// --- VR ---
+
+/**
+ * A 3D scene rendered in a VR headset (OpenXR — e.g. Meta Quest). The headset drives the camera:
+ * every frame both eyes are rendered from the tracked head pose, so `scene.camera` position/lookAt
+ * have no effect while the scene is open. The world origin is at floor level (stage space) —
+ * author content with the ground at y = 0 and the user standing at the origin.
+ *
+ * `open()` rejects on hosts without a VR runtime ("VR is not supported on this device").
+ */
+export class VRScene extends Scene {
+  override async open(): Promise<void> {
+    await new Promise<void>((res, rej) => _creator.launchVR(this._id, res, rej))
+    super.open()
+  }
+
+  override close(): void {
+    _creator.stopVR()
+    super.close()
+  }
+}

package/runtime/sdk/gl/touch.ts

@@ -5,12 +5,24 @@ import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch
 import { nodeRegistry } from "./Node"
 import { glState } from "./state"
 
+// Hits inside a loaded model (GLB) land on sub-entities the user never created a Node for — walk up
+// the transform hierarchy to the nearest entity someone actually holds (the model's Node).
+const resolveHitNode = (entityId: number) => {
+  let node = nodeRegistry.get(entityId)
+  for (let id = entityId, i = 0; !node && i < 32; i++) {
+    id = _creator.getParent(id)
+    if (id === 0) break
+    node = nodeRegistry.get(id)
+  }
+  return node ?? null
+}
+
 const onTouchEnd = (pointerId: number, clientX: number, clientY: number, entityId: number): TrackHandler | null => {
   const scene = glState.activeScene
   if (!scene) return null
   const ev = new ClickEvent<any>(clientX, clientY, pointerId)
   if (entityId > 0) {
-    const node = nodeRegistry.get(entityId) ?? null
+    const node = resolveHitNode(entityId)
     ev.target = node
     if (node) node._dispatchEvent("click", ev)
   } else {
@@ -25,7 +37,7 @@ const onTouchStart = (pointerId: number, clientX: number, clientY: number, entit
   if (!scene) return null
   const ev = new TouchStartEvent<any>(clientX, clientY, pointerId)
   if (entityId > 0) {
-    const node = nodeRegistry.get(entityId) ?? null
+    const node = resolveHitNode(entityId)
     ev.target = node
     if (node) {
       node._dispatchEvent("touchstart", ev)

package/runtime/sdk/inject.ts

@@ -25,6 +25,7 @@ export { Canvas, Bitmap } from "./canvas/Canvas"
 
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
 export { toast, SvgSource } from "./runtime/misc"
+export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
 export { fetch, fetchLocal, FormData, File } from "./runtime/fetch"
 export { localStorage } from "./runtime/storage"
 export { device } from "./runtime/device"
@@ -78,8 +79,13 @@ export { easeIn, easeOut, easeInOut } from "./animate/easings"
 // ---- plugins (optional, host-provided capabilities — see src/plugins/) ----
 export { QRScanner } from "./plugins/qr"
 
+// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
+export { defineScene, use, SceneHandle } from "./scene/defineScene"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, AspectEntry, LoadedScene } from "./scene/defineScene"
+export type { FieldMeta } from "./core/fields"
+
 // ---- 3D engine (creator-gl) ----
-export { Scene, ARScene } from "./gl/Scene"
+export { Scene, ARScene, VRScene } from "./gl/Scene"
 export { Node } from "./gl/Node"
 export { Mesh } from "./gl/Mesh"
 export { Model } from "./gl/Model"