@solidrt/cli 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -22,12 +22,12 @@
     "qrcode-generator": "^2.0.4"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.20",
-    "@solidrt/linux-x64-gnu": "0.0.20",
-    "@solidrt/win32-x64-msvc": "0.0.20"
+    "@solidrt/darwin-arm64": "0.0.22",
+    "@solidrt/linux-x64-gnu": "0.0.22",
+    "@solidrt/win32-x64-msvc": "0.0.22"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.20",
+    "@solidrt/core": "0.0.22",
     "typescript": "^6"
   },
   "devDependencies": {

package/scaffold/AGENTS.md

@@ -8,6 +8,7 @@ Authoritative references ship inside the installed packages - read them:
 - node_modules/solid-js/CHEATSHEET.md          - SolidJS 2.0 reactivity/control-flow model
 - node_modules/@solidrt/components/AGENTS.md   - the component vocabulary; build UI from these
 - node_modules/@solidrt/components/README.md   - full prop tables for every component
+- node_modules/@solidrt/components/examples/   - single-concept usage patterns to copy (see its README.md index)
 - node_modules/@solidrt/core/AGENTS.md         - the underlying element/prop/reactivity model
 - node_modules/@solidrt/core/examples/         - single-concept usage patterns to copy (see its README.md index)
 - node_modules/@solidrt/cli/AGENTS.md          - running, bundling, headless verify
@@ -68,6 +69,13 @@ Authoritative references ship inside the installed packages - read them:
     em-dashes (use a hyphen), no smart/curly quotes, no unicode symbols.
 11. Prefer let over const. Use const only for real constants - a single fixed
     string or number value - and name those in ALL_CAPS.
+12. Reading a signal/prop/store at the top level of a component body (not
+    inside JSX, a `createMemo`, or an effect's compute phase) reads it
+    untracked - it silently freezes at the initial value instead of updating
+    on change. `createEffect` takes two arguments now: `(compute, apply)`.
+    `compute` is the tracked read phase; `apply(value, prev)` runs untracked
+    and is where side effects/DOM-equivalent writes belong. The old
+    single-arg `createEffect(fn)` form is gone - using it is an error.
 
 ## Run / verify
 

package/scaffold/package.json

@@ -9,12 +9,12 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.20",
-    "@solidrt/components": "0.0.20"
+    "@solidrt/core": "0.0.22",
+    "@solidrt/components": "0.0.22"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.20",
-    "@solidrt/flux-types": "0.0.20",
+    "@solidrt/cli": "0.0.22",
+    "@solidrt/flux-types": "0.0.22",
     "typescript": "^6"
   }
 }

package/scaffold/templates/gallery/index.tsx

@@ -0,0 +1,485 @@
+import {
+  render,
+  createSignal,
+  createEffect,
+  untrack,
+  env,
+  capabilities,
+} from "@solidrt/core"
+import {
+  policy,
+  setPolicy,
+  type DensityPolicy,
+  type MotionPolicy,
+  Window,
+  View,
+  Text,
+  Image,
+  Button,
+  TextInput,
+  Switch,
+  Checkbox,
+  RadioGroup,
+  Radio,
+  Slider,
+  QrCode,
+  Card,
+  Divider,
+  Badge,
+  Spinner,
+  ProgressBar,
+  Tooltip,
+  Select,
+  ContextMenu,
+  Icon,
+  ScrollView,
+  theme,
+  space,
+  typeWeight,
+  setTheme,
+  darkTheme,
+  lightTheme,
+  SafeArea,
+} from "@solidrt/components"
+
+import icon from "./icon.png" with { type: "binary" }
+
+// A growing gallery of @solidrt/components. The whole thing recolors live when
+// the theme switches: every component reads theme.* reactively, so pressing
+// "Toggle theme" reflows the palette with no remount. The "Environment and
+// policies" card shows the environment -> capabilities -> policies cascade and
+// lets you force density/motion overrides to watch every control adapt.
+
+// Lucide icons are SVG documents (strings). In a real app you import them as
+// assets (`import House from "lucide-static/icons/house.svg"`) or from a string
+// export; we inline a few here so the example stays self-contained. Each strokes
+// with currentColor, so Icon recolors them from the theme.
+const LUCIDE = (body: string) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"` +
+  ` stroke="currentColor" stroke-width="2" stroke-linecap="round"` +
+  ` stroke-linejoin="round">${body}</svg>`
+const HOUSE = LUCIDE(
+  `<path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8"/>` +
+    `<path d="M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>`,
+)
+const HEART = LUCIDE(
+  `<path d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"/>`,
+)
+const STAR = LUCIDE(
+  `<path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"/>`,
+)
+const SETTINGS = LUCIDE(
+  `<path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915"/>` +
+    `<circle cx="12" cy="12" r="3"/>`,
+)
+const BELL = LUCIDE(
+  `<path d="M10.268 21a2 2 0 0 0 3.464 0"/>` +
+    `<path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326"/>`,
+)
+
+function Row(props: { label: string; children?: any }) {
+  return (
+    <View
+      layout={{
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: space("lg"),
+      }}
+    >
+      <Text muted>{props.label}</Text>
+      {props.children}
+    </View>
+  )
+}
+
+function Value(props: { children?: any }) {
+  return <Text>{props.children}</Text>
+}
+
+// Joins the names whose flag is true, e.g. list(["mouse", env.mouseSeen], ...).
+function list(...entries: [string, boolean][]) {
+  let names = entries.filter(([, on]) => on).map(([name]) => name)
+  return names.length > 0 ? names.join(", ") : "none yet"
+}
+
+function App() {
+  let [dark, setDark] = createSignal(true)
+  let [name, setName] = createSignal("")
+  let [notify, setNotify] = createSignal(true)
+  let [agree, setAgree] = createSignal(false)
+  let [plan, setPlan] = createSignal<unknown>("pro")
+  let [volume, setVolume] = createSignal(40)
+  let [fruit, setFruit] = createSignal<unknown>(undefined)
+
+  // The QR code follows the name field debounced, not per keystroke: each data
+  // change regenerates the whole module grid, which is too heavy to run at
+  // typing frequency.
+  // untrack: seed with the current name once; the debounced effect below owns
+  // keeping it in sync, and a bare name() read here would warn (strict mode
+  // flags top-level reactive reads in component bodies as one-shot).
+  let [qrData, setQrData] = createSignal(untrack(name))
+  createEffect(
+    () => name(),
+    (v) => {
+      let timer = setTimeout(() => setQrData(v), 250)
+      return () => clearTimeout(timer)
+    },
+  )
+
+  // Follow the OS dark/light preference until the user toggles manually; the
+  // manual toggle then owns the choice for the rest of the session.
+  let userToggledTheme = false
+  let toggleTheme = () => {
+    userToggledTheme = true
+    let next = !dark()
+    setDark(next)
+    setTheme(next ? darkTheme : lightTheme)
+  }
+  createEffect(
+    () => env.systemTheme,
+    (t) => {
+      if (userToggledTheme || t === "unknown") return
+      let isDark = t === "dark"
+      setDark(isDark)
+      setTheme(isDark ? darkTheme : lightTheme)
+    },
+  )
+
+  // Policy override choices; "auto" hands the policy back to the resolver.
+  let [densityChoice, setDensityChoice] = createSignal<unknown>("auto")
+  let [motionChoice, setMotionChoice] = createSignal<unknown>("auto")
+  let chooseDensity = (v: unknown) => {
+    setDensityChoice(v)
+    setPolicy({ density: v === "auto" ? undefined : (v as DensityPolicy) })
+  }
+  let chooseMotion = (v: unknown) => {
+    setMotionChoice(v)
+    setPolicy({ motion: v === "auto" ? undefined : (v as MotionPolicy) })
+  }
+  let [textScaleChoice, setTextScaleChoice] = createSignal<unknown>("auto")
+  let chooseTextScale = (v: unknown) => {
+    setTextScaleChoice(v)
+    setPolicy({ textScale: v === "auto" ? undefined : (v as number) })
+  }
+  let [weightDeltaChoice, setWeightDeltaChoice] = createSignal<unknown>("auto")
+  let chooseWeightDelta = (v: unknown) => {
+    setWeightDeltaChoice(v)
+    setPolicy({ textWeightDelta: v === "auto" ? undefined : (v as number) })
+  }
+
+  return (
+    <Window
+      title="Components gallery"
+      layout={{ flexDirection: "column" }}
+      style={{ backgroundColor: theme.color.background }}
+    >
+      <SafeArea>
+        <ScrollView horizontal layout={{ flex: 1 }}>
+          <View
+            layout={{
+              height: "100%",
+              flexDirection: "column",
+              flexWrap: "wrap",
+              alignContent: "flex-start",
+              justifyContent: "flex-start",
+              gap: space("xl"),
+              padding: space("xl"),
+            }}
+          >
+            <Card title={dark() ? "Dark theme" : "Light theme"} layout={{ width: 360 }}>
+              <Text muted>Toggle to recolor every control below.</Text>
+              <Button onPress={toggleTheme}>Toggle theme</Button>
+            </Card>
+
+            <Card title="Environment" layout={{ width: 360 }}>
+              <Row label="Window">
+                <Value>
+                  {`${env.windowSize.width} x ${env.windowSize.height} @ ${env.displayScale}x`}
+                </Value>
+              </Row>
+              <Row label="System">
+                <Value>{`${env.systemTheme} theme, ${env.orientation}`}</Value>
+              </Row>
+              <Row label="Devices">
+                <Value>
+                  {env.inputDevices
+                    ? list(
+                        ["mouse", env.inputDevices.mouse],
+                        ["touch", env.inputDevices.touch],
+                        ["keyboard", env.inputDevices.keyboard],
+                      )
+                    : "not reported"}
+                </Value>
+              </Row>
+              <Row label="Inputs seen">
+                <Value>
+                  {list(
+                    ["mouse", env.mouseSeen],
+                    ["touch", env.touchSeen],
+                    ["keyboard", env.keyboardSeen],
+                  )}
+                </Value>
+              </Row>
+              <Row label="Capabilities">
+                <Value>
+                  {list(
+                    ["hover", capabilities.hover],
+                    ["touch", capabilities.touch],
+                    ["keyboard nav", capabilities.keyboardNav],
+                  )}
+                </Value>
+              </Row>
+              <Row label="Size class">
+                <Value>{capabilities.windowSizeClass}</Value>
+              </Row>
+            </Card>
+
+            <Card title="Policies" layout={{ width: 360 }}>
+              <Row label="Interaction policy">
+                <Value>{policy.interaction}</Value>
+              </Row>
+              <Row label="Focus ring">
+                <Value>{policy.focusRing ? "visible" : "hidden"}</Value>
+              </Row>
+              <Row label="App policies">
+                <Value>{`${policy.navigation}, ${policy.layout}`}</Value>
+              </Row>
+              <Divider />
+              <Row label="Density policy">
+                <Value>{policy.density}</Value>
+              </Row>
+              <RadioGroup
+                value={densityChoice()}
+                onChange={chooseDensity}
+                layout={{ flexDirection: "row", flexWrap: "wrap", gap: space("md") }}
+              >
+                <Radio value="auto">Auto</Radio>
+                <Radio value="comfortable">Comfortable</Radio>
+                <Radio value="compact">Compact</Radio>
+                <Radio value="dense">Dense</Radio>
+              </RadioGroup>
+              <Divider />
+              <Row label="Motion policy">
+                <Value>{policy.motion}</Value>
+              </Row>
+              <RadioGroup
+                value={motionChoice()}
+                onChange={chooseMotion}
+                layout={{ flexDirection: "row", flexWrap: "wrap", gap: space("md") }}
+              >
+                <Radio value="auto">Auto</Radio>
+                <Radio value="normal">Normal</Radio>
+                <Radio value="reduced">Reduced</Radio>
+                <Radio value="none">None</Radio>
+              </RadioGroup>
+              <Divider />
+              <Row label="Text scale">
+                <Value>{`${policy.textScale}x`}</Value>
+              </Row>
+              <RadioGroup
+                value={textScaleChoice()}
+                onChange={chooseTextScale}
+                layout={{ flexDirection: "row", flexWrap: "wrap", gap: space("md") }}
+              >
+                <Radio value="auto">Auto</Radio>
+                <Radio value={0.9}>0.9</Radio>
+                <Radio value={1.0}>1.0</Radio>
+                <Radio value={1.1}>1.1</Radio>
+              </RadioGroup>
+              <Divider />
+              <Row label="Text weight delta">
+                <Value>
+                  {`base +${policy.textWeightDelta}, body ${typeWeight(
+                    theme.text.body.weight,
+                    theme.text.body.size * policy.textScale,
+                  )}, title ${typeWeight(theme.text.title.weight, theme.text.title.size * policy.textScale)}`}
+                </Value>
+              </Row>
+              <RadioGroup
+                value={weightDeltaChoice()}
+                onChange={chooseWeightDelta}
+                layout={{ flexDirection: "row", flexWrap: "wrap", gap: space("md") }}
+              >
+                <Radio value="auto">Auto</Radio>
+                <Radio value={0}>0</Radio>
+                <Radio value={100}>+100</Radio>
+                <Radio value={200}>+200</Radio>
+              </RadioGroup>
+            </Card>
+
+            <Card title="Buttons" layout={{ width: 360 }}>
+              <View
+                layout={{
+                  flexDirection: "row",
+                  flexWrap: "wrap",
+                  gap: space("md"),
+                  alignItems: "center",
+                }}
+              >
+                <Button>Primary</Button>
+                <Button variant="secondary">Secondary</Button>
+                <Button variant="ghost">Ghost</Button>
+                <Button variant="danger">Danger</Button>
+                <Button disabled>Disabled</Button>
+              </View>
+            </Card>
+
+            <Card title="Text input" layout={{ width: 360 }}>
+              <TextInput
+                value={name()}
+                onInput={setName}
+                placeholder="Your name"
+                layout={{ width: 320 }}
+              />
+            </Card>
+
+            <Card title="Switch and checkbox" layout={{ width: 360 }}>
+              <Row label="Notifications">
+                <Switch value={notify()} onChange={setNotify} />
+              </Row>
+              <Row label="I agree to the terms">
+                <Checkbox checked={agree()} onChange={setAgree} />
+              </Row>
+            </Card>
+
+            <Card title="Radio group" layout={{ width: 360 }}>
+              <RadioGroup value={plan()} onChange={setPlan}>
+                <Radio value="free">Free</Radio>
+                <Radio value="pro">Pro</Radio>
+                <Radio value="team">Team</Radio>
+              </RadioGroup>
+            </Card>
+
+            <Card title="Context menu" layout={{ width: 360 }}>
+              <Text muted>
+                Right-click (mouse) or long-press (touch) the box below. Touch policy presents a
+                bottom sheet, desktop and hybrid a menu at the pointer.
+              </Text>
+              <ContextMenu
+                items={[
+                  { label: "Copy", onSelect: () => console.log("copy") },
+                  { label: "Paste", onSelect: () => console.log("paste") },
+                  { label: "Rename", disabled: true },
+                  { label: "Delete", onSelect: () => console.log("delete") },
+                ]}
+              >
+                <View
+                  layout={{ padding: space("lg"), alignItems: "center" }}
+                  style={{
+                    backgroundColor: theme.color.surfaceAlt,
+                    borderRadius: theme.radius.sm,
+                  }}
+                >
+                  <Text>Secondary actions live here</Text>
+                </View>
+              </ContextMenu>
+            </Card>
+
+            <Card title="Select" layout={{ width: 360 }}>
+              <Text muted>
+                Forks on the interaction policy: desktop and hybrid anchor a dropdown, touch opens a
+                bottom sheet.
+              </Text>
+              <Select
+                value={fruit()}
+                onChange={setFruit}
+                placeholder="Pick a fruit"
+                options={[
+                  { value: "apple", label: "Apple" },
+                  { value: "banana", label: "Banana" },
+                  { value: "cherry", label: "Cherry" },
+                  { value: "dragonfruit", label: "Dragonfruit" },
+                ]}
+                layout={{ width: 200 }}
+              />
+            </Card>
+
+            <Card title="Slider" layout={{ width: 360 }}>
+              <Row label={`Volume: ${Math.round(volume())}`}>
+                <Slider
+                  value={volume()}
+                  onChange={setVolume}
+                  min={0}
+                  max={100}
+                  step={1}
+                  layout={{ width: 180 }}
+                />
+              </Row>
+            </Card>
+
+            <Card title="Progress and spinner" layout={{ width: 360 }}>
+              <Row label="Loading">
+                <Spinner />
+              </Row>
+              <Text muted>Determinate, tracking the volume slider:</Text>
+              <ProgressBar value={volume() / 100} />
+              <Text muted>Indeterminate:</Text>
+              <ProgressBar />
+            </Card>
+
+            <Card title="Badges and divider" layout={{ width: 360 }}>
+              <Row label="Status">
+                <View layout={{ flexDirection: "row", gap: space("md"), alignItems: "center" }}>
+                  <Badge>New</Badge>
+                  <Badge variant="neutral">3</Badge>
+                  <Badge variant="danger">Error</Badge>
+                </View>
+              </Row>
+              <Divider />
+              <Text muted>A divider separates content within a card.</Text>
+            </Card>
+
+            <Card title="Tooltip" layout={{ width: 360 }}>
+              <Text muted>
+                Rest the mouse on a button. Shows under desktop and hybrid interaction policies,
+                never under touch.
+              </Text>
+              <View layout={{ flexDirection: "row", gap: space("md") }}>
+                <Tooltip content="Saves your changes">
+                  <Button>Hover me</Button>
+                </Tooltip>
+                <Tooltip content="Appears below the anchor" placement="bottom">
+                  <Button>Below</Button>
+                </Tooltip>
+              </View>
+            </Card>
+
+            <Card title="Icons" layout={{ width: 360 }}>
+              <Text muted>
+                Lucide SVGs drawn through the core svg primitive. currentColor follows the theme;
+                the last two are recolored explicitly.
+              </Text>
+              <View layout={{ flexDirection: "row", gap: space("lg"), alignItems: "center" }}>
+                <Icon src={HOUSE} />
+                <Icon src={SETTINGS} />
+                <Icon src={BELL} />
+                <Icon src={HEART} color={theme.color.danger} />
+                <Icon src={STAR} color={theme.color.primary} />
+              </View>
+            </Card>
+
+            <Card title="QR code" layout={{ width: 360 }}>
+              <Text muted>Encodes your name, or a link if the field is empty.</Text>
+              <View layout={{ alignItems: "center" }}>
+                <QrCode data={qrData() || "https://solidjs.com"} />
+              </View>
+            </Card>
+
+            <Card title="Image" layout={{ width: 360 }}>
+              <Text muted>
+                Fetches, decodes, and uploads an image, then shows it as a GPU texture. Rounded via
+                a clipping border radius.
+              </Text>
+              <View layout={{ alignItems: "center" }}>
+                <Image src={icon} style={{ borderRadius: theme.radius.md }} />
+              </View>
+            </Card>
+          </View>
+        </ScrollView>
+      </SafeArea>
+    </Window>
+  )
+}
+
+render(() => <App />)

package/src/args.ts

@@ -16,6 +16,7 @@ export let { values, positionals } = parseArgs({
     stats: { type: "boolean", default: false },
     android: { type: "boolean", default: false },
     device: { type: "string" },
+    template: { type: "string", short: "t" },
   },
   allowPositionals: true,
 })
@@ -35,9 +36,6 @@ function usage(line: string): never {
 // Per-command argument requirements. Called once before dispatch.
 export function validateArgs() {
   switch (command) {
-    case "init":
-      if (!source) usage("srt init <dir>  (the target folder is required)")
-      break
     case "bundle":
       if (values.flux) {
         if (!source || !isTs) usage("srt bundle --flux [options] <entry.[ts|js]>")
@@ -76,6 +74,9 @@ Commands:
   record <file.tsx|jsx>  Capture frames for video generation
   pack <file>            Bundle + compile to a standalone executable (experimental)
 
+init options:
+  -t, --template <name>  Start from a named template (skips the interactive picker)
+
 run/server options:
       --proxy-files      Route file/dir access through the dev server
       --proxy-http       Route fetch calls through the dev server (HTTP cache enabled)

package/src/commands/init.ts

@@ -1,18 +1,22 @@
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
+import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
-import { source } from "../args"
+import { source, values } from "../args"
+import { select, text } from "../prompt"
+
+const DEFAULT_NAME = "solidrt-app"
 
 const SCAFFOLD_DIR = join(import.meta.dir, "../../scaffold")
+const TEMPLATES_DIR = join(SCAFFOLD_DIR, "templates")
 
-// What gets written into a new project. Sources live in cli/scaffold/. The
-// .gitignore is stored there as `gitignore` because npm strips files literally
-// named `.gitignore` from published packages, so it is renamed on the way out.
+// Shared project files written for every template. Sources live in
+// cli/scaffold/. The .gitignore is stored there as `gitignore` because npm
+// strips files literally named `.gitignore` from published packages, so it is
+// renamed on the way out. The per-template src/ comes from scaffold/templates/.
 const TEMPLATE_FILES: Array<{ from: string; to: string }> = [
   { from: "package.json", to: "package.json" },
   { from: "tsconfig.json", to: "tsconfig.json" },
   { from: "gitignore", to: ".gitignore" },
   { from: "AGENTS.md", to: "AGENTS.md" },
-  { from: "src/index.tsx", to: "src/index.tsx" },
 ]
 
 // A valid npm package name derived from the target directory.
@@ -23,17 +27,63 @@ function packageName(dir: string): string {
   return name || "solidrt-app"
 }
 
+const DEFAULT_TEMPLATE = "default"
+
+// Templates are the directories under scaffold/templates/; each holds the files
+// that become the new project's src/. `default` sorts first as the starting
+// point, the rest alphabetically.
+async function listTemplates(): Promise<string[]> {
+  let entries = await readdir(TEMPLATES_DIR, { withFileTypes: true })
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort((a, b) =>
+      a === DEFAULT_TEMPLATE ? -1 : b === DEFAULT_TEMPLATE ? 1 : a.localeCompare(b),
+    )
+}
+
+// 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<string> {
+  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) {
+    if (!templates.includes(chosen)) {
+      console.error(`!! Unknown template "${chosen}"; choose from: ${templates.join(", ")}`)
+      process.exit(1)
+    }
+    return chosen
+  }
+  if (process.stdin.isTTY) return select("Select a template", templates)
+  return templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0]!
+}
+
 export async function runInitCommand() {
-  // The target folder is required (validateArgs enforces it) and must be empty
-  // or absent, so init can never overwrite files in an existing project.
-  let dir = source!
+  // The target folder comes from the positional arg, or an interactive prompt
+  // (defaulting to a suggested name) when omitted.
+  let dir = source
+  if (!dir) {
+    dir = await text("Project name", DEFAULT_NAME)
+    if (!dir) {
+      console.error("!! A project name is required")
+      process.exit(1)
+    }
+  }
+
+  // The folder must not exist yet, so init can never touch an existing project.
   let existing = await readdir(dir).catch(() => null)
-  if (existing && existing.length > 0) {
-    console.error(`!! ${resolve(dir)} already exists and is not empty; choose a new folder name`)
+  if (existing) {
+    console.error(`!! ${resolve(dir)} already exists; choose a new folder name`)
     process.exit(1)
   }
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)}`)
+  let template = await resolveTemplate()
+
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
@@ -41,6 +91,15 @@ 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.
+  let templateDir = join(TEMPLATES_DIR, template)
+  await mkdir(join(dir, "src"), { recursive: true })
+  for (let file of await readdir(templateDir)) {
+    await cp(join(templateDir, file), join(dir, "src", file), { recursive: true })
+    console.log(`   Write src/${file}`)
+  }
+
   // The scaffold package.json carries a placeholder name; set it from the
   // target folder.
   let pkgPath = join(dir, "package.json")

package/src/prompt.ts

@@ -0,0 +1,76 @@
+import { createInterface, emitKeypressEvents } from "node:readline"
+
+// 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)
+    })
+  })
+}
+
+// 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. 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: string[]): Promise<string> {
+  return new Promise((resolve) => {
+    let input = process.stdin
+    let output = process.stdout
+    if (!input.isTTY) return resolve(options[0]!)
+
+    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[${options.length + 1}A`)
+      output.write(`\x1b[K? ${message}\n`)
+      for (let i = 0; i < options.length; i++) {
+        let active = i === selected
+        let pointer = active ? "\x1b[36m> " : "  "
+        let reset = active ? "\x1b[0m" : ""
+        output.write(`\x1b[K${pointer}${options[i]}${reset}\n`)
+      }
+    }
+
+    let cleanup = () => {
+      input.off("keypress", onKey)
+      input.setRawMode(wasRaw)
+      input.pause()
+    }
+
+    let onKey = (_str: string, key: { name: string; ctrl: boolean } | undefined) => {
+      if (!key) return
+      if (key.name === "up") {
+        selected = (selected - 1 + options.length) % options.length
+        render()
+      } else if (key.name === "down") {
+        selected = (selected + 1) % options.length
+        render()
+      } else if (key.name === "return" || key.name === "enter") {
+        cleanup()
+        output.write("\n")
+        resolve(options[selected]!)
+      } else if (key.ctrl && (key.name === "c" || key.name === "d")) {
+        cleanup()
+        output.write("\n")
+        process.exit(130)
+      }
+    }
+
+    input.on("keypress", onKey)
+    input.resume()
+    render(true)
+  })
+}