lecodes-sdk 0.19.0

package/src/compile/serverSplit.ts

@@ -0,0 +1,233 @@
+/**
+ * The client/server split of a project (docs/backend-plan.md §4).
+ *
+ * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__serverOnly` — client SDK
+ * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
+ * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
+ * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
+ * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
+ *
+ * Export kinds are found by a static scan (no TS program needed): a function export is an
+ * endpoint, a `channel(...)` export is a channel, anything else is server-only.
+ */
+
+import type { AppConfig } from "../server/auth/appConfig"
+import { bundleProjectWithMap, SERVER_INJECT, type MemoryFiles } from "./bundler"
+import type { CompileEntry } from "./compileProject"
+import { deriveEndpointParams } from "./serverTypes"
+
+export const SERVER_FILE = /\.server\.[tj]s$/
+export const isServerPath = (path: string) => SERVER_FILE.test(path)
+
+/** Project path → endpoint-id prefix: no leading `./` or `/`, forward slashes. */
+export const serverModuleId = (path: string) => path.split("\\").join("/").replace(/^(\.\/|\/)+/, "")
+
+export type ServerExportKind = "fn" | "channel" | "other"
+export type ServerExport = { name: string, kind: ServerExportKind }
+
+// ───────────────────────────── static export scan ─────────────────────────────
+
+/** Blank out comments and string/template contents (keeps line structure) so the regexes below don't
+ *  trip on `export` inside a comment or a string. */
+export const blankCommentsAndStrings = (src: string): string => {
+  let out = ""
+  let i = 0
+  const n = src.length
+  while (i < n) {
+    const c = src[i], d = src[i + 1]
+    if (c === "/" && d === "/") { while (i < n && src[i] !== "\n") { out += " "; i++ } continue }
+    if (c === "/" && d === "*") {
+      out += "  "; i += 2
+      while (i < n && !(src[i] === "*" && src[i + 1] === "/")) { out += src[i] === "\n" ? "\n" : " "; i++ }
+      out += "  "; i += 2; continue
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      const q = c
+      out += q; i++
+      while (i < n && src[i] !== q) {
+        if (src[i] === "\\") { out += "  "; i += 2; continue }
+        out += src[i] === "\n" ? "\n" : " "; i++
+      }
+      out += q; i++; continue
+    }
+    out += c; i++
+  }
+  return out
+}
+
+const IDENT = "[A-Za-z_$][\\w$]*"
+const classifyInit = (init: string): ServerExportKind => {
+  const s = init.trimStart()
+  if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^(async\s+)?function\b/.test(s)) return "fn"
+  if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
+  if (new RegExp(`^${IDENT}\\s*=>`).test(s)) return "fn"           // x => …
+  if (/^\(/.test(s)) {
+    // `(a, b) => …` — find the matching paren and look for `=>` (a type annotation may sit between)
+    let depth = 0
+    for (let i = 0; i < s.length; i++) {
+      if (s[i] === "(") depth++
+      else if (s[i] === ")") { depth--; if (depth === 0) return /^\s*(:[^=]*)?=>/.test(s.slice(i + 1)) ? "fn" : "other" }
+    }
+  }
+  return "other"
+}
+
+/** Exported names of a server module with their kinds. Default exports are rejected. */
+export const scanServerExports = (source: string, path = "<server module>"): ServerExport[] => {
+  const src = blankCommentsAndStrings(source)
+  if (/(^|\n)\s*export\s+default\b/.test(src)) {
+    throw new Error(`${path}: default exports are not endpoints — use named exports`)
+  }
+  // (position, name, kind) — kept in source order so ids/manifests are stable and readable
+  const found: { at: number, name: string, kind: ServerExportKind }[] = []
+  const add = (at: number, name: string, kind: ServerExportKind) => {
+    const i = found.findIndex(f => f.name === name)
+    if (i >= 0) found[i] = { at: found[i].at, name, kind }
+    else found.push({ at, name, kind })
+  }
+  // export [async] function name / export function* name
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(async\\s+)?function\\s*\\*?\\s*(${IDENT})`, "g"))) add(m.index!, m[3], "fn")
+  // export const|let|var name [: T] = init
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(?:const|let|var)\\s+(${IDENT})\\s*(?::[^=]*?)?=\\s*([^\\n]*)`, "g"))) {
+    add(m.index!, m[2], classifyInit(m[3]))
+  }
+  // export class name → server-only
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+class\\s+(${IDENT})`, "g"))) add(m.index!, m[2], "other")
+  // export { a, b as c } → classify by the local declaration
+  for (const m of src.matchAll(/(^|\n)\s*export\s*\{([^}]*)\}/g)) {
+    for (const part of m[2].split(",")) {
+      const [local, exported] = part.split(/\s+as\s+/).map(s => s.trim())
+      if (!local || /^type\s/.test(local)) continue
+      const name = exported ?? local
+      let kind: ServerExportKind = "other"
+      if (new RegExp(`(^|\\n)\\s*(async\\s+)?function\\s*\\*?\\s*${local}\\b`).test(src)) kind = "fn"
+      else {
+        const decl = src.match(new RegExp(`(^|\\n)\\s*(?:const|let|var)\\s+${local}\\s*(?::[^=]*?)?=\\s*([^\\n]*)`))
+        if (decl) kind = classifyInit(decl[2])
+      }
+      add(m.index!, name, kind)
+    }
+  }
+  return found.sort((a, b) => a.at - b.at).map(({ name, kind }) => ({ name, kind }))
+}
+
+// ───────────────────────────── client stubs ─────────────────────────────
+
+/** The client-side replacement of a `*.server.ts` module. `serverUrl` is baked in (draft/prod are
+ *  separate compiles); "" means "no server deployed" — calls fail with a clear error. */
+export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string): string => {
+  const mod = serverModuleId(path)
+  const url = JSON.stringify(serverUrl)
+  const lines = exports.map(({ name, kind }) => {
+    const id = JSON.stringify(`${mod}#${name}`)
+    if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
+    if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    return `export const ${name} = __serverOnly(${id})`
+  })
+  return `// client stub of ${mod} — generated by the lecodes compiler\n${lines.join("\n")}\n`
+}
+
+// ───────────────────────────── server entry ─────────────────────────────
+
+export const SERVER_ENTRY_PATH = "/.server-entry.ts"
+/** The SDK's app-config placeholder (src/server/auth/appConfig.ts) — the compile overrides it in the file map
+ *  with the project's real values (project files win over SDK files), so `auth.model.user()` and friends see
+ *  app.json as an ordinary import. */
+export const APP_CONFIG_PATH = "/__sdk/server/auth/appConfig.ts"
+
+/** Compile-time manifest embedded in the server bundle (validators land here — see serverTypes.ts). */
+export type ServerManifest = {
+  modules: Record<string, ServerExport[]>
+  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated). */
+  params?: Record<string, unknown[]>
+  /** The `app.json` subset the server runtime reads (name, auth providers); the bundle itself gets it as the
+   *  compiled-in `appConfig` module (APP_CONFIG_PATH). */
+  app?: AppConfig
+  /** Some server file references the `auth` global: the runner then resolves a device session on every
+   *  request (minting one on first contact). Projects that never touch `auth` pay nothing. */
+  usesAuth?: boolean
+}
+
+/** The synthetic entry: imports every export by name (chisel has no namespace imports) and registers
+ *  the module map + manifest on `globalThis.__lecodesServer` — a side effect chisel keeps. */
+export const serverEntrySource = (modules: Record<string, ServerExport[]>, manifest: ServerManifest): string => {
+  const imports: string[] = []
+  const entries: string[] = []
+  Object.entries(modules).forEach(([path, exports], i) => {
+    const names = exports.map(e => `${e.name} as m${i}_${e.name}`).join(", ")
+    if (names) imports.push(`import { ${names} } from ${JSON.stringify(path)}`)
+    else imports.push(`import ${JSON.stringify(path)}`)
+    const props = exports.map(e => `${JSON.stringify(e.name)}: m${i}_${e.name}`).join(", ")
+    entries.push(`${JSON.stringify(serverModuleId(path))}: { ${props} }`)
+  })
+  return `${imports.join("\n")}\n;(globalThis as any).__lecodesServer = { modules: { ${entries.join(", ")} }, manifest: ${JSON.stringify(manifest)} }\n`
+}
+
+const normalizePath = (path: string) => {
+  const parts: string[] = []
+  for (const part of path.split("\\").join("/").split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+/** Scan every `*.server.ts` entry → module path → exports. Throws on a default export. */
+export const scanServerModules = (entries: CompileEntry[]): Record<string, ServerExport[]> => {
+  const out: Record<string, ServerExport[]> = {}
+  for (const e of entries) {
+    if (e.type !== "text" || !isServerPath(e.path)) continue
+    out[normalizePath(e.path)] = scanServerExports(e.text ?? "", serverModuleId(e.path))
+  }
+  return out
+}
+
+/** Replace each `*.server.ts` entry with its client stub (returns a new entries array). */
+export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] =>
+  entries.map(e => e.type === "text" && isServerPath(e.path)
+    ? { ...e, text: serverStubSource(e.path, scanServerExports(e.text ?? "", serverModuleId(e.path)), serverUrl) }
+    : e)
+
+export type CompileServerOptions = {
+  entries: CompileEntry[]
+  /** Derive per-endpoint argument validators from the TS parameter types (serverTypes.ts) and embed
+   *  them in the manifest. Default true; throws `EndpointTypeError` on non-JSON parameter types. */
+  validate?: boolean
+  /** Precomputed param schemas to embed instead of deriving them. */
+  params?: Record<string, unknown[]>
+  /** Server bundles are readable by default (stack traces in the server console). */
+  minify?: boolean
+  sourcemap?: boolean
+  /** The project's `app.json` (name + auth providers) — embedded in the manifest and exposed to the bundle. */
+  app?: AppConfig
+}
+
+/** Bundle the project's server side. Returns the code (a script that registers
+ *  `globalThis.__lecodesServer`) and the manifest; `null` when the project has no server files. */
+export const compileServerBundle = async (opts: CompileServerOptions): Promise<{ code: string, manifest: ServerManifest } | null> => {
+  const modules = scanServerModules(opts.entries)
+  if (Object.keys(modules).length === 0) return null
+  const files: MemoryFiles = {}
+  for (const e of opts.entries) {
+    if (e.type !== "text") continue
+    if (e.path.toLowerCase().endsWith(".svg")) continue
+    files[normalizePath(e.path)] = e.text ?? ""
+  }
+  let params = opts.params
+  if (!params && opts.validate !== false) {
+    const derived = await deriveEndpointParams(opts.entries, modules)
+    for (const w of derived.warnings) console.warn(`warning: ${w}`)
+    params = derived.params
+  }
+  const usesAuth = opts.entries.some(e => e.type === "text" && isServerPath(e.path) && /\bauth\s*\./.test(blankCommentsAndStrings(e.text ?? "")))
+  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app, usesAuth }
+  if (opts.app) files[APP_CONFIG_PATH] = `export const app = ${JSON.stringify(opts.app)}\n`
+  files[SERVER_ENTRY_PATH] = serverEntrySource(modules, manifest)
+  const { code } = await bundleProjectWithMap(
+    SERVER_ENTRY_PATH, files, "esm", opts.minify ?? false, false, undefined, opts.sourcemap ?? false, SERVER_INJECT,
+  )
+  return { code, manifest }
+}

package/src/compile/serverTypes.ts

@@ -0,0 +1,227 @@
+/**
+ * Endpoint parameter schemas from TypeScript types (docs/backend-plan.md §2.3 / §4.3).
+ *
+ * Endpoints are plain functions; their argument types are ordinary TS annotations. The client is not
+ * trusted, so the server validates every call — and rather than making developers write a schema
+ * twice, this pass runs the TypeScript checker over the project's `*.server.ts` files (in memory) and
+ * lowers each exported function's parameter types to the compact JSON schema `src/server/validate.ts`
+ * interprets at runtime. The result is embedded in the server bundle's manifest.
+ *
+ * Supported: primitives, literals, unions, enums, arrays, tuples, object types / interfaces / type
+ * aliases (from any project file), optional properties, index signatures (`Record<string, T>`),
+ * optional / defaulted / rest parameters, `any`/`unknown` (= accept anything). Rejected with a
+ * compile error: functions, classes with methods, `Date`, `Map`/`Set`, symbols, recursive types —
+ * "endpoint args must be JSON-serializable". Return types are not validated.
+ *
+ * `typescript` is loaded lazily (it's a devDependency of the SDK and a dependency of the platform
+ * compile step); the browser-safe parts of the compiler never import this module's runtime.
+ */
+
+import type { CompileEntry } from "./compileProject"
+import type { ParamSchema, Schema } from "../server/validate"
+import { serverModuleId, type ServerExport } from "./serverSplit"
+
+type TS = typeof import("typescript")
+
+const normalizePath = (path: string) => {
+  const parts: string[] = []
+  for (const part of path.split("\\").join("/").split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+export class EndpointTypeError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`endpoint args must be JSON-serializable:\n  ${problems.join("\n  ")}`)
+    this.name = "EndpointTypeError"
+    this.problems = problems
+  }
+}
+
+export type DeriveResult = {
+  /** endpoint id → parameter schemas (only endpoints the checker could see). */
+  params: Record<string, ParamSchema[]>
+  warnings: string[]
+}
+
+/**
+ * Derive `{ "<module>#<fn>": ParamSchema[] }` for every function export of every `*.server.ts` entry.
+ * Throws `EndpointTypeError` when a parameter type can't be validated at runtime.
+ */
+export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>): Promise<DeriveResult> => {
+  let ts: TS
+  try {
+    ts = (await import("typescript")).default ?? (await import("typescript")) as unknown as TS
+  } catch {
+    throw new Error("serverTypes: the `typescript` package is required to compile server endpoints")
+  }
+
+  const files = new Map<string, string>()
+  for (const e of entries) {
+    if (e.type !== "text" || typeof e.text !== "string") continue
+    if (!/\.[tj]sx?$/.test(e.path)) continue
+    files.set(normalizePath(e.path), e.text)
+  }
+  const roots = Object.keys(modules).map(normalizePath).filter(p => files.has(p))
+
+  const options: import("typescript").CompilerOptions = {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    allowImportingTsExtensions: true,
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+    types: [],
+    lib: ["lib.es2022.d.ts"],
+  }
+  const defaultLibPath = ts.getDefaultLibFilePath(options).split("\\").join("/")
+  const defaultLibDir = defaultLibPath.slice(0, defaultLibPath.lastIndexOf("/"))
+  const sys = ts.sys
+  const host: import("typescript").CompilerHost = {
+    fileExists: p => files.has(normalizePath(p)) || (p.split("\\").join("/").startsWith(defaultLibDir) && sys.fileExists(p)),
+    readFile: p => files.get(normalizePath(p)) ?? (p.split("\\").join("/").startsWith(defaultLibDir) ? sys.readFile(p) : undefined),
+    getSourceFile: (p, lang) => {
+      const text = files.get(normalizePath(p)) ?? (p.split("\\").join("/").startsWith(defaultLibDir) ? sys.readFile(p) : undefined)
+      return text === undefined ? undefined : ts.createSourceFile(p, text, lang, true)
+    },
+    getDefaultLibFileName: o => ts.getDefaultLibFilePath(o),
+    writeFile: () => {},
+    getCurrentDirectory: () => "/",
+    getCanonicalFileName: p => p,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => "\n",
+    directoryExists: () => true,
+    getDirectories: () => [],
+  }
+  const program = ts.createProgram(roots, options, host)
+  const checker = program.getTypeChecker()
+
+  const params: Record<string, ParamSchema[]> = {}
+  const warnings: string[] = []
+  const problems: string[] = []
+
+  for (const [path, exports] of Object.entries(modules)) {
+    const sf = program.getSourceFile(normalizePath(path))
+    if (!sf) { warnings.push(`${path}: not in the TS program`); continue }
+    const modSym = checker.getSymbolAtLocation(sf)
+    if (!modSym) continue
+    const exported = new Map(checker.getExportsOfModule(modSym).map(s => [s.name, s]))
+    for (const ex of exports) {
+      if (ex.kind !== "fn") continue
+      const id = `${serverModuleId(path)}#${ex.name}`
+      let sym = exported.get(ex.name)
+      if (!sym) { warnings.push(`${id}: export not found by the checker — unvalidated`); continue }
+      if (sym.flags & ts.SymbolFlags.Alias) sym = checker.getAliasedSymbol(sym)
+      const decl = sym.valueDeclaration ?? sym.declarations?.[0]
+      if (!decl) { warnings.push(`${id}: no declaration — unvalidated`); continue }
+      const type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      const sig = type.getCallSignatures()[0]
+      if (!sig) { warnings.push(`${id}: not callable — unvalidated`); continue }
+      const list: ParamSchema[] = []
+      for (const p of sig.getParameters()) {
+        const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
+        const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
+        const rest = !!pd?.dotDotDotToken
+        const optional = !!pd?.questionToken || !!pd?.initializer || rest
+        try {
+          // `x?: T` carries `undefined` in its type — the optional flag covers it, strip it from the schema
+          const members = ptype.flags & ts.TypeFlags.Union ? (ptype as import("typescript").UnionType).types : [ptype]
+          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${id}(${p.name})`, new Set())
+          list.push({ name: p.name, schema, optional, rest })
+        } catch (e) {
+          problems.push((e as Error).message)
+        }
+      }
+      params[id] = list
+    }
+  }
+  if (problems.length) throw new EndpointTypeError(problems)
+  return { params, warnings }
+}
+
+// ───────────────────────────── type → schema ─────────────────────────────
+
+const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("typescript").Type, where: string, stack: Set<import("typescript").Type>): Schema => {
+  const f = type.flags
+  const T = ts.TypeFlags
+  if (f & (T.Any | T.Unknown)) return { t: "any" }
+  if (f & T.Never) throw new Error(`${where}: never`)
+  if (f & T.Null) return { t: "null" }
+  if (f & (T.Undefined | T.Void)) return { t: "undefined" }
+  if (f & T.BooleanLiteral) return { t: "lit", v: (type as any).intrinsicName === "true" }
+  if (f & T.Boolean) return { t: "boolean" }
+  if (f & T.StringLiteral) return { t: "lit", v: (type as import("typescript").StringLiteralType).value }
+  if (f & T.NumberLiteral) return { t: "lit", v: (type as import("typescript").NumberLiteralType).value }
+  if (f & T.String) return { t: "string" }
+  if (f & T.Number) return { t: "number" }
+  if (f & (T.BigInt | T.BigIntLiteral | T.ESSymbol | T.UniqueESSymbol)) throw new Error(`${where}: ${checker.typeToString(type)} is not JSON`)
+  if (f & T.EnumLiteral && f & T.Union) {
+    return { t: "union", of: (type as import("typescript").UnionType).types.map(t => lower(ts, checker, t, where, stack)) }
+  }
+  if (f & T.Union) return lowerMembers(ts, checker, (type as import("typescript").UnionType).types, where, stack)
+  if (f & T.Intersection || f & T.Object) {
+    if (stack.has(type)) throw new Error(`${where}: recursive type ${checker.typeToString(type)}`)
+    if (type.getCallSignatures().length || type.getConstructSignatures().length) throw new Error(`${where}: functions are not JSON`)
+    stack.add(type)
+    try {
+      if (checker.isArrayType(type)) {
+        const [el] = checker.getTypeArguments(type as import("typescript").TypeReference)
+        return { t: "array", of: el ? lower(ts, checker, el, where, stack) : { t: "any" } }
+      }
+      if (checker.isTupleType(type)) {
+        const ref = type as import("typescript").TypeReference
+        const target = ref.target as import("typescript").TupleType
+        const args = checker.getTypeArguments(ref)
+        const items: Schema[] = []
+        let rest: Schema | undefined
+        target.elementFlags.forEach((flag, i) => {
+          const s = lower(ts, checker, args[i], where, stack)
+          if (flag & ts.ElementFlags.Rest || flag & ts.ElementFlags.Variadic) rest = (s.t === "array" ? s.of : s)
+          else items.push(flag & ts.ElementFlags.Optional ? { t: "union", of: [s, { t: "undefined" }] } : s)
+        })
+        return { t: "tuple", items, rest }
+      }
+      const name = checker.typeToString(type)
+      if (/^(Date|Map<|Set<|WeakMap<|WeakSet<|Promise<|RegExp$|ArrayBuffer$|Uint8Array$)/.test(name)) throw new Error(`${where}: ${name} is not JSON`)
+      const props: Record<string, Schema> = {}
+      const optional: string[] = []
+      for (const p of checker.getPropertiesOfType(type)) {
+        const pt = checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration ?? p.declarations?.[0]!)
+        if (pt.getCallSignatures().length) throw new Error(`${where}.${p.name}: functions are not JSON`)
+        const isOpt = !!(p.flags & ts.SymbolFlags.Optional)
+        // an optional property's type carries `undefined` — strip it, the optional list covers it
+        const members = pt.flags & T.Union ? (pt as import("typescript").UnionType).types : [pt]
+        props[p.name] = lowerMembers(ts, checker, isOpt ? members.filter(t => !(t.flags & T.Undefined)) : members, `${where}.${p.name}`, stack)
+        if (isOpt) optional.push(p.name)
+      }
+      let index: Schema | undefined
+      for (const info of checker.getIndexInfosOfType(type)) {
+        if (info.keyType.flags & T.String) index = lower(ts, checker, info.type, `${where}[string]`, stack)
+      }
+      return { t: "object", props, ...(optional.length ? { optional } : {}), ...(index ? { index } : {}) }
+    } finally {
+      stack.delete(type)
+    }
+  }
+  if (f & T.TypeParameter) throw new Error(`${where}: generic parameter ${checker.typeToString(type)} can't be validated`)
+  throw new Error(`${where}: unsupported type ${checker.typeToString(type)}`)
+}
+
+/** Lower a list of union members: `boolean` arrives as `true | false` — fold it back; a single member is itself. */
+const lowerMembers = (ts: TS, checker: import("typescript").TypeChecker, members: readonly import("typescript").Type[], where: string, stack: Set<import("typescript").Type>): Schema => {
+  const T = ts.TypeFlags
+  if (members.length === 1) return lower(ts, checker, members[0], where, stack)
+  const isLit = (m: import("typescript").Type, v: string) => !!(m.flags & T.BooleanLiteral) && (m as any).intrinsicName === v
+  const foldBool = members.some(m => isLit(m, "true")) && members.some(m => isLit(m, "false"))
+  const of: Schema[] = foldBool ? [{ t: "boolean" }] : []
+  for (const m of members) {
+    if (foldBool && m.flags & T.BooleanLiteral) continue
+    of.push(lower(ts, checker, m, where, stack))
+  }
+  return of.length === 1 ? of[0] : { t: "union", of }
+}

package/src/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
+}