lecodes-cli 0.19.0 → 0.19.2

package/runtime/sdk/ui/UIWidget.ts

@@ -1,127 +0,0 @@
-import { TouchStartEvent } from "../runtime/touch"
-import { _descOf, _navSupported, Presentable } from "./presentable"
-import { ContainerElement, buildUI, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type PaddingStyle, type PositionStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode"
-
-
-export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
-  /** A layer behind the widget that intercepts clicks — `"transparent"` still intercepts, `null`
-   *  removes the layer. A tap on it fires `onOverlayTap`. */
-  overlayColor?: Color | null
-}
-
-
-/** A floating overlay — absolutely positioned in device coordinates, mounted above the page as
- *  its own layout root (never a child of what's underneath). The base of dialogs, toasts,
- *  mini-players and scene HUDs; `UIModal`/`UIPopover`/`UIBottomSheet` build on it. */
-export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
-  readonly type: "widget",
-
-  /**
-   * Attach this widget to a destination (a `Scene`, a `UIScreen`, …): the widget lives on that
-   * page's layer — it shows/hides with the page and rides its transition, and a screen pushed
-   * on top covers it (a scene HUD behaves like part of the scene). Sticky until `attachTo(null)`
-   * (= back to a global overlay). Set it while the widget is hidden. The widget is always its own
-   * overlay root mounted into the owner's page view — it never becomes a child of the owner, so it
-   * stays topmost and its updates never trigger the owner's relayout. Works with a `UIScreen` that
-   * is a page inside a `UIPager`: the widget mounts into that tab and rides its swipe. (Web shows
-   * and hides it with the owner but does not yet ride the transition.)
-   */
-  attachTo(owner: Presentable | null): this,
-
-  /** Show the widget. By default it is a global overlay above every destination — it stays
-   *  visible across navigation until `hide()` (dialogs, mini-player, global loader). If the
-   *  widget was attached via `attachTo(owner)`, it mounts on that page's layer instead and is
-   *  only visible while the owner is presented. */
-  show(): void,
-  /** Unmount the widget. */
-  hide(): void,
-
-  /** Mounted right now (`show()` ran, `hide()` hasn't). */
-  readonly isShow: boolean,
-
-  /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
-  onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this,
-  /** Tap on the overlay layer (requires an `overlayColor`). */
-  onOverlayTap(callback: () => void): this,
-  /** Hardware/system back while the widget is shown. */
-  onBackPressed(callback: () => void): this
-}
-
-
-export class WidgetElement extends ContainerElement<"widget"> {
-  scrollable = false as const
-  _owner?: Presentable
-  constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn) {
-    // Widgets are absolutely positioned in device coordinates — in the constructor (not the
-    // factory) so subclasses like ModalElement inherit it.
-    super(type, { position: "absolute", ...style }, children)
-  }
-  attachTo(owner: Presentable | null): this {
-    this._owner = owner ?? undefined
-    return this
-  }
-  show(): void {
-    // A widget is always its OWN overlay root (a separate Yoga tree mounted above the owner's
-    // content) — never a child of the owner, so it stays topmost, its updates never relayout the
-    // owner, and it doesn't pollute the owner's children. `attachTo(owner)` just tells the host
-    // which page view to mount that root into; ownerless widgets are global overlays.
-    if (this._owner && _navSupported()) {
-      _creatorUI.showWidget(this, _descOf(this._owner))
-    } else {
-      // Unattached (or legacy host): global overlay above navigation.
-      _creatorUI.showWidget(this)
-    }
-  }
-  hide(): void {
-    _creatorUI.hideWidget(this)
-  }
-  get isShow(): boolean {
-    return this._id !== 0
-  }
-
-  _interactive = false
-  readonly touchStartListeners: any[] = []
-  onTouchStart (callback: any): this {
-    this._interactive = true
-    this.touchStartListeners.push(callback)
-    return this
-  }
-  _emitTouchStart(pointerId: number, clientX: number, clientY: number): any {
-    const touchEvent = new TouchStartEvent(clientX, clientY, pointerId)
-    touchEvent.target = this
-    for (let callback of this.touchStartListeners) {
-      callback(touchEvent)
-      if ((touchEvent as any)._trackHandler) {
-        return (touchEvent as any)._trackHandler
-      }
-    }
-    return null
-  }
-  readonly otl: (() => void)[] = []
-  onOverlayTap(callback: () => void): this {
-    this.otl.push(callback)
-    return this
-  }
-
-  _backButtonCallback?: () => void
-  onBackPressed(callback: any): this {
-    this._backButtonCallback = callback
-    return this
-  }
-}
-
-
-const makeWidget = (style: any, children: any) => new WidgetElement("widget", style, children)
-
-/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
-export const __UIWidget = (children: UINodeChild[] | ChildrenFn): UIWidget => makeWidget({}, children)
-
-/** Create a widget (same argument forms as `UIColumn`). Position it with absolute-style props
- *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
-export function UIWidget(...children: UIChildArg[]): UIWidget;
-export function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIWidget(style: UIWidgetStyle, children?: UINodeChild[] | ChildrenFn): UIWidget;
-export function UIWidget(...args: any[]): UIWidget {
-  return buildUI(args, null, makeWidget)
-}

package/runtime/sdk/ui/fonts.ts

@@ -1,13 +0,0 @@
-type FontOptions = {
-  weight?: number,
-  style?: "normal" | "italic"
-}
-
-/** Register a font face from a URL at runtime under `fontFamily`; resolves once it's ready to
- *  use in styles. For registry/project fonts prefer the compile-time `font()` macro — this is the
- *  dynamic escape hatch. */
-export async function registerFont (fontFamily: string, url: string, options: FontOptions = {}): Promise<void> {
-  return new Promise<void>((res, rej) => {
-    _creatorUI.registerFont(fontFamily, url, options, res, rej)
-  })
-}

package/runtime/sdk/ui/presentable.ts

@@ -1,117 +0,0 @@
-// The Presentable contract — the one navigation model (docs/navigation-presentable-plan.md).
-// Anything that can occupy the app's main slot implements it: UIScreen, Scene (+ARScene),
-// Scene2D, NativeView, UIVideo. Exactly one Presentable is visible at a time — a screen no
-// longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
-// `UIWidget.attachTo(scene)`.
-//
-// This module is dependency-free on purpose: gl/ and g2/ import it, so it must not pull any UI
-// element code into engine-only bundles.
-
-/** Built-in transition catalog. `push`/`pop` are the stacked-navigation pair (slide + parallax +
- *  dim + edge shadow); the rest are simple two-view moves. */
-export type TransitionName =
-  | "push" | "pop"
-  | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom"
-  | "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
-
-/** Start/end pose of one side of a custom transition. `x`/`y` are logical px, or a percentage of
- *  the destination's size (e.g. `"100%"` = one full width to the right). */
-export type TransitionTransform = {
-  x?: number | `${number}%`
-  y?: number | `${number}%`
-  scale?: number
-  opacity?: number
-}
-
-/**
- * A custom transition: declarative poses for the incoming/outgoing destination, played natively.
- * Serializes onto each platform's existing transition machinery — there is no per-frame JS.
- * Fields omitted keep the identity pose. Interactive back-swipe stays system-native (push/pop
- * only); a spec applies to non-interactive transitions.
- */
-export interface TransitionSpec {
-  /** Duration in ms (default 300). */
-  duration?: number
-  /** cubic-bezier control points (default ease-out). */
-  easing?: [number, number, number, number]
-  /** The entering destination animates FROM this pose to identity. */
-  incoming?: { from?: TransitionTransform }
-  /** The leaving destination animates from identity TO this pose. */
-  outgoing?: { to?: TransitionTransform }
-  /** Scrim alpha (0..1) painted over whichever destination is underneath. */
-  dim?: number
-  /** Which side stacks on top during the animation (default "incoming"). On Android, transitions
-   *  involving a scene always animate the screen side on top — the scene view itself never moves. */
-  onTop?: "incoming" | "outgoing"
-}
-
-export type Transition = TransitionName | TransitionSpec
-
-export type PresentOptions = {
-  /** Transition to play while this destination replaces the current one (default "none" for a
-   *  direct open(); the Router applies its own defaults — push/pop, and the theme's
-   *  `replaceTransition` for replace). */
-  transition?: Transition
-}
-
-/**
- * Anything that can be shown as the app's current destination: a `UIScreen`, a `Scene` /
- * `ARScene`, a `Scene2D`, a `NativeView`, or a `UIVideo`. One Presentable is visible at a time;
- * open it directly (`p.open()` — replaces the current destination, suspending an active Router
- * until `Router.restore()`) or navigate with `Router.push/replace/pop`.
- *
- * `onOpen`/`onClose` are the presentation lifecycle (fired when the destination becomes / stops
- * being the visible one — including router pushes covering it and pops revealing it).
- */
-export interface Presentable {
-  // Return type covers the implementers: UIScreen → void, Scene2D → this, ARScene → Promise.
-  open(options?: PresentOptions): void | this | Promise<void>
-  close(): void
-  onOpen(callback: () => void): this
-  onClose(callback: () => void): this
-  onBackPressed(callback: () => void): this
-  /** @internal Async work that must finish BEFORE this destination replaces the current one
-   *  (camera permission, warm render, session launch — ARScene). The previous destination —
-   *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`
-   *  await it and skip the swap entirely if it rejects (permission denied, or superseded by
-   *  another navigation that happened while preparing). */
-  _prepare?(): Promise<void>
-}
-
-// The destination visible right now. Set optimistically by every successful open()/router
-// navigation, cleared by close(), and corrected by router onChange (hosts hand the wire desc
-// back on every stack change, including back gestures — `_p` resolves it to the SDK instance).
-let current: Presentable | null = null
-/** @internal Call whenever the visible destination changes. */
-export const _setCurrent = (p: Presentable | null): void => { current = p }
-
-/** Runtime companion of the `Presentable` interface (declaration merging): the navigation
- *  state that isn't tied to the Router. */
-export const Presentable = /*#__PURE__*/ Object.freeze({
-  /** The destination visible right now (a `UIScreen`, `Scene`, `Scene2D`, `NativeView` or
-   *  `UIVideo`), or `null` before the first open. Distinct from `Router.current` — that is the
-   *  top of the router stack, which stays meaningful while the router is suspended by a direct
-   *  `open()`; this is what is actually on screen. `UIWidget.show()` attaches to it. */
-  get current(): Presentable | null { return current },
-})
-
-// Monotonic navigation epoch: every destination change (open/close/router nav) bumps it. Async
-// preparers capture the epoch before their awaits and reject as "superseded" if it moved — so a
-// slow AR prepare can't steal the screen from a navigation the user made in the meantime.
-let navEpoch = 0
-/** @internal */
-export const _navEpoch = (): number => navEpoch
-/** @internal Call on every action that changes the visible destination. */
-export const _bumpNavEpoch = (): void => { navEpoch++ }
-
-/** @internal Does this host implement the Presentable navigation surface? The SDK falls back to
- *  the legacy openScreen/openScene bridges when it doesn't (screens keep working; scene/native
- *  destinations in the Router then throw). */
-export const _navSupported = (): boolean =>
-  typeof _creatorUI !== "undefined" && typeof _creatorUI.openView === "function"
-
-/** @internal The wire descriptor for a Presentable. Screens (and anything without `_viewDesc`)
- *  travel as themselves; scenes/native views/video provide a stable descriptor object carrying
- *  `_p` (the SDK instance) so hosts can hand it back through router onChange / lifecycle. */
-export const _descOf = (p: Presentable): object =>
-  typeof (p as any)._viewDesc === "function" ? (p as any)._viewDesc() : (p as object)

package/runtime/sdk/ui/router.ts

@@ -1,132 +0,0 @@
-import { _bumpNavEpoch, _descOf, _navSupported, _setCurrent, Presentable, type Transition } from "./presentable"
-import { _navDefaults } from "./theme"
-
-type RouterOptions = {
-  showDefaultBackButton?: boolean
-}
-
-type NavigateOptions = {
-  /** Transition to play. Defaults: `"push"` for push, `"pop"` for pop; replace follows the
-   *  theme's `replaceTransition` (`"none"` out of the box). */
-  transition?: Transition
-}
-
-/** Stack navigation over `Presentable` destinations. `init` once with the home page, then
- *  `push`/`replace`/`pop`; the back gesture/button pops natively. A direct `page.open()` suspends
- *  the router until `restore()`. */
-type Router = {
-  /** The top of the router stack (not necessarily what's on screen — see `Presentable.current`). */
-  get current(): Presentable
-  /** Mount the router with `homePage` as the stack root — the app's navigation entry point. */
-  init(homePage: Presentable, opts?: RouterOptions): void
-  /** Push a destination onto the stack — a `UIScreen`, a `Scene`, a `Scene2D`, a `NativeView`,
-   *  or a `UIVideo`. The back gesture/button pops it. Destinations with async preparation
-   *  (`ARScene`: camera permission + warm render) return a Promise — the current page stays
-   *  visible until they're ready, and a rejection (permission denied / superseded) leaves the
-   *  stack untouched. */
-  push(page: Presentable, opts?: NavigateOptions): void | Promise<void>
-  /** Swap the top of the stack for `page` — no back entry to the replaced one. */
-  replace(page: Presentable, opts?: NavigateOptions): void | Promise<void>
-  /** Pop the top destination (the programmatic twin of the back gesture); `to` unwinds to a
-   *  stack index in one step. */
-  pop(to?: number, opts?: NavigateOptions): void
-  /** Blank the router's page, keeping the stack — `restore()` brings it back. A destination
-   *  opened directly stays visible. */
-  hide(): void
-  /** Re-present the stack top after `hide()` or a direct `open()` suspended the router. */
-  restore(): void
-
-  /** `"change"` fires on every stack change — pushes, pops, and native back gestures — with the
-   *  new top destination. */
-  addEventListener(channel: "change", callback: (page: Presentable) => void): void
-  removeEventListener(channel: "change", callback: (page: Presentable) => void): void
-}
-
-let currentPage: Presentable | null = null
-let onChange = (page: any) => {
-  // Hosts hand back the wire object: the screen itself, or a descriptor carrying `_p`.
-  currentPage = page && page._p ? page._p : page
-  // The router's page is the visible destination (hosts fire this on every stack change,
-  // including back gestures) — keep Presentable.current in sync.
-  _setCurrent(currentPage)
-  for (let callback of (Router as any)._changeListeners) {
-    callback(currentPage)
-  }
-}
-
-// Non-screen destinations have no legacy bridge to fall back to — surface that clearly instead
-// of letting an old host try to build a screen out of a scene descriptor.
-const wireDesc = (page: Presentable): object => {
-  const desc = _descOf(page)
-  if (desc !== page && !_navSupported()) {
-    throw new Error("This host does not support scene/native-view navigation (requires _creatorUI.openView)")
-  }
-  return desc
-}
-
-export const Router: Router = /*#__PURE__*/ Object.freeze({
-
-  init(homePage: Presentable, opts: RouterOptions = {}): void {
-    _bumpNavEpoch()
-    _creatorUI.routerOpen(wireDesc(homePage), onChange, opts.showDefaultBackButton ?? false)
-    currentPage = homePage
-    _setCurrent(homePage)
-  },
-  push(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
-    const desc = wireDesc(page)   // throws early on unsupported hosts, before any async work
-    const go = () => {
-      _bumpNavEpoch()
-      // Legacy hosts ignore the extra transition argument.
-      _creatorUI.routerPush(desc, opts?.transition ?? "push")
-      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
-    }
-    // A preparing destination (ARScene) keeps the current page visible until it's ready; a
-    // rejection (camera denied / superseded) propagates to the caller and nothing is pushed.
-    const prep = page._prepare?.()
-    return prep ? prep.then(go) : go()
-  },
-  replace(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
-    const desc = wireDesc(page)
-    const go = () => {
-      _bumpNavEpoch()
-      _creatorUI.routerReplace(desc, opts?.transition ?? _navDefaults.replace)
-      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
-    }
-    const prep = page._prepare?.()
-    return prep ? prep.then(go) : go()
-  },
-  pop(to?: number, opts?: NavigateOptions): void {
-    _bumpNavEpoch()
-    _creatorUI.routerPop(to ?? -1, opts?.transition ?? "pop")
-  },
-  hide() {
-    _bumpNavEpoch()
-    _creatorUI.routerHide()
-    // hide() only blanks the router's own page — a directly-opened destination stays visible.
-    if (Presentable.current === currentPage) _setCurrent(null)
-  },
-  restore() {
-    _bumpNavEpoch()
-    _creatorUI.routerRestore()
-    _setCurrent(currentPage)   // the stack top is visible again
-  },
-
-  get current(): Presentable {
-    return currentPage!
-  },
-
-  _changeListeners: [] as any[],
-  addEventListener(channel: "change", callback: (page: Presentable) => void): void {
-    if (channel === "change") {
-      this._changeListeners.push(callback)
-    }
-  },
-  removeEventListener(channel: "change", callback: (page: Presentable) => void): void {
-    if (channel === "change") {
-      let index = this._changeListeners.indexOf(callback)
-      if (index >= 0) {
-        this._changeListeners.splice(index, 1)
-      }
-    }
-  }
-})

package/runtime/sdk/ui/theme.ts

@@ -1,84 +0,0 @@
-// theme() — app theme variables (docs/ui-theme-plan.md). One global var table lives in the UI
-// core; `var(--key)` references resolve at style-apply time, so re-calling theme() re-styles the
-// LIVE UI. Bare style tokens (`pt: "comfort-top"`) are keywords that may expand to formulas
-// (max(safe-top, knob)); `var(--comfort-top)` always reads the raw table value.
-
-import type { Transition } from "./presentable"
-
-export type ThemeValues = Record<string, string | number | null>
-
-/** @internal Navigation defaults the theme owns; the router reads them at call time.
- *  (SDK-side state, deliberately NOT in the host var table — `var(--replaceTransition)`
- *  is not a style value.) */
-export const _navDefaults: { replace: Transition } = { replace: "none" }
-
-// (Unconstrained: it also maps inputs whose `replaceTransition` key was carved out.)
-export type ThemeAccessors<T> = {
-  readonly [K in keyof T]: K extends string ? `var(--${K})` : never
-}
-
-const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "vh", "vmin", "vmax"]
-
-/**
- * Merge app theme variables into the live table and get typed `var(--key)` accessors back:
- *
- * ```ts
- * export const T = theme({ primaryColor: "#0A84FF", cardBg: "#1C1C1E" })
- * card.style({ bgColor: T.cardBg })   // T.cardBg === "var(--cardBg)"
- * ```
- *
- * Strings pass through (colors, fonts, expressions like `"max(safe-top, 24px)"`); numbers are
- * lengths (px); `null` removes a key (comfort knobs reset to their defaults). Env names
- * (`safe-*`, `vw`/`vh`/…) are host-owned — skipped with a warning. One special key:
- * `replaceTransition` — the app-wide default transition for `Router.replace` (consumed SDK-side,
- * never sent to the host table).
- */
-const setTheme = <T extends Record<string, string | number | Transition | null>>(
-  // Only `replaceTransition` may carry a Transition — every other key is a style value.
-  values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null }
-): ThemeAccessors<Omit<T, "replaceTransition">> => {
-  const accessors: Record<string, string> = {}
-  let send = values as ThemeValues
-  const strip = (key: string) => {
-    if (send === values) send = { ...values } as ThemeValues
-    delete send[key]
-  }
-  for (const key of Object.keys(values)) {
-    if (key === "replaceTransition") {
-      _navDefaults.replace = (values[key] ?? "none") as Transition
-      strip(key)   // SDK-consumed, no accessor: it isn't a style var
-      continue
-    }
-    if (RESERVED.includes(key)) {
-      console.warn(`theme(): "${key}" is an environment value (host-owned) — ignored`)
-      strip(key)
-      continue
-    }
-    accessors[key] = `var(--${key})`
-  }
-  // Optional during rollout: hosts without the method simply don't theme (values still type).
-  if (Object.keys(send).length > 0) _creatorUI.setTheme?.(send)
-  return accessors as ThemeAccessors<Omit<T, "replaceTransition">>
-}
-
-/** App theme: callable to merge variables (`theme({...})` — re-calling re-styles the live UI, so
- *  dark mode is just a second call), with the system vars as static properties
- *  (`theme.primaryColor`, `theme["comfort-top"]`, …). */
-export const theme = Object.assign(setTheme, {
-  /** The app accent color. Kit components will read it via `var(--primaryColor, <fallback>)`. */
-  primaryColor: "var(--primaryColor)",
-  /** Secondary / inactive content color for kit components. */
-  mutedColor: "var(--mutedColor)",
-  /** DEFAULT text color — text without an explicit `color` follows it (hosts source their
-   *  default from the theme; unset = the host default, white on dark screens). Set it once for
-   *  a light theme instead of `color: "black"` on every label. */
-  color: "var(--color)",
-  /** DEFAULT text font — text without an explicit `fontFamily` follows it. */
-  fontFamily: "var(--fontFamily)",
-  /** Raw comfort knobs (logical px). The bare `comfort-top` style TOKEN applies the safe-area
-   *  formula — these accessors read the knob value itself, for manual composition. */
-  "comfort-top": "var(--comfort-top)",
-  "comfort-bottom": "var(--comfort-bottom)",
-  "comfort-left": "var(--comfort-left)",
-  "comfort-right": "var(--comfort-right)",
-} as const)