@solidrt/cli 0.0.49 → 0.0.50

package/AGENTS.md

@@ -24,7 +24,11 @@ bundled `flux` runtime, not on Bun. Invoke via `bunx srt <command>`.
   separately (server distributes code; clients on other devices connect to it).
 - `bunx srt run src/index.tsx --capture out.script.json` - records keydown/keyup
   from every connected client into one script file (written on client
-  disconnect), for replaying later with `render --script`.
+  disconnect), for replaying later with `render --script`. The file is JSON
+  Lines and hand-authorable - the exact shape (`after` ms, `type`, `key`,
+  `device`) is in `docs/cli.md` under `--capture`. For probing app state
+  without a display, `-- <args...>` reaches the app as `flux:process` argv
+  (also `docs/cli.md`), which is often simpler than scripting input.
 
 ## Verifying without a display (headless / CI / agent box)
 
@@ -35,7 +39,8 @@ Two reliable checks that need no GUI:
    renders offscreen via EGL and writes `frame-NNNNNN.png`. This actually
    proves the app renders. Combine with `--fps`/`--duration` (defaults
    1280x720, 60fps, 1s). No display needed: rendering uses SDL's offscreen
-   driver (falling back to a hidden window where EGL cannot go headless).
+   driver, or alloy's own EGL pbuffer where that driver cannot go headless
+   (see the ANGLE gotcha below).
 
 Also headless: the bundled flux runtime runs a plain `.js` file directly -
 `node_modules/@solidrt/<platform>/flux script.js` (e.g.
@@ -49,6 +54,14 @@ behavior in isolation.
 - `--size` is physical output pixels: layout runs at exactly that size
   (display scale is pinned to 1), so frames are identical on every machine.
 - Run from the project directory. There is no `bunx --cwd` flag.
+- On ANGLE stacks (Windows, macOS) SDL's offscreen driver cannot go
+  headless (no EGL device enumeration), so `render` there builds its own
+  EGL pbuffer context behind SDL's dummy video driver instead; the log says
+  "using a headless EGL context". If that also fails it renders into a
+  hidden window, which needs an interactive desktop session (fails under a
+  service, in Session 0, or over SSH-only). Verified headless on Linux
+  (Wayland) and the pbuffer path on Windows from a desktop session; a
+  non-interactive Windows session and macOS are unverified.
 
 ## Sessions (parallel dev servers on one machine)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -19,6 +19,7 @@
     "@babel/core": "^7.0.0",
     "@babel/plugin-syntax-jsx": "^7.0.0",
     "@babel/preset-typescript": "^7.0.0",
+    "@clack/prompts": "^1.7.0",
     "@jridgewell/remapping": "^2.3.0",
     "@jridgewell/trace-mapping": "^0.3.25",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -28,16 +29,16 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.49",
-    "@solidrt/linux-arm64-gnu": "0.0.49",
-    "@solidrt/linux-x64-gnu": "0.0.49",
-    "@solidrt/win32-x64-msvc": "0.0.49"
+    "@solidrt/darwin-arm64": "0.0.50",
+    "@solidrt/linux-arm64-gnu": "0.0.50",
+    "@solidrt/linux-x64-gnu": "0.0.50",
+    "@solidrt/win32-x64-msvc": "0.0.50"
   },
   "peerDependencies": {
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.49",
+    "@solidrt/flux-types": "0.0.50",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest"
   }

package/scaffold/AGENTS.md

@@ -280,6 +280,12 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    snapshot instead of re-rasterizing. A window shader's output is invisible
    to get_snapshot and every other MCP tool; `srt render` is the only way to
    see it (Run / verify below).
+7. `flux:wasm` is not the fast lane. It runs a pure interpreter (wasmi, no
+   JIT), so tight typed compute gains a small constant factor over the same
+   loop in JavaScript, nowhere near browser wasm speed, and every host call
+   costs marshalling. Use it to ship one compiled module across every target
+   without native binaries, not to speed up per-frame work; for that, rules
+   1-2 (move it to the GPU, cut property writes) are the leverage.
 
 ### Isolates: heavy work off the JS thread
 
@@ -432,7 +438,7 @@ its tools over guessing at runtime state:
   re-fetch ids and restart cursors
 - get_stats: fps, CPU/memory, frame phase timings, setProperty rate, plus
   layout-activity counters for the last rebuild (nodes, measureCalls,
-  paraShapes, dirtiedNodes, cacheGets/cacheHits) - when layoutMs looks
+  paraShapes/wordHits, dirtiedNodes, cacheGets/cacheHits) - when layoutMs looks
   wrong, these say whether the cost is text shaping, invalidation breadth,
   or a defeated layout cache (healthy incremental rebuilds show a near-100%
   cacheHits rate). reusedPerSec/skippedPerSec are the demand gate's visible

package/scaffold/package.json

@@ -10,12 +10,13 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.49",
-    "@solidrt/components": "0.0.49"
+    "@solidrt/core": "0.0.50",
+    "@solidrt/components": "0.0.50",
+    "@solidrt/3d": "0.0.50"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.49",
-    "@solidrt/flux-types": "0.0.49",
+    "@solidrt/cli": "0.0.50",
+    "@solidrt/flux-types": "0.0.50",
     "typescript": "^7"
   }
 }

package/src/args.ts

@@ -35,7 +35,7 @@ export let { values, positionals } = parseArgs({
     port: { type: "string" },
     android: { type: "boolean", default: false },
     device: { type: "string" },
-    template: { type: "string", short: "t" },
+    with: { type: "string" },
   },
   allowPositionals: true,
 })
@@ -159,7 +159,7 @@ Commands:
   mcp                    MCP server (stdio) exposing the running dev server to coding agents
 
 init options:
-  -t, --template <name>  Start from a named template (skips the interactive picker)
+      --with <pkg,pkg>   Extensions to include, e.g. @solidrt/components,@solidrt/3d (skips the picker)
 
 run/server options:
   -s, --session <N>      Session number: dev server on port 34884+N, client slot N (default: 0)

package/src/commands/init.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
 import { source, values } from "../args"
-import { select, text } from "../prompt"
+import { multiselect, note, text } from "../prompt"
 
 const DEFAULT_NAME = "solidrt-app"
 
@@ -29,76 +29,57 @@ function packageName(dir: string): string {
 }
 
 const DEFAULT_TEMPLATE = "default"
-const TEMPLATE_MANIFEST = "template.json"
-
-// Each template's template.json declares which level the scaffolded app is
-// written at: "core" (only @solidrt/core, no component framework) or
-// "components" (built with @solidrt/components). The level decides the
-// generated dependencies; the description labels the template in the picker.
-interface TemplateInfo {
-  name: string
-  level: "core" | "components"
+
+// Optional packages an app can opt into on top of core. Each maps to a
+// dependency in the scaffold package.json (kept when selected, removed
+// otherwise) and optionally to a starter under scaffold/templates/.
+interface Extension {
+  pkg: string
+  template?: string
   description: string
 }
 
-// Templates are the directories under scaffold/templates/; each holds the files
-// that become the new project's src/, plus a template.json manifest. `default`
-// sorts first as the starting point, the rest alphabetically.
-async function listTemplates(): Promise<TemplateInfo[]> {
-  let entries = await readdir(TEMPLATES_DIR, { withFileTypes: true })
-  let names = entries
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .sort((a, b) =>
-      a === DEFAULT_TEMPLATE ? -1 : b === DEFAULT_TEMPLATE ? 1 : a.localeCompare(b),
-    )
-  let templates: TemplateInfo[] = []
-  for (let name of names) {
-    // A missing manifest falls back to the components level: it keeps every
-    // dependency, so the scaffolded app works at either level.
-    let manifest = await readFile(join(TEMPLATES_DIR, name, TEMPLATE_MANIFEST), "utf8")
-      .then((raw) => JSON.parse(raw))
-      .catch(() => ({}))
-    templates.push({
-      name,
-      level: manifest.level === "core" ? "core" : "components",
-      description: typeof manifest.description === "string" ? manifest.description : "",
-    })
-  }
-  return templates
-}
+const EXTENSIONS: Extension[] = [
+  {
+    pkg: "@solidrt/components",
+    template: "components",
+    description: "component framework: widgets, theming, navigation",
+  },
+  { pkg: "@solidrt/3d", description: "general purpose 3D library" },
+]
 
-// Resolve which template to scaffold from: an explicit --template if valid, an
-// interactive picker on a TTY, else `default` (or the first available).
-async function resolveTemplate(): Promise<TemplateInfo> {
-  let templates = await listTemplates()
-  if (templates.length === 0) {
-    console.error(`!! No templates found in ${TEMPLATES_DIR}`)
-    process.exit(1)
-  }
-  let chosen = values.template
-  if (chosen) {
-    let found = templates.find((t) => t.name === chosen)
-    if (!found) {
-      let names = templates.map((t) => t.name).join(", ")
-      console.error(`!! Unknown template "${chosen}"; choose from: ${names}`)
-      process.exit(1)
+// Resolve which extensions the app takes: an explicit --with list if valid,
+// an interactive picker on a TTY, else none (core only).
+async function resolveExtensions(): Promise<Extension[]> {
+  let raw = values.with
+  if (raw !== undefined) {
+    let names = raw.split(",").map((n) => n.trim()).filter(Boolean)
+    let chosen: Extension[] = []
+    for (let name of names) {
+      let found = EXTENSIONS.find((e) => e.pkg === name)
+      if (!found) {
+        let all = EXTENSIONS.map((e) => e.pkg).join(", ")
+        console.error(`!! Unknown extension "${name}"; choose from: ${all}`)
+        process.exit(1)
+      }
+      if (!chosen.includes(found)) chosen.push(found)
     }
-    return found
-  }
-  if (process.stdin.isTTY) {
-    let picked = await select(
-      "Select a template",
-      templates.map((t) => {
-        // Core is the runtime every app has; anything else is a package the
-        // app opts into, so the picker marks it as such.
-        let name = t.level === "core" ? t.name : `${t.name} (extension)`
-        return { label: t.description ? `${name} - ${t.description}` : name, value: t.name }
-      }),
-    )
-    return templates.find((t) => t.name === picked)!
+    return chosen
   }
-  return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
+  if (!process.stdin.isTTY) return []
+  // Core is the runtime every app has, so it is not a choice.
+  note("@solidrt/core is always included", "Packages")
+  let picked = await multiselect(
+    "Select extensions",
+    EXTENSIONS.map((e) => ({ label: `${e.pkg} - ${e.description}`, value: e.pkg })),
+  )
+  return EXTENSIONS.filter((e) => picked.includes(e.pkg))
+}
+
+// The starter src/ comes from the first selected extension that brings a
+// template; with none, the core `default` starter.
+function resolveTemplate(extensions: Extension[]): string {
+  return extensions.find((e) => e.template)?.template ?? DEFAULT_TEMPLATE
 }
 
 export async function runInitCommand() {
@@ -120,9 +101,11 @@ export async function runInitCommand() {
     process.exit(1)
   }
 
-  let template = await resolveTemplate()
+  let extensions = await resolveExtensions()
+  let template = resolveTemplate(extensions)
+  let summary = ["@solidrt/core", ...extensions.map((e) => e.pkg)].join(", ")
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template.name})`)
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${summary})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
@@ -130,13 +113,11 @@ export async function runInitCommand() {
     console.log(`   Write ${to}`)
   }
 
-  // The chosen template's files become the project's src/. Entries may be
-  // nested directories (e.g. an asset folder), so copy recursively. The
-  // manifest describes the template rather than belonging to the app.
-  let templateDir = join(TEMPLATES_DIR, template.name)
+  // The template's files become the project's src/. Entries may be nested
+  // directories (e.g. an asset folder), so copy recursively.
+  let templateDir = join(TEMPLATES_DIR, template)
   await mkdir(join(dir, "src"), { recursive: true })
   for (let file of await readdir(templateDir)) {
-    if (file === TEMPLATE_MANIFEST) continue
     await cp(join(templateDir, file), join(dir, "src", file), { recursive: true })
     console.log(`   Write src/${file}`)
   }
@@ -149,12 +130,15 @@ export async function runInitCommand() {
   await writeFile(join(dir, "assets", "icon.svg"), await readFile(join(SCAFFOLD_DIR, "icon.svg")))
   console.log("   Write assets/icon.svg")
 
-  // The scaffold package.json carries a placeholder name; set it from the
-  // target folder. A core-level app gets no component framework dependency.
+  // The scaffold package.json carries a placeholder name and every extension
+  // dependency; set the name from the target folder and keep only the
+  // selected extensions.
   let pkgPath = join(dir, "package.json")
   let pkg = JSON.parse(await readFile(pkgPath, "utf8"))
   pkg.name = packageName(dir)
-  if (template.level === "core") delete pkg.dependencies["@solidrt/components"]
+  for (let ext of EXTENSIONS) {
+    if (!extensions.includes(ext)) delete pkg.dependencies[ext.pkg]
+  }
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
 
   // Deps are declared in scaffold/package.json (Solid peers resolve via

package/src/commands/mcp.ts

@@ -10,8 +10,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
 import { dirname, join, resolve } from "node:path"
-import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { values } from "../args"
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs"
+import { values, DEFAULT_DEV_PORT } from "../args"
 import { DEV_PORT } from "../dev-server"
 import { devDir } from "../dev-dir"
 
@@ -35,12 +35,30 @@ function findProjectDir(): string | null {
   }
 }
 
+// The two sides of a projectDir comparison come from different processes
+// (the server's entry path, the bridge's cwd) and only agree by construction
+// on the directory, not the spelling: an editor-spawned bridge on Windows
+// keeps its parent's lower-case drive letter while a shell writes it upper
+// case, and 8.3 names, symlinks and subst drives are the same class. Compare
+// the canonical path, so the spelling never decides.
+function sameDir(a: string, b: string): boolean {
+  if (a === b) return true
+  try {
+    return realpathSync.native(a) === realpathSync.native(b)
+  } catch {
+    return false
+  }
+}
+
+// Only ESRCH means the process is gone. EPERM is a live process this bridge
+// may not signal (Windows reports it for other users' processes), and a
+// bare try/catch would drop that healthy server from the registry.
 function pidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0)
     return true
-  } catch {
-    return false
+  } catch (e: any) {
+    return e?.code === "EPERM"
   }
 }
 
@@ -80,7 +98,8 @@ async function resolvePort(): Promise<PortResult> {
       message: `No package.json found above ${process.cwd()}, so no dev server can be resolved by project. Pass -s <N> or --port <N> to srt mcp.`,
     }
   }
-  let matches = liveRecords().filter((r) => r.projectDir === project && pidAlive(r.pid))
+  let records = liveRecords()
+  let matches = records.filter((r) => sameDir(r.projectDir, project) && pidAlive(r.pid))
   if (matches.length > 1) {
     let ports = matches
       .map((r) => r.port)
@@ -89,7 +108,25 @@ async function resolvePort(): Promise<PortResult> {
     return { ok: false, message: `${matches.length} dev servers are serving this project (ports ${ports}); pass -s <N> to srt mcp` }
   }
   if (matches.length === 0) {
-    return { ok: false, message: `No dev server for ${project}. Start one with srt run, or pass -s <N> to srt mcp.` }
+    // A lookup by key that fails against a small table prints the table: an
+    // empty registry, a dead pid and a record for another project are three
+    // different problems, and the reader can only tell them apart if the
+    // candidates are listed next to the key that was looked up.
+    let listing =
+      records.length === 0
+        ? `Registry ${devDir("servers")}: no records.`
+        : `Registry ${devDir("servers")}: ${records.length} record(s).\n` +
+          records
+            .map((r) => {
+              let session = r.port - DEFAULT_DEV_PORT
+              let flag = session >= 0 && session < 100 ? `-s ${session}` : `--port ${r.port}`
+              return `  port ${r.port} (${flag})  pid ${r.pid} (${pidAlive(r.pid) ? "alive" : "dead"})  serving ${r.projectDir}`
+            })
+            .join("\n")
+    return {
+      ok: false,
+      message: `No dev server for ${project}.\n${listing}\nStart one with srt run, or pin one of the servers above by passing its flag to srt mcp.`,
+    }
   }
   let port = matches[0]!.port
   // The record is a hint; the server is authoritative. The probe catches a
@@ -97,7 +134,7 @@ async function resolvePort(): Promise<PortResult> {
   try {
     let probe = await fetch(`http://127.0.0.1:${port}/__control__/clients`)
     let body: any = await probe.json().catch(() => null)
-    if (!probe.ok || body?.projectDir !== project) {
+    if (!probe.ok || typeof body?.projectDir !== "string" || !sameDir(body.projectDir, project)) {
       return {
         ok: false,
         message: `The server on port ${port} is not serving ${project}${
@@ -206,7 +243,7 @@ let TOOLS: {
     name: "get_stats",
     readOnly: true,
     description:
-      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassMs (cumulative shader/pipeline target renders on the raster thread and the wall time they took in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; the ms figure is raster-thread occupancy issuing the passes, not GPU-side duration), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
+      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped, i.e. words the shared word cache did not have; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), wordHits (words answered from the shared word cache; hits high and paraShapes near zero on a text change means only the changed words were reshaped), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassMs (cumulative shader/pipeline target renders on the raster thread and the wall time they took in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; the ms figure is raster-thread occupancy issuing the passes, not GPU-side duration), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
     inputSchema: { client: CLIENT_ARG },
   },
   {

package/src/prompt.ts

@@ -1,18 +1,21 @@
-import { createInterface, emitKeypressEvents } from "node:readline"
+import * as clack from "@clack/prompts"
+
+// Thin wrappers over @clack/prompts. Every prompt guards on a TTY: a non-TTY
+// stdin resolves the default rather than blocking on input that will never
+// arrive. Cancelling (ctrl-c) exits the process.
+
+function unwrap<T>(value: T | symbol): T {
+  if (clack.isCancel(value)) {
+    clack.cancel("Cancelled")
+    process.exit(130)
+  }
+  return value as T
+}
 
-// Single-line text prompt with an optional default (shown in parentheses, used
-// when the answer is blank). Non-TTY stdin resolves the default rather than
-// blocking on input that will never arrive.
-export function text(message: string, def = ""): Promise<string> {
-  return new Promise<string>((resolve) => {
-    if (!process.stdin.isTTY) return resolve(def)
-    let rl = createInterface({ input: process.stdin, output: process.stdout })
-    let suffix = def ? ` (${def})` : ""
-    rl.question(`? ${message}${suffix}: `, (answer) => {
-      rl.close()
-      resolve(answer.trim() || def)
-    })
-  })
+// Single-line text prompt; a blank answer resolves the default.
+export async function text(message: string, def = ""): Promise<string> {
+  if (!process.stdin.isTTY) return def
+  return unwrap(await clack.text({ message, defaultValue: def, placeholder: def }))
 }
 
 export interface SelectOption {
@@ -20,65 +23,36 @@ export interface SelectOption {
   value: string
 }
 
-// Minimal arrow-key single-select prompt, built on node:readline (same
-// dependency-free approach as repl.ts). Renders the option list, moves the
-// highlight on up/down, resolves the chosen value on enter. Options are plain
-// strings or { label, value } pairs when the display text differs from the
-// resolved value. Callers guard on process.stdin.isTTY; a non-TTY stdin here
-// resolves the first option rather than hanging on input that will never
-// arrive.
-export function select(message: string, options: Array<string | SelectOption>): Promise<string> {
+// Arrow-key single-select; non-TTY resolves the first option.
+export async function select(message: string, options: Array<string | SelectOption>): Promise<string> {
   let items = options.map((o) => (typeof o === "string" ? { label: o, value: o } : o))
-  return new Promise((resolve) => {
-    let input = process.stdin
-    let output = process.stdout
-    if (!input.isTTY) return resolve(items[0]!.value)
-
-    let selected = 0
-    emitKeypressEvents(input)
-    let wasRaw = input.isRaw
-    input.setRawMode(true)
-
-    let render = (first = false) => {
-      // After the first paint the cursor sits below the block; move it back up
-      // to the message line so the list redraws in place.
-      if (!first) output.write(`\x1b[${items.length + 1}A`)
-      output.write(`\x1b[K? ${message}\n`)
-      for (let i = 0; i < items.length; i++) {
-        let active = i === selected
-        let pointer = active ? "\x1b[36m> " : "  "
-        let reset = active ? "\x1b[0m" : ""
-        output.write(`\x1b[K${pointer}${items[i]!.label}${reset}\n`)
-      }
-    }
-
-    let cleanup = () => {
-      input.off("keypress", onKey)
-      input.setRawMode(wasRaw)
-      input.pause()
-    }
+  if (!process.stdin.isTTY) return items[0]!.value
+  return unwrap(await clack.select({ message, options: items }))
+}
 
-    let onKey = (_str: string, key: { name: string; ctrl: boolean } | undefined) => {
-      if (!key) return
-      if (key.name === "up") {
-        selected = (selected - 1 + items.length) % items.length
-        render()
-      } else if (key.name === "down") {
-        selected = (selected + 1) % items.length
-        render()
-      } else if (key.name === "return" || key.name === "enter") {
-        cleanup()
-        output.write("\n")
-        resolve(items[selected]!.value)
-      } else if (key.ctrl && (key.name === "c" || key.name === "d")) {
-        cleanup()
-        output.write("\n")
-        process.exit(130)
-      }
-    }
+export interface MultiSelectOption {
+  label: string
+  value: string
+  checked?: boolean
+}
 
-    input.on("keypress", onKey)
-    input.resume()
-    render(true)
-  })
+// Space toggles, enter confirms; resolves the selected values in option
+// order. Non-TTY resolves the preselected values.
+export async function multiselect(message: string, options: MultiSelectOption[]): Promise<string[]> {
+  let preset = options.filter((o) => o.checked).map((o) => o.value)
+  if (!process.stdin.isTTY) return preset
+  let picked = unwrap(
+    await clack.multiselect({
+      message,
+      options: options.map((o) => ({ label: o.label, value: o.value })),
+      initialValues: preset,
+      required: false,
+    }),
+  )
+  return options.filter((o) => picked.includes(o.value)).map((o) => o.value)
 }
+
+// Boxed informational message; silent on a non-TTY.
+export function note(message: string, title?: string) {
+  if (process.stdin.isTTY) clack.note(message, title)
+}

package/scaffold/templates/components/template.json

@@ -1,4 +0,0 @@
-{
-  "level": "components",
-  "description": "components starter application"
-}

package/scaffold/templates/default/template.json

@@ -1,4 +0,0 @@
-{
-  "level": "core",
-  "description": "core starter application"
-}