lecodes-sdk 0.19.0

package/src/compile/bundler.ts

@@ -0,0 +1,287 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { createRequire } from "node:module"
+import { dirname, join, relative } from "node:path"
+import { fileURLToPath } from "node:url"
+import { collectAssetMacros, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
+import type { ScanModule } from "./detectEntry"
+import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
+import { hasImportStatement, rewriteLibraryImports } from "./libraryImports"
+
+/*
+ * The user-project bundler. Project files live in an in-memory map; the whole SDK is delivered via
+ * chisel's `inject` so user code uses globals (Scene, Sprite, toast, …) with NO imports. chisel — the
+ * Rust method-granular bundler (@letary/chisel) — tree-shakes the injected SDK down to what the
+ * project references, including unused class *methods*. It is the only bundler (the esbuild fallback
+ * is gone). Bare imports are a hard error (chisel's resolver enforces it).
+ */
+
+export type MemoryFiles = Record<string, string>
+
+/** Locate the SDK inject entry: an explicit override (LECODES_SDK_INJECT — used by the published CLI,
+ *  which vendors the SDK source), else the source in-repo. chisel needs the SOURCE tree (not a bundle). */
+const resolveInject = (): string => {
+  const override = process.env.LECODES_SDK_INJECT
+  if (override && existsSync(override)) return override
+  const here = dirname(fileURLToPath(import.meta.url)) // …/sdk/src/compile — portable (Node + Bun)
+  const src = join(here, "..", "inject.ts")
+  if (existsSync(src)) return src
+  throw new Error("sdk: could not locate the inject source (LECODES_SDK_INJECT / src/inject.ts)")
+}
+
+const normalize = (path: string): string => {
+  const parts: string[] = []
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+// ---- chisel (Rust) bundler -------------------------------------------------------------------
+//
+// chisel is fed an in-memory file map over JSON-stdio: the SDK source under `/__sdk/…` (injected via
+// `/__sdk/inject.ts`), the project files at their own paths, and a `define` map. It does
+// method-granular tree-shaking + (when minify is on) compress + mangle. Assets/shaders/svg reach it
+// as `asset()` macros desugared to default imports; aspect names are injected as `static aspect`.
+
+// `EDITOR` is a boolean define: `false` (const-folded, `if (EDITOR)` branches DCE'd away) in
+// every shipped bundle, `true` only in scene-editor compiles (CompileOptions.editor). Requires a
+// chisel with boolean-define support — an older binary ignores the entry and leaves `EDITOR` as a
+// free identifier (a runtime ReferenceError only in code that actually uses it).
+const CHISEL_DEFINE: Record<string, string> = { RAD2DEG: "57.29577951308232", DEG2RAD: "0.017453292519943295" }
+
+// Methods the native host invokes by name have no in-bundle caller, so method-DCE can't see them.
+// The SDK prefixes its framework / host-facing methods with `_` (`_emitTouchStart`, `_emitClick`,
+// `_onSlotEvent`, `_emitCollision`, …), so keep every underscore-prefixed method on classes that survive.
+const CHISEL_KEEP = [ "_*" ]
+
+/** The two inject modules (paths inside chisel's file map, see collectSdkFiles): the client SDK
+ *  (every UI/2D/3D global) and the server SDK (`t`, `model`, `defineDb`, `channel`, … — see
+ *  src/server/inject.ts). A bundle gets exactly one of them. */
+export const CLIENT_INJECT = "/__sdk/inject.ts"
+export const SERVER_INJECT = "/__sdk/server/inject.ts"
+
+/** The SDK source root (parent of `inject.ts`). chisel needs the source tree, not a prebuilt bundle. */
+const resolveSdkSrc = (): string => {
+  const inject = resolveInject()
+  if (!inject.endsWith("inject.ts")) {
+    throw new Error(`chisel needs the SDK source tree (src/inject.ts); got ${inject}. Set LECODES_SDK_INJECT to the source.`)
+  }
+  return dirname(inject)
+}
+
+const isSdkSource = (path: string) =>
+  /\.[tj]s$/.test(path) && !path.endsWith(".d.ts") &&
+  !path.includes("/compile/") && !path.includes("/tests/") && !path.includes("/__tests__/")
+
+// The SDK tree doesn't change within a process — read it once.
+const sdkFilesCache = new Map<string, MemoryFiles>()
+const collectSdkFiles = (sdkSrc: string): MemoryFiles => {
+  const cached = sdkFilesCache.get(sdkSrc)
+  if (cached) return cached
+  const out: MemoryFiles = {}
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) walk(p)
+      else if (isSdkSource(p)) out["/__sdk/" + relative(sdkSrc, p).split("\\").join("/")] = readFileSync(p, "utf8")
+    }
+  }
+  walk(sdkSrc)
+  sdkFilesCache.set(sdkSrc, out)
+  return out
+}
+
+/** Locate the chisel binary: an explicit override (LECODES_CHISEL_BIN), else the prebuilt binary from
+ *  the @letary/chisel npm package (which resolves the platform via optional @letary/chisel-<platform>). */
+const resolveChiselBin = (): string => {
+  const override = process.env.LECODES_CHISEL_BIN
+  if (override) {
+    if (existsSync(override)) return override
+    throw new Error(`LECODES_CHISEL_BIN points at a missing file: ${override}`)
+  }
+  try {
+    const bin = createRequire(import.meta.url)("@letary/chisel").binaryPath() as string | null
+    if (bin && existsSync(bin)) return bin
+  } catch { /* @letary/chisel (or its platform binary) not installed */ }
+  throw new Error("chisel binary not found. Install @letary/chisel, or set LECODES_CHISEL_BIN.")
+}
+
+/** Parse every module in `files` via chisel scan (no bundling): resolved local imports +
+ *  hasExports per file. Null when the binary is missing or predates scan mode (it then rejects
+ *  the entry-less input) — detectEntry then falls back to its regex scanner. Passed into
+ *  `detectEntry` as its `scanner` by every node caller (detectEntry itself stays browser-safe). */
+export const scanModulesChisel = (files: MemoryFiles): Record<string, ScanModule> | null => {
+  let bin: string
+  try {
+    bin = resolveChiselBin()
+  } catch {
+    return null
+  }
+  const input = JSON.stringify({ scan: true, files })
+  const r = spawnSync(bin, [], { input, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 })
+  if (r.status !== 0 || r.error) return null
+  try {
+    const parsed = JSON.parse(r.stdout || "{}") as { scan?: Record<string, ScanModule> }
+    return parsed.scan ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every `asset('…')` must name a file that's actually in the compile input — a missing one is a
+ * COMPILE ERROR, never a fallback.
+ *
+ * chisel used to turn an asset import with no backing module into `const x = "<the specifier>"`:
+ * a relative source path nothing resolves at runtime, so the app got a silently broken reference
+ * (and, since the desugared imports are appended, a const declared after its own use — a TDZ
+ * ReferenceError at boot that read like a bundler crash). Reporting the call site here instead
+ * names the real problem: the file isn't there.
+ */
+const assertAssetsExist = (refs: { file: string, ref: AssetMacroRef }[], files: MemoryFiles) => {
+  const missing: string[] = []
+  for (const { file, ref } of refs) {
+    // Bare specifiers aren't paths at all — chisel reports those as bare imports.
+    if (!ref.path.startsWith("./") && !ref.path.startsWith("../") && !ref.path.startsWith("/")) continue
+    const dir = file.slice(0, file.lastIndexOf("/"))
+    const base = ref.path.startsWith("/") ? normalize(ref.path) : normalize(`${dir}/${ref.path}`)
+    // Same candidate list chisel's resolver uses, so "found here" means "found there".
+    const found = [ base, `${base}.ts`, `${base}.js`, `${base}/index.ts` ].some(c => files[c] !== undefined)
+    if (!found) missing.push(`asset not found: ${ref.path} (${file.replace(/^\//, "")}:${ref.line})`)
+  }
+  if (missing.length > 0) throw new Error(missing.join("\n"))
+}
+
+const bundleProjectChisel = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife",
+  sourcemap: boolean,
+  minifyOverride?: boolean,
+  editor?: boolean,
+  libraries?: Record<string, MemoryFiles>,
+  inject: string = CLIENT_INJECT,
+): Promise<{ code: string, map: string | null, diagnostics: string[] }> => {
+  const entry = normalize(entrypoint)
+  const slugs = new Set(Object.keys(libraries ?? {}))
+  // Per-file source transforms (project files only — SDK aspects declare their own `static aspect`):
+  //  - rewrite bare library imports (`from "acme-ui"`) → the injected `/__lib/<slug>/…` tree
+  //  - desugar `asset('./x')` → a default import that resolves to the synthetic asset module
+  //  - inject `static aspect = '<name>'` from `class … extends Aspect<'<name>', …>`
+  const projFiles: MemoryFiles = {}
+  const assetRefs: { file: string, ref: AssetMacroRef }[] = []
+  for (const [ k, v ] of Object.entries(files)) {
+    const path = normalize(k)
+    let src = v
+    if (/\.[tj]sx?$/.test(path)) {
+      if (hasImportStatement(src)) src = rewriteLibraryImports(src, slugs)
+      if (hasAssetMacro(src)) {
+        const found = collectAssetMacros(src, path)
+        for (const ref of found) assetRefs.push({ file: path, ref })
+        src = desugarAssetMacros(src, path, found)
+      }
+      if (hasAspectExtends(src)) src = injectAspectNames(src)
+    }
+    projFiles[path] = src
+  }
+  if (!projFiles[entry]) throw new Error(`Entrypoint not found: ${entry}`)
+
+  // Library dependencies: merge each library's files under /__lib/<slug>/… (like /__sdk/…). They
+  // get the same asset/aspect desugaring as project code, but NOT the bare-import rewrite — a
+  // library can't declare dependencies (flat graph v1), so any bare import in a library is an
+  // error chisel surfaces. Library-internal relative imports resolve within the prefix untouched.
+  for (const [ slug, libFiles ] of Object.entries(libraries ?? {})) {
+    for (const [ k, v ] of Object.entries(libFiles)) {
+      const path = normalize(`/__lib/${slug}/${k}`)
+      let src = v
+      if (/\.[tj]sx?$/.test(path)) {
+        if (hasAssetMacro(src)) {
+          const found = collectAssetMacros(src, path)
+          for (const ref of found) assetRefs.push({ file: path, ref })
+          src = desugarAssetMacros(src, path, found)
+        }
+        if (hasAspectExtends(src)) src = injectAspectNames(src)
+      }
+      projFiles[path] = src
+    }
+  }
+
+  assertAssetsExist(assetRefs, projFiles)
+
+  const sdkFiles = collectSdkFiles(resolveSdkSrc())
+  // Shipped bundles minify by default; edit-mode bundles pass `false` — mangling erases class
+  // names, which the scene editor matches aspect schemas by (`describeAspect().className`).
+  const minify = minifyOverride ?? (process.env.LECODES_CHISEL_MINIFY !== "0")
+  const input = JSON.stringify({
+    files: { ...sdkFiles, ...projFiles },
+    entry,
+    inject: [ inject ],
+    format,
+    minify,
+    // Chain fusion, ON by default (`LECODES_CHISEL_FUSE=0` opts out): Vec3/date math chains lower to
+    // scalar arithmetic (bit-exact — JS numbers are f64 and the lowering never reassociates) and
+    // particle `curve()`/`colorCurve()` chains constant-fold into the exact native Float32Array.
+    fuse: process.env.LECODES_CHISEL_FUSE !== "0",
+    define: { ...CHISEL_DEFINE, EDITOR: editor ? "true" : "false" },
+    keep: CHISEL_KEEP,
+    sourcemap,
+    // Reactive-UI desugaring (memoized children .map → __uiMap + auto-wrapped signal reads in
+    // UIText/style args). Only fires on free references to the injected globals, i.e. user code.
+    // An older chisel binary ignores the unknown field — bundles still work, children just
+    // rebuild per change instead of reusing nodes.
+    reactive_ui: process.env.LECODES_CHISEL_REACTIVE_UI !== "0",
+    // Flatten literal array args of UI factory calls into variadic args (`UIColumn([a, b])` →
+    // `UIColumn(a, b)`) — the SDK's buildUI dispatch flattens array args one level anyway, so
+    // this only drops an array allocation per call site. Safe to always request: the sibling SDK
+    // source above has the variadic dispatch, and an older binary ignores the unknown field.
+    flatten_ui: process.env.LECODES_CHISEL_FLATTEN_UI !== "0",
+  })
+
+  const bin = resolveChiselBin()
+  const r = spawnSync(bin, [], { input, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 })
+  if (r.status === 2 || r.error) {
+    throw new Error(`chisel failed: ${r.error?.message ?? r.stderr ?? "unknown error"}`)
+  }
+  let parsed: { code?: string, map?: string, error?: string, diagnostics?: string[] }
+  try {
+    parsed = JSON.parse(r.stdout || "{}")
+  } catch {
+    throw new Error(`chisel produced invalid output: ${(r.stdout || r.stderr || "").slice(0, 200)}`)
+  }
+  if (parsed.error) throw new Error(`chisel: ${parsed.error}`)
+  if (parsed.code == null) throw new Error("chisel produced no code")
+  // Non-fatal build-time findings (`path:line:col: message`) — today: particle curve chains the
+  // engine would reject at set time. Warn so they're visible in the CLI / server log; the bundle
+  // itself is unaffected (chisel leaves an invalid chain as real calls).
+  const diagnostics = parsed.diagnostics ?? []
+  for (const d of diagnostics) console.warn(`warning: ${d}`)
+  return { code: parsed.code, map: parsed.map ?? null, diagnostics }
+}
+
+/**
+ * Bundle the project `files` (path → source) starting at `entrypoint`, with the SDK injected.
+ * `format` is "esm" by default (what the platform ships); "iife" produces a self-running script.
+ */
+export const bundleProject = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife" = "esm",
+): Promise<string> => (await bundleProjectChisel(entrypoint, files, format, false)).code
+
+/** Like `bundleProject`, but also returns chisel's source map (and any build-time `diagnostics`).
+ *  The map's `sources` are the original module paths and its generated positions are relative to
+ *  `code` (line 1 = first line of `code`). Pass `sourcemap: false` to skip map generation entirely —
+ *  `map` then comes back null. */
+export const bundleProjectWithMap = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife" = "esm",
+  minify?: boolean,
+  editor?: boolean,
+  libraries?: Record<string, MemoryFiles>,
+  sourcemap = true,
+  inject?: string,
+): Promise<{ code: string, map: string | null, diagnostics: string[] }> => bundleProjectChisel(entrypoint, files, format, sourcemap, minify, editor, libraries, inject)

package/src/compile/compileProject.ts

@@ -0,0 +1,127 @@
+// Turns a project's files into the esbuild input map + entrypoint + metadata header, then bundles.
+// The one canonical "user project → deployable bundle" path: the backend and CLI both call this
+// (the backend resolves asset URLs from the DB, the CLI from local metadata — same function, the
+// URLs are passed in as `publicUrl` + per-entry `fileSrc`/`shaders`).
+
+import { bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bundler"
+import { detectEntry } from "./detectEntry"
+import { buildHeader } from "./header"
+import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
+import { stubServerEntries } from "./serverSplit"
+
+export type CompileFileType = "text" | "resource" | "shader"
+
+export type CompileEntry = {
+  path: string
+  type: CompileFileType
+  /** Source text for code / .svg files. */
+  text?: string
+  /** Server src for a binary resource (e.g. "/uploads/x.png"); prefixed with publicUrl. */
+  fileSrc?: string
+  /** Under `localAssets`: keep THIS resource in the URL form (publicUrl + fileSrc) anyway — for
+   *  hosts that bundle most assets locally but stream heavy ones (e.g. videos) from the server. */
+  remote?: boolean
+  /** Compiled-shader artifacts (platform + src); the first drives the per-backend URL. */
+  shaders?: { platform: string, src: string }[]
+  /** `shaders` are LOCAL files staged next to the bundle (bare artifact names, not server srcs):
+   *  the module compiles to a fetchLocal lookup instead of a URL. Set by the CLI's local shader
+   *  compile for hosts with no asset server (the desktop host). */
+  shadersLocal?: boolean
+}
+
+export type CompileOptions = {
+  entries: CompileEntry[]
+  name: string
+  publicUrl: string
+  entryOverride?: string
+  /** Prepend the metadata header (default true). */
+  header?: boolean
+  /** Generated-icon URL for the header (backend only). */
+  icon?: string
+  /** `// fonts:` header payload (from the font() macro pass the caller ran over the entries). */
+  fontsHeader?: string
+  /** `// icons:` header payload (from the assetIcon() macro pass the caller ran over the entries). */
+  iconsHeader?: string
+  /** "esm" (default, shipped) or "iife" (self-running, for the local renderer). */
+  format?: "esm" | "iife"
+  /** Resolve `asset()` resources to a LOCAL host asset at runtime instead of a `publicUrl` URL: each
+   *  resource compiles to `"id:" + _creatorUtils.fetchLocal(<name>)` (the host reads the file by name
+   *  and returns its systemId). For hosts with no asset server (the desktop native host), where a URL
+   *  can't be fetched. Off by default — the shipped/web build keeps the URL form. */
+  localAssets?: boolean
+  /** Override minification (default: on, `LECODES_CHISEL_MINIFY` env aside). Scene-editor bundles
+   *  compile with `false`: mangling erases class names, which the editor matches aspect schemas by. */
+  minify?: boolean
+  /** Generate a source map (default true) and inline it into the bundle. `false` skips the map
+   *  entirely — a smaller bundle, but runtime errors report generated positions only. */
+  sourcemap?: boolean
+  /** Editor compile: the `EDITOR` global compiles to `true` (scene-editor bundles). Default false —
+   *  shipped bundles get `EDITOR` = `false`, const-folded so `if (EDITOR)` branches are DCE'd. */
+  editor?: boolean
+  /** Component-library dependencies: slug → the library's files (root-relative paths). Merged under
+   *  `/__lib/<slug>/…` and reachable from project code via `import … from "<slug>"`. See
+   *  docs/library-system-plan.md §4. */
+  libraries?: Record<string, MemoryFiles>
+  /** Base URL of the project's deployed server (draft or prod), baked into the RPC/channel stubs
+   *  that replace every `*.server.ts` module in the client bundle (docs/backend-plan.md §4). Server
+   *  files never reach the client bundle either way; with no URL, calling an endpoint fails with
+   *  "server not deployed". */
+  serverUrl?: string
+}
+
+export const compileProject = async (opts: CompileOptions): Promise<string> => {
+  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
+  }
+
+  const files: Record<string, string> = {}
+  for (const e of entries) {
+    if (e.type === "resource") {
+      if (opts.localAssets && !e.remote) {
+        // The host resolves the asset by name at runtime (reads the local file → systemId); the
+        // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
+        const name = e.path.split(/[\\/]/).pop() ?? e.path
+        files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
+      } else {
+        files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
+      }
+    } else if (e.type === "shader") {
+      const shaders = e.shaders ?? []
+      if (e.shadersLocal && shaders.length > 0) {
+        // Artifacts compiled locally and staged NEXT TO the bundle (no asset server): the host
+        // reads them by name through the same fetchLocal door the built-in materials use
+        // (`Material.lit` → fetchLocal("lit.filamat")), and Material.load parses the "id:" scheme.
+        // The name is built at RUNTIME because one bundle serves every native backend — the
+        // desktop host reports "desktop" on Windows and "opengl" on Linux, iOS "metal".
+        // Only entries the CLI actually compiled+staged carry `shadersLocal`; server artifacts
+        // (URLs) and un-staged ones keep the URL forms below.
+        const name = shaders[0].src.split(/[\\/]/).pop() ?? ""
+        const [prefix, suffix = ".filamat"] = name.split("_opengl")
+        files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
+      } else if (shaders.length > 0) {
+        files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.backend}")}\``
+      } else {
+        files[e.path] = `export default ""` // local-only shader with no compiled artifact yet
+      }
+    } else if (e.path.toLowerCase().endsWith(".svg")) {
+      files[e.path] = `export default SvgSource(\`${e.text ?? ""}\`)`
+    } else {
+      files[e.path] = e.text ?? ""
+    }
+  }
+
+  const { code, map } = await bundleProjectWithMap(
+    entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
+  )
+  if (opts.header === false) {
+    return map ? `${code}\n${inlineSourceMapComment(map)}` : code
+  }
+  const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader })
+  if (!map) return header + code
+  // Shift the map down past the header (prepended before the code); the inline comment lands last.
+  const headerLines = (header.match(/\n/g) ?? []).length
+  return `${header}${code}\n${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`
+}

package/src/compile/detectEntry.ts

@@ -0,0 +1,128 @@
+// Entrypoint detection from the project's import graph. The entry is the file no other project
+// file imports (an import-graph root): a side-effect registration module is imported by the entry,
+// so it stops being a candidate, and the entry itself may freely use `export`.
+//
+// Pick order among roots: `/main.ts` (the documented convention) → export-free roots by size →
+// any root by size. `roots.length > 1` without a `/main.ts` means the choice was ambiguous —
+// CLI callers surface that as a warning suggesting `main.ts` or `--entry`.
+//
+// This module is intentionally dependency-free (no node imports) so the FRONTEND can run the same
+// detection live in the editor. Node callers inject chisel's `scan` mode (real parser — comments,
+// strings, `import type` handled correctly) via the `scanner` parameter (`scanModulesChisel` from
+// bundler.ts); without one — in the browser, or with a pre-scan chisel binary — the regex fallback
+// below runs over the same resolution rules.
+
+type Files = Record<string, string>
+
+/** Per-module facts entry detection consumes (chisel `scan` output shape). */
+export type ScanModule = { imports: string[], hasExports: boolean, error?: string }
+
+/** A pluggable module scanner: path→source in, per-module facts out (null = unavailable). */
+export type ModuleScanner = (files: Files) => Record<string, ScanModule> | null
+
+export type DetectEntryInput = {
+  path: string
+  type?: string
+  text?: string | null
+}
+
+export type DetectedEntry = {
+  /** The chosen entry path ("" when the project has no candidate module at all). */
+  entry: string
+  /** Import-graph roots. More than one (without a `/main.ts` among them) = ambiguous choice. */
+  roots: string[]
+}
+
+/** The conventional entry filename — always wins when it is an import-graph root. */
+export const ENTRY_CONVENTION = "/main.ts"
+
+const isCode = (path: string) => /\.[tj]s$/.test(path) && !path.endsWith(".d.ts")
+/** Never entries: editor plugins and server modules (docs/backend-plan.md — a `*.server.ts` nobody
+ *  imports is still not the app; server files compile into their own bundle). */
+const isNonEntry = (path: string) => path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path)
+
+const normalize = (path: string): string => {
+  const parts: string[] = []
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+const dirOf = (path: string): string => {
+  const i = path.lastIndexOf("/")
+  return i <= 0 ? "/" : path.slice(0, i)
+}
+
+/** Mirror of chisel's resolver: relative/absolute specifiers only, `.ts`/`.js`/`/index.ts`
+ *  fallback, exact match first. Null for bare imports (libraries) and unresolved paths. */
+const resolveSpec = (files: Files, importer: string, spec: string): string | null => {
+  if (!spec.startsWith("./") && !spec.startsWith("../") && !spec.startsWith("/")) return null
+  const base = normalize(spec.startsWith("/") ? spec : dirOf(importer) + "/" + spec)
+  for (const cand of [base, base + ".ts", base + ".js", base + "/index.ts"]) {
+    if (cand in files) return cand
+  }
+  return null
+}
+
+// One pattern, two alternatives: `import|export … from "<spec>"` (multi-line safe — the specifier
+// clause may sit on a later line) and a side-effect `import "<spec>"`.
+const IMPORT_RE = /(?:^|[\n;])\s*(?:import|export)\b[^'"`]*?\bfrom\s*['"]([^'"\n]+)['"]|(?:^|[\n;])\s*import\s*['"]([^'"\n]+)['"]/g
+const EXPORT_RE = /(?:^|[\n;])\s*export\b/
+
+/** Regex fallback for a chisel binary without scan support. Same output shape; less precise
+ *  (a specifier inside a comment counts, `export type` counts as an export) — both only affect
+ *  which root wins a tie, never whether the true entry is a root. */
+export const scanModulesFallback = (files: Files): Record<string, ScanModule> => {
+  const out: Record<string, ScanModule> = {}
+  for (const [path, text] of Object.entries(files)) {
+    const imports: string[] = []
+    for (const m of text.matchAll(IMPORT_RE)) {
+      const target = resolveSpec(files, path, m[1] ?? m[2] ?? "")
+      if (target && isCode(target) && !imports.includes(target)) imports.push(target)
+    }
+    out[path] = { imports, hasExports: EXPORT_RE.test(text) }
+  }
+  return out
+}
+
+/**
+ * Detect the project's entrypoint. `entries` is the full project file list; only `.ts`/`.js` text
+ * files participate (`.d.ts`, `.editor.ts` and `*.server.ts` are never entries, and editor-only imports don't
+ * remove a file from candidacy — production compiles don't bundle editor plugins).
+ */
+export const detectEntry = (entries: DetectEntryInput[], scanner?: ModuleScanner): DetectedEntry => {
+  const files: Files = {}
+  for (const e of entries) {
+    if (e.type !== undefined && e.type !== "text") continue
+    if (typeof e.text !== "string") continue
+    const path = normalize(e.path.split("\\").join("/"))
+    if (isCode(path)) files[path] = e.text
+  }
+
+  const candidates = Object.keys(files).filter((p) => !isNonEntry(p))
+  if (candidates.length === 0) return { entry: "", roots: [] }
+
+  const scan = scanner?.(files) ?? scanModulesFallback(files)
+
+  const imported = new Set<string>()
+  for (const [path, mod] of Object.entries(scan)) {
+    if (path.endsWith(".editor.ts")) continue
+    for (const target of mod.imports) imported.add(target)
+  }
+
+  let roots = candidates.filter((p) => !imported.has(p))
+  // Everything imported (a cycle through every file) — degrade to all candidates.
+  if (roots.length === 0) roots = candidates
+
+  if (roots.includes(ENTRY_CONVENTION)) return { entry: ENTRY_CONVENTION, roots }
+
+  // Export-free roots are scripts — the old heuristic's signal, kept as the tie-breaker so
+  // existing projects resolve the same way; a lone exporting root is still a valid entry.
+  const scripts = roots.filter((p) => !scan[p]?.hasExports)
+  const pool = scripts.length > 0 ? scripts : roots
+  const bySize = [...pool].sort((a, b) => files[b].length - files[a].length)
+  return { entry: bySize[0], roots }
+}