lecodes-cli 0.6.4 → 0.7.0

package/runtime/sdk/scene/editorPlugins.ts

@@ -0,0 +1,86 @@
+// Editor plugins: `registerEditorWindow` / `registerEditorTool` (docs/scene-editor-plan.md,
+// phase 11). Registrations live in `*.editor.ts` files — compiled and executed ONLY in
+// scene-editor bundles (phase 10), so none of this reaches shipped app.js (nothing references it
+// there, and method-granular DCE drops it).
+//
+// The scene-editor harness (packages/projects/src/scene-editor) reads the registry through the
+// injected `__editorPlugins` global — the harness, the scene, and the editor files compile into
+// ONE bundle, so they share this module instance. Windows and tools describe their UI through the
+// same immediate-mode `InspectorUI` protocol custom inspector cards use (one widget vocabulary,
+// three mount points), and mutate the scene ONLY through the `editor` doc API — every plugin write
+// lands in the scene document (undoable, diffable), never in live engine state.
+
+import type { InspectorUI } from "../core/InspectorUI"
+
+/** A geometry hit under the viewport pointer, handed to tools. Physics builds raycast the scene's
+ *  meshes (precise); otherwise (and on misses) the hit falls back to the ground plane (y = 0). */
+export type EditorRayHit = {
+  point: [number, number, number]
+  normal: [number, number, number]
+  /** The scene-file node the hit belongs to — null for ground-plane fallback hits. */
+  node: string | null
+}
+
+/**
+ * The editor scripting API handed to windows and tools. Doc-op methods write the scene DOCUMENT
+ * through the editor's normal commit path (undo, file, live patching all included); they return
+ * false / no-op when the document can't take the edit (duplicate name, unknown node).
+ */
+export type EditorApi = {
+  /** The currently selected node name (or `model::part` key), null when nothing is selected. */
+  readonly selection: string | null
+  select(name: string | null): void
+  /** The scene document's nodes (name + source kind: mesh / model / light / group). */
+  nodes(): { name: string, kind: string }[]
+  /** First unused "base", "base2", "base3", … node name. */
+  uniqueName(base: string): string
+  /** Add a node from plain def data (scene-file grammar; a string `model` value means an asset
+   *  path). One undo step unless grouped by `transact`. */
+  addNode(name: string, def: Record<string, unknown>): boolean
+  /** Write one def prop (transforms apply live; anything else patches/re-runs the node). */
+  setProp(name: string, key: string, value: unknown): boolean
+  removeNode(name: string): void
+  /** Duplicate a node; returns the copy's name (null when it can't). */
+  duplicate(name: string): string | null
+  /** Raycast the scene under a viewport pixel (same hit rules as tool clicks). */
+  raycast(screenX: number, screenY: number): EditorRayHit | null
+  /** Group every doc edit inside `fn` into ONE undo step. */
+  transact(fn: () => void): void
+}
+
+export type EditorWindowFn = (ui: InspectorUI, editor: EditorApi) => void
+
+export type EditorToolHooks = {
+  /** CSS cursor for the viewport while this tool is active (default "crosshair"). */
+  cursor?: string
+  /** A short glyph (one character / emoji) for the tool's toolbar button — tools without one all
+   *  share the generic wand icon, so any editor with two or more tools should set it. */
+  icon?: string
+  /** A viewport click while the tool is active — `hit` is the raycast result under the pointer.
+   *  Selection clicks and the transform gizmo are suspended while a tool is active. */
+  onViewportClick?(hit: EditorRayHit, editor: EditorApi): void
+}
+
+/** @internal The registry the scene-editor harness reads (windows/tools in registration order). */
+export const __editorPlugins = {
+  windows: [] as { title: string, render: EditorWindowFn }[],
+  tools: [] as { name: string, hooks: EditorToolHooks }[],
+}
+
+/** Register an editor panel — a collapsible overlay docked over the viewport (the inspector rail
+ *  stays selection-scoped). A window that emits `ui.toolButton` for a tool becomes that tool's
+ *  settings panel: activating the tool expands and highlights it. `render` re-runs immediate-mode
+ *  on every interaction — same protocol as `static inspector` cards. */
+export const registerEditorWindow = (title: string, render: EditorWindowFn): void => {
+  const existing = __editorPlugins.windows.find((w) => w.title === title)
+  if (existing) existing.render = render
+  else __editorPlugins.windows.push({ title, render })
+}
+
+/** Register a viewport tool — a toolbar entry beside move/rotate/scale (activate it there or via
+ *  `ui.toolButton(label, name)`). While active, viewport clicks arrive as raycast hits. */
+export const registerEditorTool = (name: string, hooks: EditorToolHooks): void => {
+  const existing = __editorPlugins.tools.find((t) => t.name === name)
+  if (existing) existing.hooks = hooks
+  else __editorPlugins.tools.push({ name, hooks })
+}

package/runtime/sdk/ui/UI.ts

@@ -13,6 +13,7 @@ export { UIWidget, type UIWidgetStyle } from './UIWidget'
 
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
 export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
+export { UIScreenHost, type UIScreenHostStyle } from './UIScreenHost'
 
 export { UIVirtualizedList } from './UIVirtualizedList'
 

package/runtime/sdk/ui/UIScreen.ts

@@ -34,6 +34,17 @@ export interface UIScreen <Scrollable extends boolean = false> {
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
 
+  /**
+   * Keep this screen's built native tree alive when a UIScreenHost detaches it (replace / remove /
+   * pop): instead of being destroyed, its views + layout + live state (scroll position, input text)
+   * are retained, so re-hosting the SAME screen object restores it in place rather than rebuilding.
+   * `onClose`/`onOpen` still fire on detach/re-attach. You own the lifetime — a kept tree is freed
+   * only by `dispose()` or when the project unloads. (Native-only today; web rebuilds.)
+   */
+  keepAlive(enabled?: boolean): this
+  /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
+  dispose(): this
+
   onLayout(onLayout: OnLayoutCallback): this
 
   setClass(name: string, enabled: boolean): this
@@ -62,6 +73,18 @@ export class ScreenElement extends ContainerElement<"screen"> {
     this.cl.push(callback)
     return this
   }
+  // Read by the host at detach time (a plain flag on the node, like _interactive).
+  _keepAlive = false
+  keepAlive(enabled = true): this {
+    this._keepAlive = enabled
+    return this
+  }
+  dispose(): this {
+    // Rides the generic command channel (no dedicated bridge). No-op while _id is 0 (never mounted)
+    // or when the tree isn't currently detached-and-kept — the host ignores it then.
+    if (this._id !== 0) _creatorUI.command(this, "disposeKeepAlive")
+    return this
+  }
   readonly touchStartListeners: any[] = []
   _interactive = false
   onTouchStart (callback: any): this {

package/runtime/sdk/ui/UIScreenHost.ts

@@ -0,0 +1,212 @@
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style, type UINodeChild } from "./UINode"
+import type { UIScreen } from "./UIScreen"
+
+// UIScreenHost — the system's ONE screen host: an element whose pages are full UIScreens, each laid
+// out to the host's box (the same mechanism screens use, with the "device" swapped for the slot).
+// With several screens it pages between them (wrapping each platform's native pager); with a single
+// screen it simply embeds it — a refreshable region under a fixed header, or a screen-swap slot via
+// setContent(next). UITabs is pure TS over a swipe-disabled UIScreenHost.
+//
+// Pages are screens ONLY — no plain elements. Every page then carries the full screen contract
+// (onOpen/onClose from the settle lifecycle, makeScrollable()/onRefresh), and every platform
+// implements exactly one page kind: mount the screen root in the slot, lay it out to the slot size.
+// To host a plain element, wrap it: UIScreenHost(UIScreen([el])).
+
+/** A hosted page: any UIScreen, scrollable or not. Sizing styles on it are ignored (screens are roots sized by their host). */
+export type HostedScreen = UIScreen<boolean>
+/** Reactive pages — ChildrenFn narrowed to screens. */
+export type ScreensFn = () => (HostedScreen | null | undefined | false)[]
+
+/**
+ * Transition for `replace()`. The `Router.replace` catalogue, plus `"push"`/`"pop"` — the native
+ * UINavigationController feel (the incoming/outgoing screen slides full-width while the other
+ * parallaxes ~30% under a dim overlay with a soft edge shadow). Use `"push"` to go forward, `"pop"`
+ * to go back. (Animated transitions are native-only; web swaps instantly.)
+ */
+export type ScreenHostTransition =
+  | "push" | "pop"
+  | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom"
+  | "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
+
+export type UIScreenHostStyle = ElementStyle & DrawableStyle & {
+  // Paging axis. Default "horizontal". Read by the host at mount; live-updatable via .style().
+  scrollDirection?: "horizontal" | "vertical",
+  // false = programmatic-only paging (no user swipe) — the mode UITabs uses. Default true.
+  swipeEnabled?: boolean,
+}
+
+export interface UIScreenHost {
+  readonly type: "screenhost",
+  style: Style<this, UIScreenHostStyle>,
+  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
+  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
+
+  /** Current settled page index. */
+  readonly page: number,
+  /** Programmatic page switch. `animated` defaults to true (ignored when swipe physics can't run). */
+  setPage(index: number, animated?: boolean): this,
+  /** Fires when the settled page changes (after the swipe/scroll comes to rest). */
+  onPageChange(callback: (index: number) => void): this,
+  /** Continuous fractional scroll position (e.g. 1.35) — for tab-strip indicators / page dots. */
+  onPageScroll(callback: (position: number) => void): this,
+
+  append(...screens: HostedScreen[]): this,
+  insert(index: number, ...screens: HostedScreen[]): this,
+  remove(...screens: HostedScreen[]): this,
+  /** Replace the pages. A single screen swaps the hosted screen in place (old page onClose → new page onOpen). */
+  setContent(screens: HostedScreen | HostedScreen[] | ScreensFn): this,
+  /**
+   * Replace the page at `index` with a new screen, animating the swap when that page is the visible
+   * one (off-screen pages swap instantly). The settled page index is preserved — a replace is not a
+   * page change. This is the push/pop primitive: keep your own stack of screens and replace the
+   * visible slot with a forward transition to push, a backward one to pop.
+   */
+  replace(index: number, screen: HostedScreen, transition?: ScreenHostTransition): this,
+
+  readonly children: UINodeChild[],
+
+  onLayout(onLayout: OnLayoutCallback): this,
+
+  setClass(name: string, enabled: boolean): this,
+  toggleClass(name: string): this,
+  hasClass(name: string): boolean,
+  bindClass(name: string, fn: () => boolean): this,
+}
+
+export class ScreenHostElement extends ContainerElement<"screenhost"> {
+  // --- read by the host at mount (createScreenHostSystem) ---
+  _page = 0                                      // settled index; host writes it back on settle
+  _dir: "horizontal" | "vertical" = "horizontal"
+  _swipe = true
+
+  // --- listeners the host invokes directly (same pattern as UIScrollable.sl / vlist) ---
+  readonly pcl: ((index: number) => void)[] = []   // onPageChange
+  readonly psl: ((position: number) => void)[] = [] // onPageScroll
+
+  get page(): number {
+    return this._page
+  }
+
+  setPage(index: number, animated = true): this {
+    if (this._id !== 0) {
+      _creatorUI.command(this, "setPage", index, animated)
+    } else {
+      this._page = index   // remembered as the initial page until the host mounts
+    }
+    return this
+  }
+
+  onPageChange(callback: (index: number) => void): this {
+    this.pcl.push(callback)
+    return this
+  }
+  onPageScroll(callback: (position: number) => void): this {
+    this.psl.push(callback)
+    return this
+  }
+
+  // Pages are separate layout roots, not yoga children, so the generic insertNode/removeNode path
+  // doesn't apply. Keep `children` in sync and ask the host to reconcile pages by node identity.
+  append(...nodes: UINodeChild[]): this {
+    this.children.push(...nodes)
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  insert(index: number, ...nodes: UINodeChild[]): this {
+    this.children.splice(index, 0, ...nodes)
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  remove(...nodes: UINodeChild[]): this {
+    const set = new Set(nodes)
+    this.children = this.children.filter(c => !set.has(c as UINodeChild))
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  setContent(nodes: UINodeChild | UINodeChild[] | ChildrenFn): this {
+    if (typeof nodes === "function") {
+      // Reactive pages: the base binding drives _reconcile, which calls our insert/remove above.
+      return super.setContent(nodes)
+    }
+    this.children = Array.isArray(nodes) ? [...nodes] : [nodes]
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+
+  // Replace one page in place, animated. The node travels via children[index] (the command channel
+  // carries only index + transition); the host reads it back and swaps the page, animating the swap
+  // when `index` is the visible page. Before mount it just seeds the initial content at that index.
+  replace(index: number, screen: UINodeChild, transition: ScreenHostTransition = "fade"): this {
+    if (index < 0 || index >= this.children.length) return this
+    this.children[index] = screen
+    if (this._id !== 0) _creatorUI.command(this, "replace", index, transition)
+    return this
+  }
+
+  // scrollDirection/swipeEnabled are host behavior, not layout — intercept them here so they never
+  // reach the layout engine, and forward live changes to the host. Everything else flows to the base
+  // style proxy unchanged (including property get/set via the forwarding Proxy below).
+  private _hostStyleProxy?: any
+  get style(): any {
+    if (this._hostStyleProxy) return this._hostStyleProxy
+    const base = super.style
+    const self = this
+    const apply = (s: any) => {
+      if (s && typeof s === "object") {
+        if ("scrollDirection" in s && typeof s.scrollDirection !== "function") {
+          self._dir = s.scrollDirection
+          delete s.scrollDirection
+          if (self._id !== 0) _creatorUI.command(self, "setDirection", self._dir)
+        }
+        if ("swipeEnabled" in s && typeof s.swipeEnabled !== "function") {
+          self._swipe = s.swipeEnabled
+          delete s.swipeEnabled
+          if (self._id !== 0) _creatorUI.command(self, "setSwipe", self._swipe)
+        }
+      }
+      return base(s)
+    }
+    this._hostStyleProxy = new Proxy(apply, {
+      apply: (_t, _thisArg, args) => apply(args[0]),
+      get: (_t, k) => (base as any)[k],
+      set: (_t, k, v) => { (base as any)[k] = v; return true },
+    })
+    return this._hostStyleProxy
+  }
+}
+
+function makeScreenHost(style: UIScreenHostStyle | null, children: UINodeChild[] | ChildrenFn): ScreenHostElement {
+  const dir = style?.scrollDirection
+  const swipe = style?.swipeEnabled
+  if (style) {
+    delete style.scrollDirection
+    delete style.swipeEnabled
+  }
+  const el = new ScreenHostElement("screenhost", style ?? {}, children)
+  if (dir !== undefined) el._dir = dir
+  if (swipe !== undefined) el._swipe = swipe
+  return el
+}
+
+// A screen is the only non-array, non-function, non-style argument the factory accepts.
+const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v.type === "screen"
+const asPages = (v: any): UINodeChild[] | ChildrenFn => (Array.isArray(v) || typeof v === "function") ? v : [v]
+
+export function UIScreenHost(): UIScreenHost
+export function UIScreenHost(screen: HostedScreen): UIScreenHost
+export function UIScreenHost(screens: HostedScreen[] | ScreensFn): UIScreenHost
+export function UIScreenHost(style: UIScreenHostStyle): UIScreenHost
+export function UIScreenHost(style: UIScreenHostStyle, screens: HostedScreen | HostedScreen[] | ScreensFn): UIScreenHost
+export function UIScreenHost(...args: [] | [HostedScreen | HostedScreen[] | ScreensFn | UIScreenHostStyle] | [UIScreenHostStyle, HostedScreen | HostedScreen[] | ScreensFn]): UIScreenHost {
+  if (args.length === 0) {
+    return makeScreenHost({}, [])
+  } else if (args.length === 1) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function" || isScreenArg(args[0])) {
+      return makeScreenHost({}, asPages(args[0]))
+    } else {
+      return makeScreenHost(args[0] as UIScreenHostStyle, [])
+    }
+  } else {
+    return makeScreenHost(args[0] as UIScreenHostStyle, asPages(args[1]))
+  }
+}