@zvndev/darkmown 1.1.0 → 1.2.0

package/src/builder.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { discoverApiRoutes } from "./api-runner.js";
 import { compilePage } from "./compiler.js";
 import { createPaths } from "./config.js";
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
@@ -24,10 +25,19 @@ const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
 /**
  * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ *
+ * The build is always 100% static, CDN-cacheable HTML. Backend `api/*.js`
+ * functions are NOT compiled — they are the host's concern. `target` only
+ * decides the small amount of host glue Darkmown emits alongside the static
+ * output: the default (`vercel`/anything) leaves `api/` for the platform to pick
+ * up natively; `cloudflare` emits a `dist/_worker.js/` module that routes
+ * `/api/*` to those same functions and serves everything else as a static asset.
+ *
  * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @param {{ target?: string }} [options] `target: "cloudflare"` emits the Pages worker.
  * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
  */
-export function buildSite(cwd = process.cwd()) {
+export function buildSite(cwd = process.cwd(), options = {}) {
   const paths = createPaths(cwd);
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
@@ -55,14 +65,18 @@ export function buildSite(cwd = process.cwd()) {
     if (route.route === "/404/") notFoundHtml = page.html;
     emitAssets(page.assets, paths);
     if (page.assets.runtime) emitRuntime(paths);
+    emitBehaviors(page.assets, paths);
+    const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
     manifest.push({
       route: route.route,
       file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
       assets: {
         skins: [...page.assets.skins],
-        scripts: page.assets.runtime
-          ? ["/__wd/runtime.js", ...page.assets.scripts]
-          : [...page.assets.scripts],
+        scripts: [
+          ...(page.assets.runtime ? ["/__wd/runtime.js"] : []),
+          ...behaviorSrcs,
+          ...page.assets.scripts
+        ],
         runtime: page.assets.runtime
       }
     });
@@ -85,9 +99,173 @@ export function buildSite(cwd = process.cwd()) {
   // sees every emitted route/framework file already on disk.
   emitPageAssets(paths);
 
+  // Surface api/ routing footguns on every build (target-independent): two files
+  // that resolve to the same /api path mean one is silently unreachable.
+  const apiDir = path.join(cwd, "api");
+  const apiRoutes = discoverApiRoutes(apiDir);
+  warnApiRouteCollisions(apiRoutes, apiDir);
+
+  if (options.target === "cloudflare") {
+    emitCloudflareWorker(paths, apiDir, apiRoutes);
+  }
+
   return { routes: manifest, distRoot: paths.distRoot };
 }
 
+/**
+ * Warn when more than one handler resolves to the same `/api` path, since only
+ * one is ever reachable and readdir order silently decides which. Two collisions
+ * are caught: an exact duplicate (`api/users.js` + `api/users/index.js`) and two
+ * dynamic siblings at the same position (`api/[id].js` + `api/[slug].js`), which
+ * is why dynamic segments are normalized to `[*]` before grouping.
+ * @param {import("./api-runner.js").ApiRoute[]} routes
+ * @param {string} apiDir
+ * @returns {void}
+ */
+function warnApiRouteCollisions(routes, apiDir) {
+  /** @type {Map<string, string[]>} */
+  const byPath = new Map();
+  for (const route of routes) {
+    const key = route.segments.map((s) => (s.startsWith("[") ? "[*]" : s)).join("/");
+    const list = byPath.get(key) || [];
+    list.push(path.relative(apiDir, route.file).replaceAll(path.sep, "/"));
+    byPath.set(key, list);
+  }
+  for (const [key, files] of byPath) {
+    if (files.length > 1) {
+      console.warn(
+        `hint: ${files.length} api handlers resolve to /api/${key} — only one is reachable. ` +
+          `Rename or remove: ${files.join(", ")}.`
+      );
+    }
+  }
+}
+
+/**
+ * Emit `dist/_worker.js/` for a Cloudflare Pages deploy (advanced mode). The
+ * project's `api/*.js` functions are copied in, and a generated `index.js` routes
+ * `/api/*` to them (Web-standard `(request, { params, env }) => Response`) and
+ * falls through to `env.ASSETS.fetch(request)` for static files — so `_headers`
+ * still applies to assets. No-op when the project has no `api/` functions.
+ *
+ * Handlers must be dependency-free (or pre-bundled): advanced mode does not run a
+ * bundler, so bare npm imports won't resolve. We scan copied handlers and warn on
+ * any bare specifier. Same source still runs on Vercel (which does bundle) and in
+ * `darkmown dev` — the shape is identical.
+ * @param {Paths} paths
+ * @param {string} apiDir Absolute path to the project's `api/` directory.
+ * @param {import("./api-runner.js").ApiRoute[]} routes Discovered api routes.
+ * @returns {void}
+ */
+function emitCloudflareWorker(paths, apiDir, routes) {
+  if (routes.length === 0) return;
+
+  const workerDir = path.join(paths.distRoot, "_worker.js");
+  fs.mkdirSync(workerDir, { recursive: true });
+
+  /** @type {{ ident: string, spec: string, segments: string[] }[]} */
+  const entries = [];
+  routes.forEach((route, i) => {
+    const rel = path.relative(apiDir, route.file).replaceAll(path.sep, "/");
+    const out = path.join(workerDir, "api", rel);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    const source = fs.readFileSync(route.file, "utf8");
+    warnBareImports(source, `api/${rel}`);
+    fs.writeFileSync(out, source);
+    entries.push({ ident: `h${i}`, spec: `./api/${rel}`, segments: route.segments });
+  });
+
+  const imports = entries
+    .map((e) => `import ${e.ident} from ${JSON.stringify(e.spec)};`)
+    .join("\n");
+  const table = entries
+    .map((e) => `  { segments: ${JSON.stringify(e.segments)}, handler: ${e.ident} }`)
+    .join(",\n");
+
+  fs.writeFileSync(path.join(workerDir, "index.js"), cloudflareWorkerSource(imports, table));
+}
+
+/**
+ * Warn when a Cloudflare-bound handler imports a bare npm package. Advanced mode
+ * runs no bundler, so only relative (`./`, `../`) and `node:` specifiers resolve
+ * at the edge; a bare `import x from "some-pkg"` would fail at runtime with no
+ * build-time signal. Advisory only — relative/`node:`/data imports pass clean.
+ * @param {string} source Handler source.
+ * @param {string} label Human-readable handler path for the message.
+ * @returns {void}
+ */
+function warnBareImports(source, label) {
+  /** @type {Set<string>} */
+  const bare = new Set();
+  const re =
+    /(?:^|[^.\w])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]|(?:^|[^.\w])import\s*\(?\s*['"]([^'"]+)['"]/g;
+  for (let m = re.exec(source); m; m = re.exec(source)) {
+    const spec = m[1] || m[2];
+    if (spec && !/^[./]/.test(spec) && !spec.startsWith("node:")) bare.add(spec);
+  }
+  if (bare.size > 0) {
+    console.warn(
+      `hint: ${label} imports ${[...bare].map((s) => `"${s}"`).join(", ")} — Cloudflare ` +
+        "advanced mode runs no bundler, so bare npm imports won't resolve at the edge. " +
+        "Inline the dependency or pre-bundle the handler."
+    );
+  }
+}
+
+/**
+ * The generated Cloudflare Pages `_worker.js/index.js` source. Mirrors the
+ * dev runner's matching (static beats dynamic; `[param]` capture; `index`
+ * collapses to its directory) so routing is identical across dev and prod.
+ * @param {string} imports
+ * @param {string} table
+ * @returns {string}
+ */
+function cloudflareWorkerSource(imports, table) {
+  return `// Generated by Darkmown for Cloudflare Pages (advanced mode). Routes /api/* to
+// the project's api functions; every other request is a static asset.
+${imports}
+
+const routes = [
+${table}
+];
+
+function match(pathname) {
+  if (pathname !== "/api" && !pathname.startsWith("/api/")) return null;
+  const parts = pathname.split("/").filter(Boolean).slice(1);
+  for (const route of routes) {
+    if (route.segments.length !== parts.length) continue;
+    const params = {};
+    let ok = true;
+    for (let i = 0; i < parts.length; i++) {
+      const seg = route.segments[i];
+      if (seg[0] === "[" && seg[seg.length - 1] === "]") {
+        params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+      } else if (seg !== parts[i]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) return { handler: route.handler, params };
+  }
+  return null;
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    const matched = match(new URL(request.url).pathname);
+    if (!matched) return env.ASSETS.fetch(request);
+    try {
+      const response = await matched.handler(request, { params: matched.params, env });
+      if (response instanceof Response) return response;
+      return Response.json({ ok: false, error: "Handler did not return a Response" }, { status: 500 });
+    } catch (err) {
+      return Response.json({ ok: false, error: String((err && err.message) || err) }, { status: 500 });
+    }
+  }
+};
+`;
+}
+
 /**
  * Strip developer comments from the runtime before it ships. The source keeps
  * full JSDoc type annotations (for `checkJs` + `.d.ts`) and explanatory comments
@@ -192,6 +370,23 @@ function emitRuntime(paths) {
   fs.writeFileSync(out, stripRuntimeComments(source));
 }
 
+/**
+ * Emit the pay-for-what-you-use behavior modules a page asked for, comment-
+ * stripped like the runtime. Each is a standalone `/__wd/behaviors/<name>.js`
+ * module, NOT part of `runtime.js`, so the core runtime budget is untouched.
+ * @param {Assets} assets
+ * @param {Paths} paths
+ * @returns {void}
+ */
+function emitBehaviors(assets, paths) {
+  for (const name of assets.behaviors) {
+    const source = fs.readFileSync(path.join(moduleDir, "behaviors", `${name}.js`), "utf8");
+    const out = path.join(paths.distRoot, "__wd/behaviors", `${name}.js`);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, stripRuntimeComments(source));
+  }
+}
+
 /**
  * @param {Assets} assets
  * @param {Paths} paths

package/src/cli.js

@@ -4,9 +4,11 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { handleApiRequest } from "./api-runner.js";
 import { buildSite } from "./builder.js";
+import { DEPLOY_TARGETS, deploy } from "./deploy.js";
 import { devClientPath, devClientScript, devEventsPath, injectDevClient } from "./dev.js";
-import { initProject } from "./scaffold.js";
+import { availableTemplates, initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
@@ -27,6 +29,7 @@ const cliPath = fileURLToPath(import.meta.url);
  * @property {(message?: unknown, ...rest: unknown[]) => void} [log] stdout sink.
  * @property {(message?: unknown, ...rest: unknown[]) => void} [warn] stderr (warn) sink.
  * @property {(message?: unknown, ...rest: unknown[]) => void} [error] stderr (error) sink.
+ * @property {(file: string, args: string[], options: object) => Promise<{ code: number, stdout: string, stderr: string }>} [spawn] Process runner for `deploy` (defaults to a real spawn); injectable for tests.
  *
  * @param {string[]} argv The argv tail (i.e. `process.argv.slice(2)`).
  * @param {RunEnv} [env]
@@ -51,16 +54,20 @@ export async function run(argv, env = {}) {
     return { command: "version" };
   }
   if (command === "init") {
-    const target = argv[1] || ".";
-    const result = initProject(path.resolve(cwd, target));
+    const target = argv.slice(1).find((arg) => !arg.startsWith("-")) || ".";
+    const template = flagValue(argv, "--template");
+    const result = initProject(path.resolve(cwd, target), { template });
     const relativeRoot = path.relative(cwd, result.root) || ".";
-    log(`Created Darkmown project at ${relativeRoot}`);
+    log(`Created Darkmown project (${result.template}) at ${relativeRoot}`);
     log(`Next: ${nextStep(relativeRoot)}`);
     return { command: "init" };
   }
   if (command === "build") {
-    const result = buildSite(cwd);
+    const target = flagValue(argv, "--target");
+    const result = buildSite(cwd, { target });
     log(`Built ${result.routes.length} routes into ${path.relative(cwd, result.distRoot)}`);
+    if (target === "cloudflare")
+      log("Emitted dist/_worker.js for Cloudflare Pages api/* functions");
     return { command: "build" };
   }
   if (command === "dev") {
@@ -69,6 +76,15 @@ export async function run(argv, env = {}) {
   if (command === "serve") {
     return startPreviewServer({ cwd, log, error });
   }
+  if (command === "deploy") {
+    const target = argv.slice(1).find((arg) => !arg.startsWith("-"));
+    if (!target) {
+      error(`Usage: darkmown deploy <${DEPLOY_TARGETS.join("|")}> [--prod]`);
+      throw new CliError("Missing deploy target", { silent: true });
+    }
+    await deploy({ cwd, target, prod: argv.includes("--prod"), log, run: env.spawn });
+    return { command: "deploy" };
+  }
   // No command matched: report it, show help, and fail like the binary always
   // did (exit 1). `silent` keeps `main` from re-printing a `✗` line on top.
   error(`Unknown command: ${command}`);
@@ -157,52 +173,43 @@ function startDevServer({ cwd, log, warn, error }) {
     }
   }
 
+  const apiDir = path.join(cwd, "api");
   const server = http.createServer((req, res) => {
-    try {
-      const url = req.url || "/";
-      if (url.split("?")[0] === devEventsPath) {
-        res.writeHead(200, {
-          "content-type": "text/event-stream",
-          "cache-control": "no-cache",
-          connection: "keep-alive"
-        });
-        res.write("\n");
-        clients.add(res);
-        // Replay a broken build to clients that connect while it's still failing,
-        // so the overlay shows even after a startup or pre-connect compile error.
-        if (lastBuildError) {
-          res.write(
-            `event: builderror\ndata: ${JSON.stringify({ message: lastBuildError.slice(0, 4000) })}\n\n`
-          );
-        }
-        req.on("close", () => clients.delete(res));
-        return;
-      }
-      if (url.split("?")[0] === devClientPath) {
-        res.writeHead(200, { "content-type": "text/javascript" });
-        res.end(devClientScript());
-        return;
-      }
-      if (url.split("?")[0] === "/__wd/echo" && req.method === "POST") {
-        let body = "";
-        req.on("data", (chunk) => (body += chunk));
-        req.on("end", () => {
-          res.writeHead(200, { "content-type": "application/json" });
-          res.end(
-            JSON.stringify({
-              ok: true,
-              received: Object.fromEntries(new URLSearchParams(body)),
-              at: new Date().toISOString()
-            })
-          );
-        });
-        return;
+    const url = req.url || "/";
+    if (url.split("?")[0] === devEventsPath) {
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive"
+      });
+      res.write("\n");
+      clients.add(res);
+      // Replay a broken build to clients that connect while it's still failing,
+      // so the overlay shows even after a startup or pre-connect compile error.
+      if (lastBuildError) {
+        res.write(
+          `event: builderror\ndata: ${JSON.stringify({ message: lastBuildError.slice(0, 4000) })}\n\n`
+        );
       }
-      serveDev(distRoot, url, res);
-    } catch (err) {
-      res.writeHead(500, { "content-type": "text/plain" });
-      res.end((err instanceof Error && err.stack) || String(err));
+      req.on("close", () => clients.delete(res));
+      return;
     }
+    if (url.split("?")[0] === devClientPath) {
+      res.writeHead(200, { "content-type": "text/javascript" });
+      res.end(devClientScript());
+      return;
+    }
+    // Serverless parity: run a project `api/*.js` function if the path matches,
+    // exactly as Vercel/Cloudflare would in production; otherwise serve static. A
+    // throw on either path (e.g. a stat/read error) becomes a clean 500.
+    handleApiRequest({ apiDir, req, res })
+      .then((handled) => {
+        if (!handled) serveDev(distRoot, url, res);
+      })
+      .catch((err) => {
+        res.writeHead(500, { "content-type": "text/plain" });
+        res.end((err instanceof Error && err.stack) || String(err));
+      });
   });
 
   return new Promise((resolve) => {
@@ -293,16 +300,20 @@ export function helpText() {
   return `Darkmown
 
 Usage:
-  darkmown init [dir]   Scaffold a new Darkmown project
-  darkmown dev          Start the live compiler dev server
-  darkmown build        Compile site/pages into dist
-  darkmown serve        Preview the built dist locally
-  darkmown version      Print the installed Darkmown version
-  darkmown help         Show this help
+  darkmown init [dir] [--template <name>]   Scaffold a new project from a template
+  darkmown dev                              Start the live compiler dev server
+  darkmown build [--target cloudflare]      Compile site/pages into dist
+  darkmown deploy <${DEPLOY_TARGETS.join("|")}> [--prod]    Build + deploy to a platform
+  darkmown serve                            Preview the built dist locally
+  darkmown version                          Print the installed Darkmown version
+  darkmown help                             Show this help
+
+Templates (init --template <name>): ${availableTemplates().join(", ")}
 
 Authoring:
   site/pages          File-based routes: .md stays plain, .wd adds directives
   site/_              Include shelf for @include /name.wd
+  api/                Serverless functions: export default (request) => Response
   @loop x into item   Loop over JSON files, in-scope values, or :state lists
   *.skin              Colocated indentation-based CSS
   *.js                Colocated page behavior
@@ -318,6 +329,20 @@ export function nextStep(relativeRoot) {
   return `cd ${relativeRoot} && npm install && npm run dev`;
 }
 
+/**
+ * Read a `--flag value` or `--flag=value` option out of an argv tail.
+ * @param {string[]} argv The argv tail.
+ * @param {string} flag The flag name, e.g. `"--target"`.
+ * @returns {string | undefined} The value, or undefined when the flag is absent.
+ */
+export function flagValue(argv, flag) {
+  const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
+  if (inline) return inline.slice(flag.length + 1);
+  const index = argv.indexOf(flag);
+  if (index !== -1 && index + 1 < argv.length) return argv[index + 1];
+  return undefined;
+}
+
 /**
  * Binary entry point: read argv, dispatch, and map failures to a clean
  * `✗`-prefixed line + exit code 1 — never a Node stack trace. The thrown Error

package/src/compiler/body.js

@@ -11,6 +11,7 @@ import { at } from "./context.js";
 import {
   handleBind,
   handleButton,
+  handleCarousel,
   handleChoiceGroup,
   handleComputed,
   handleContainer,
@@ -24,6 +25,7 @@ import {
   handleInput,
   handleMedia,
   handleSelect,
+  handleSlider,
   handleState,
   handleStore,
   handleSubmit,
@@ -155,6 +157,13 @@ export function compileBody(lines, ctx) {
       i = block.end;
       continue;
     }
+    if (/^:carousel(?:\s|$)/.test(line)) {
+      flush();
+      const block = scanBlock(lines, i, /^:carousel(?:\s|$)/, ":endcarousel", ctx.file);
+      out.push(handleCarousel(line, block.body, ctx, i));
+      i = block.end;
+      continue;
+    }
     if (/^:input\s/.test(line)) {
       flush();
       out.push(handleInput(line, ctx, i));
@@ -197,6 +206,11 @@ export function compileBody(lines, ctx) {
       out.push(handleBind(line, ctx, i));
       continue;
     }
+    if (/^:slider\s/.test(line)) {
+      flush();
+      out.push(handleSlider(line, ctx, i));
+      continue;
+    }
     if (/^:submit\s/.test(line)) {
       flush();
       out.push(handleSubmit(line, ctx, i));

package/src/compiler/context.js

@@ -29,6 +29,9 @@
  * @property {Set<string>} scripts Public hrefs of colocated page scripts.
  * @property {Map<string, string>} files Source path → public href for emitted assets.
  * @property {boolean} runtime Whether the reactive runtime is required.
+ * @property {Set<string>} behaviors Names of framework behavior modules this page
+ *   needs (`slider` is compile-time only and never appears here; `sortable`,
+ *   `carousel` each emit a pay-for-what-you-use `/__wd/behaviors/<name>.js`).
  */
 
 /**
@@ -103,6 +106,8 @@
  * @property {NumArg | null} limit
  * @property {string[] | null} empty Empty-branch body lines, if any.
  * @property {boolean} clauseRefsState Whether offset/limit reference state.
+ * @property {boolean} sortable Drag-to-reorder the underlying :state/:store list
+ *   (the `sortable` clause). Only valid on a plain reactive state-key loop.
  */
 
 /**
@@ -130,7 +135,13 @@ export const LOOP_META = {
 /** @returns {Compilation} */
 export function createCompilation() {
   return {
-    assets: { skins: new Set(), scripts: new Set(), files: new Map(), runtime: false },
+    assets: {
+      skins: new Set(),
+      scripts: new Set(),
+      files: new Map(),
+      runtime: false,
+      behaviors: new Set()
+    },
     state: new Map(),
     stores: new Set(),
     warnings: [],

package/src/compiler/directives.js

@@ -578,6 +578,129 @@ export function handleBind(line, ctx, index) {
   return `<input type="${escapeHtml(type)}" data-wd-bind-input="${key}"${valueAttr} ${attrs.join(" ")}>`;
 }
 
+/**
+ * `:slider name [= value] [min=N] [max=N] [step=N] [aria-label="…"] [persist]` — a
+ * range input two-way bound to a NUMBER :state. With `= value` it declares the state
+ * inline (seeding it numeric) and may `persist`; without `=` it binds to an already-
+ * declared :state. Pure compile-time: it reuses the runtime's input binding (range
+ * values coerce to Number), so it ships NO behavior module.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSlider(line, ctx, index) {
+  const head = line.match(/^:slider\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
+  if (!head)
+    throw new Error(
+      `Malformed :slider in ${at(ctx.file, index)}: ${line}. Use: :slider volume = 50 min=0 max=100 step=1`
+    );
+  const name = head[1];
+  let rest = head[2].trim();
+
+  /** @type {string | undefined} */
+  let initialRaw;
+  if (rest.startsWith("=")) {
+    const valueMatch = rest.match(/^=\s*(\S+)\s*(.*)$/);
+    if (!valueMatch)
+      throw new Error(
+        `Malformed :slider initial value in ${at(ctx.file, index)}: ${line}. Use: :slider ${name} = 50`
+      );
+    initialRaw = valueMatch[1];
+    rest = valueMatch[2].trim();
+  }
+
+  let min = "0";
+  let max = "100";
+  let step = "1";
+  /** @type {string | undefined} */
+  let ariaLabel;
+  let persist = false;
+  for (const token of rest.matchAll(/([A-Za-z-]+)=("[^"]*"|\S+)|(\bpersist\b)/g)) {
+    if (token[3]) {
+      persist = true;
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "min") min = value;
+    else if (token[1] === "max") max = value;
+    else if (token[1] === "step") step = value;
+    else if (token[1] === "aria-label") ariaLabel = value;
+    else throw new Error(`Unknown :slider attribute "${token[1]}" in ${at(ctx.file, index)}`);
+  }
+  for (const [label, raw] of [
+    ["min", min],
+    ["max", max],
+    ["step", step]
+  ]) {
+    if (!/^-?\d+(?:\.\d+)?$/.test(raw))
+      throw new Error(`:slider ${label} must be a number in ${at(ctx.file, index)}: ${raw}`);
+  }
+
+  ctx.comp.assets.runtime = true;
+  /** @type {string} */
+  let key;
+  let seed = "";
+  if (initialRaw !== undefined) {
+    const value = parseStateValue(initialRaw, at(ctx.file, index));
+    if (typeof value !== "number")
+      throw new Error(
+        `:slider ${name} initial value must be a number in ${at(ctx.file, index)}: ${initialRaw}`
+      );
+    key = declareState(name, value, ctx);
+    const persistAttr = persist ? ` data-wd-persist="${key}"` : "";
+    seed = `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
+  } else {
+    if (persist)
+      throw new Error(
+        `:slider persist only applies when declaring state inline (:slider ${name} = 0 … persist) in ${at(ctx.file, index)}`
+      );
+    const resolved = resolveStateKey(name, ctx);
+    if (!resolved)
+      throw new Error(
+        `:slider ${name} in ${ctx.file} has no matching state. Declare it: :slider ${name} = 0 min=0 max=100`
+      );
+    key = resolved;
+  }
+
+  const initial = ctx.comp.state.get(key);
+  const valueAttr =
+    initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
+  const ariaAttr = ` aria-label="${escapeHtml(ariaLabel || humanizeName(name))}"`;
+  return `${seed}<input type="range" data-wd-bind-input="${key}" min="${escapeHtml(min)}" max="${escapeHtml(max)}" step="${escapeHtml(step)}"${valueAttr}${ariaAttr}>`;
+}
+
+/**
+ * `:carousel [autoplay=N]` … `:endcarousel` — a horizontally scroll-snapping
+ * carousel. Contract: each DIRECT child element of the track is one slide, so put
+ * each slide in its own block (e.g. a `::: slide` container) and give that block
+ * the slide sizing in your skin — loose prose lines would each count as a slide.
+ * Registers the `carousel` behavior (prev/next, dot nav, optional autoplay, mouse
+ * drag); native CSS scroll-snap + the page skin handle layout and touch swipe.
+ * `autoplay` is suppressed under `prefers-reduced-motion`. No runtime required.
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleCarousel(line, bodyLines, ctx, index) {
+  const match = line.match(/^:carousel\s*(.*)$/);
+  const rest = (match?.[1] || "").trim();
+  let autoplayAttr = "";
+  if (rest) {
+    const auto = rest.match(/^autoplay=(\d+)$/);
+    if (!auto)
+      throw new Error(
+        `Malformed :carousel in ${at(ctx.file, index)}: ${line}. Use: :carousel [autoplay=3000] … :endcarousel`
+      );
+    autoplayAttr = ` data-wd-carousel-autoplay="${auto[1]}"`;
+  }
+  ctx.comp.assets.behaviors.add("carousel");
+  const inner = compileBody(bodyLines, ctx);
+  return `<div class="wd-carousel" data-wd-carousel${autoplayAttr}>\n<div class="wd-carousel-track" data-wd-carousel-track>\n${inner}\n</div>\n</div>`;
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx