lecodes-cli 0.13.2 → 0.14.0

package/runtime/sdk/compile/libraryImports.ts

@@ -0,0 +1,52 @@
+// Pre-chisel rewrite of user-library bare-specifier imports. chisel's resolver hard-errors on any
+// bare import (the whole SDK is globals), so a project that imports a component library by its slug
+// —`import { Card } from "acme-ui"`— is rewritten here to the injected library tree under
+// `/__lib/<slug>/…` BEFORE chisel runs. Only libraries present in the dependency map are known
+// slugs; any other bare specifier is an author error, surfaced with a friendly message instead of
+// chisel's generic one. Static string-literal specifiers only — dynamic `import()` is unsupported
+// (documented). Chisel itself is untouched. See docs/library-system-plan.md §4.
+
+/** Cheap pre-check so the regexes don't run over files with no imports at all. */
+export const hasImportStatement = (src: string): boolean => src.includes("import") || src.includes("from")
+
+// A static `from "…"` clause (import-from OR export-from). Anchored at a statement boundary
+// (line start / `;` / `}`) and disallowing quotes/backticks/semicolons between the keyword and
+// `from`, so it can never span into a string literal or a neighbouring statement. Named-import
+// lists may span multiple lines (newlines are allowed between the keyword and `from`).
+const IMPORT_FROM_RE = /(^|[;\n}])(\s*(?:import|export)\b[^"'`;]*?\bfrom\s*)(["'])([^"'\n]+)\3/g
+
+// A side-effect `import "…"` (a bare quote directly after the keyword — not `import x`, not `import(`).
+const SIDE_EFFECT_RE = /(^|[;\n}])(\s*import\s*)(["'])([^"'\n]+)\3/g
+
+const isRelativeOrAbsolute = (spec: string): boolean =>
+  spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../")
+
+/**
+ * Rewrite every known-library bare import in `src` to its `/__lib/<slug>/…` path. Relative and
+ * absolute specifiers pass through untouched; an unknown bare specifier throws a friendly Error.
+ * `slugs` is the set of library slugs available to this project (its dependency map's keys).
+ */
+export const rewriteLibraryImports = (src: string, slugs: Set<string>): string => {
+  const rewriteSpec = (spec: string): string => {
+    if (isRelativeOrAbsolute(spec)) return spec
+    const slash = spec.indexOf("/")
+    const slug = slash === -1 ? spec : spec.slice(0, slash)
+    if (slugs.has(slug)) {
+      // `acme-ui` → `/__lib/acme-ui/index`; `acme-ui/theme` → `/__lib/acme-ui/theme`.
+      const sub = slash === -1 ? "/index" : spec.slice(slash)
+      return `/__lib/${slug}${sub}`
+    }
+    // Legacy worker-module imports (`import { UIScreen } from "ui"`) predate the globals-only SDK —
+    // chisel would reject them anyway; say so here instead of "Unknown library".
+    if (slug === "ui" || slug === "creator" || slug === "utils") {
+      throw new Error(`import from "${slug}": the SDK needs no imports — UIScreen, Scene, etc. are globals; remove this import line.`)
+    }
+    throw new Error(`Unknown library "${slug}" — add it in Settings → Libraries, or use a relative path like "./${slug}".`)
+  }
+
+  let out = src.replace(IMPORT_FROM_RE, (_m, boundary, head, quote, spec) =>
+    `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  out = out.replace(SIDE_EFFECT_RE, (m, boundary, head, quote, spec) =>
+    isRelativeOrAbsolute(spec) ? m : `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  return out
+}

package/runtime/sdk/compile/sceneEditor.ts

@@ -0,0 +1,78 @@
+// 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`, (3) imports the project's `*.editor.ts` plugin files (editor bundles ONLY —
+ * production compiles never import them, so they cost zero bytes in shipped `app.js`), and
+ * (4) 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"); `projectPaths` is
+ * the project's file list — `.editor.ts` entries are picked out of it. Compile with
+ * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
+ */
+export const sceneEditorEntries = (
+  scenePath: string,
+  harness: Record<string, string>,
+  projectPaths: 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`,
+  })
+  const editorImports = projectPaths
+    .filter((p) => p.endsWith(".editor.ts"))
+    .map((p) => `import "${p}"\n`)
+    .join("")
+  entries.push({
+    path: SCENE_ENTRY_PATH,
+    type: "text",
+    text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
+      + `import "${scenePath}"\n`
+      + editorImports
+      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`,
+  })
+  return entries
+}

package/runtime/sdk/compile/sfnt.ts

@@ -0,0 +1,98 @@
+// Minimal sfnt (TTF/OTF) reader for the `font()` compile macro: family name from the `name` table,
+// weight/italic from `OS/2` (with a `head.macStyle` fallback). Reads only what the macro needs —
+// this is not a font sanitizer or validator.
+
+export type SfntInfo = { family: string, weight: number, italic: boolean }
+
+const TAG_TTF = 0x00010000
+const TAG_OTTO = 0x4f54544f // 'OTTO' (CFF outlines)
+const TAG_TTCF = 0x74746366 // 'ttcf' (collection)
+const TAG_WOFF = 0x774f4646 // 'wOFF'
+const TAG_WOF2 = 0x774f4632 // 'wOF2'
+
+/** Parse a .ttf/.otf. Throws a message meant to surface verbatim in a compile error. */
+export const parseSfnt = (bytes: Uint8Array): SfntInfo => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (bytes.byteLength < 12) throw new Error("not a font file (truncated)")
+  const version = dv.getUint32(0)
+  if (version === TAG_TTCF) throw new Error("font collections (.ttc) aren't supported — export a single face")
+  if (version === TAG_WOFF || version === TAG_WOF2) throw new Error("WOFF/WOFF2 project fonts aren't supported — use the .ttf/.otf")
+  if (version !== TAG_TTF && version !== TAG_OTTO) throw new Error("not a TTF/OTF font file")
+
+  const numTables = dv.getUint16(4)
+  const tables = new Map<string, { offset: number, length: number }>()
+  for (let i = 0; i < numTables; i++) {
+    const rec = 12 + i * 16
+    if (rec + 16 > bytes.byteLength) throw new Error("not a font file (truncated table directory)")
+    const tag = String.fromCharCode(bytes[rec], bytes[rec + 1], bytes[rec + 2], bytes[rec + 3])
+    tables.set(tag, { offset: dv.getUint32(rec + 8), length: dv.getUint32(rec + 12) })
+  }
+
+  const family = readFamily(dv, bytes, tables.get("name"))
+  if (!family) throw new Error("no family name in the font's `name` table")
+
+  let weight = 400
+  let italic = false
+  const os2 = tables.get("OS/2")
+  if (os2 && os2.offset + 64 <= bytes.byteLength) {
+    weight = dv.getUint16(os2.offset + 4) // usWeightClass
+    italic = (dv.getUint16(os2.offset + 62) & 1) === 1 // fsSelection ITALIC
+  } else {
+    const head = tables.get("head")
+    if (head && head.offset + 46 <= bytes.byteLength) {
+      const macStyle = dv.getUint16(head.offset + 44)
+      if (macStyle & 1) weight = 700
+      italic = (macStyle & 2) === 2
+    }
+  }
+  if (weight < 1 || weight > 1000) weight = 400
+
+  return { family, weight, italic }
+}
+
+/** Best family name: typographic family (nameID 16) over legacy family (1); Windows-English
+ *  records over the rest. Returns "" when the table yields nothing decodable. */
+const readFamily = (dv: DataView, bytes: Uint8Array, name?: { offset: number, length: number }): string => {
+  if (!name || name.offset + 6 > bytes.byteLength) return ""
+  const base = name.offset
+  const count = dv.getUint16(base + 2)
+  const stringOffset = base + dv.getUint16(base + 4)
+
+  let best = ""
+  let bestScore = -1
+  for (let i = 0; i < count; i++) {
+    const rec = base + 6 + i * 12
+    if (rec + 12 > bytes.byteLength) break
+    const platformID = dv.getUint16(rec)
+    const languageID = dv.getUint16(rec + 4)
+    const nameID = dv.getUint16(rec + 6)
+    const length = dv.getUint16(rec + 8)
+    const offset = stringOffset + dv.getUint16(rec + 10)
+    if (nameID !== 16 && nameID !== 1) continue
+    if (offset + length > bytes.byteLength) continue
+
+    // nameID 16 beats 1; within an id, Windows-English > Windows > Unicode > Mac.
+    let score = nameID === 16 ? 100 : 0
+    if (platformID === 3) score += languageID === 0x409 ? 30 : 20
+    else if (platformID === 0) score += 10
+    if (score <= bestScore) continue
+
+    const text = platformID === 1 ? decodeLatin1(bytes, offset, length) : decodeUtf16be(bytes, offset, length)
+    if (!text.trim()) continue
+    best = text.trim()
+    bestScore = score
+  }
+  return best
+}
+
+const decodeUtf16be = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i + 1 < length; i += 2) out += String.fromCharCode((bytes[offset + i] << 8) | bytes[offset + i + 1])
+  return out
+}
+
+const decodeLatin1 = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i < length; i++) out += String.fromCharCode(bytes[offset + i])
+  return out
+}

package/runtime/sdk/compile/sourcemap.ts

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

package/runtime/sdk/inject.ts

@@ -81,6 +81,7 @@ export {
   UIScrollable, type UIScrollableStyle,
   UIPager, type UIPagerStyle,
   UITabs, type UITabDef,
+  defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,

package/runtime/sdk/ui/UI.ts

@@ -17,7 +17,7 @@ export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopove
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
 export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
 export { UIPager, type UIPagerStyle } from './UIPager'
-export { UITabs, type UITabDef } from './UITabs'
+export { UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle } from './UITabs'
 
 export { UIVirtualizedList } from './UIVirtualizedList'
 

package/runtime/sdk/ui/UITabs.ts

@@ -1,15 +1,16 @@
 import { PagerElement, type UIPager } from "./UIPager"
-import { ScreenElement, type UIScreen } from "./UIScreen"
+import { ScreenElement, UIScreen } from "./UIScreen"
 import { UIButton } from "./UIButton"
 import { UIRow, UIColumn, type UIRow as UIRowType } from "./UIContainer"
 import { UIText } from "./UIText"
 import { UIImage, type ImageSource } from "./UIImage"
+import type { UIChildArg } from "./UINode"
 
 // UITabs — the standard bottom-tab shell, prewired: a UIScreen composing [ UIPager (flexGrow: 1),
 // tab bar ]. Pure SDK composition over the pager — zero new ABI, works wherever UIPager does.
-// The build-mode twin of the design scaffold's `defineTabs` (lecodes-design/tabbar-surface.md):
-// same keyed config, same `tab-<id>` button names, same theme variables with the same fallbacks,
-// so a designed mockup and the built app render identically.
+// `defineTabs` (below) is its design-stage twin (lecodes-design/tabbar-surface.md): the same keyed
+// config without screens, mounted per-file with a literal tab id. They share the constants and bar
+// geometry in this file, so a designed mockup and the built app render identically.
 
 /** Active/inactive/bar colors ride the theme — one `theme({ primaryColor, mutedColor, tabbarBg })`
  *  call restyles the bar app-wide; the fallbacks keep an unthemed app looking right. */
@@ -173,3 +174,63 @@ export class TabsElement extends ScreenElement {
 export function UITabs(tabs: Record<string, UITabDef>): UITabs {
   return new TabsElement(tabs) as unknown as UITabs
 }
+
+// ---- defineTabs — the design-stage twin ---------------------------------------------------------
+
+/** A `defineTabs` tab: `label` + optional `icon` (an `assetIcon("lucide:…")` call — never a
+ *  hand-written source object). `UITabDef` is this plus the tab's root `screen`. */
+export type TabDef = Omit<UITabDef, "screen">
+
+/** What `defineTabs` returns: the bar (mount it yourself when the screen owns its whole layout)
+ *  and the standard screen shell around it. `active` must be a declared tab id, as a literal. */
+export type TabsHandle<T extends Record<string, TabDef>> = {
+  /** Tab ids in declaration order. */
+  ids: (keyof T & string)[]
+  /** The bar alone — one button per tab, the `active` one highlighted. */
+  bar(active: keyof T & string): UIRowType
+  /** A screen sitting ON the bar: `[ padded content column, bar ]`. */
+  screen(active: keyof T & string, ...children: UIChildArg[]): UIScreen
+}
+
+/**
+ * Declare a tab bar WITHOUT screens — the design-stage twin of {@link UITabs} (same keys, same
+ * `tab-<id>` button names, same theme variables), for mockups where every screen is its own file
+ * and mounts the bar with a literal tab id:
+ *
+ * ```ts
+ * export const mainTabs = defineTabs({
+ *   home:    { label: "Home",    icon: assetIcon("lucide:house") },
+ *   profile: { label: "Profile", icon: assetIcon("lucide:user") },
+ * })
+ * // in a screen file:
+ * export default () => mainTabs.screen("home", [ ...content ])
+ * ```
+ *
+ * Restyle through the theme — `theme({ primaryColor, mutedColor, tabbarBg, screenBg })` recolors
+ * every bar at once. The built app passes the same keys (plus each tab's root screen) to `UITabs`,
+ * which renders the identical bar interactively.
+ */
+export function defineTabs<T extends Record<string, TabDef>>(tabs: T): TabsHandle<T> {
+  const ids = Object.keys(tabs) as (keyof T & string)[]
+
+  const bar = (active: keyof T & string) =>
+    UIRow(ids.map((id) => {
+      const def = tabs[id]
+      const color = id === active ? ACTIVE : INACTIVE
+      return UIButton(
+        def.icon ? UIImage(def.icon).style({ width: 22, height: 22, tintColor: color }) : null,
+        UIText(def.label).style({ fontSize: 10, color }),
+      ).style({ name: `tab-${id}`, flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+    })).style({
+      name: "tabbar", bgColor: BAR_BG, pb: "comfort-bottom",
+      borderTopWidth: 1, borderTopColor: BAR_BORDER,
+    })
+
+  const screen = (active: keyof T & string, ...children: UIChildArg[]) =>
+    UIScreen(
+      UIColumn(...children).style({ flexGrow: 1, p: 16, pt: "safe-top" }),
+      bar(active),
+    ).style({ bgColor: SCREEN_BG })
+
+  return { ids, bar, screen }
+}