@stackbox/cms 0.0.2 → 0.0.4

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node -e \"import\\('@hyperspan/html'\\).then\\(m => console.log\\('html export:', typeof m.html\\)\\)\")",
+      "Bash(npm run *)"
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,87 @@
+# @stackbox/cms — agent instructions
+
+Stackbox is a code-first CMS that assembles TypeScript into a **fetch-handler-compatible server**. Use these conventions when building or extending a site.
+
+## Site conventions
+
+| Primitive | Factory | Purpose |
+| --- | --- | --- |
+| Site config | `createSiteConfig(config)` | Definition-time settings shared by templates and pages |
+| Site | `createSite(siteConfig, { pages })` | Runtime router with `fetch(request, env)` |
+| Template | `createTemplate({ siteConfig, slots, render })` | Reusable layout with named slots |
+| Page | `createPage(template, { path, title, slots })` | A single URL built from a template + slot content |
+| Block | `createBlock({ name, render })` | A content block placed into a slot at request time |
+
+**Project layout:**
+
+```
+site.config.ts       # createSiteConfig
+server.ts            # createSite(...) — default export is the fetch handler
+templates/           # shared createTemplate() layouts
+pages/               # createPage() per route or feature
+content/             # markdown or other bundle-time content (per feature)
+```
+
+The default export from `server.ts` implements `fetch(request, env)` and returns a `Response`. It works on Cloudflare Workers, Bun, Deno, and any runtime that speaks the fetch-handler pattern.
+
+## Plugins vs blocks
+
+- **Plugin** — a packaged use-case under `@stackbox/cms/plugins/<name>` (e.g. blog). May export factories, content objects, blocks, types, and helpers.
+- **Block** — a core primitive via `createBlock()`. Renders HTML into a template slot. Usable inside or outside plugins.
+
+Slot content is `Block | string`. Plugin content arrays can interleave blocks and HTML strings.
+
+## Plugin catalog
+
+Before implementing a use-case (blog, newsletter, docs, …), check this table. If the user's request matches a row, **read only that plugin's AGENTS.md** and follow it. Do not invent a parallel implementation.
+
+| Plugin | Import | Read when the user mentions | Instructions |
+| --- | --- | --- | --- |
+| blog | `@stackbox/cms/plugins/blog` | blog, posts, articles, journal, markdown posts, blog listing, blog page | `src/plugins/blog/AGENTS.md` |
+| random-quote | `@stackbox/cms/plugins/random-quote` | random quote, quote of the day, inspirational quote, sidebar quote | `src/plugins/random-quote/AGENTS.md` |
+
+When adding a new plugin to this package, add a row here and create `src/plugins/<name>/AGENTS.md` using the same heading structure as the blog plugin. Document all export kinds (factory, types, blocks, helpers).
+
+## Plugin public assets
+
+Runtime files that must be **publicly available** (images, CSS, fonts, JSON served over HTTP) go in:
+
+```
+src/plugins/<name>/public_assets/
+```
+
+**Opt-in:** only plugins with a `public_assets/` folder get copied at build time. Do not edit the copy script when adding files.
+
+Build copies each `public_assets/` folder to:
+
+- `dist/public/_sb/plugins/<name>/` — served at `/_sb/plugins/<name>/...`
+- `dist/plugins/<name>/public_assets/` — so `import "./public_assets/..." with { type: "json" }` works in compiled JS
+
+Use `pluginAssetPath()` from `@stackbox/cms/link` for `<img src>`, `<link href>`, etc. Do not put site files under `/_sb/` — that prefix is reserved for Stackbox plugin assets.
+
+```ts
+import { pluginAssetPath } from "@stackbox/cms/link";
+
+pluginAssetPath("random-quote", "photo.jpg");
+// → "/_sb/plugins/random-quote/photo.jpg"
+```
+
+For data bundled into JS at build time, import from `./public_assets/...` in the plugin's `index.ts`.
+
+## For site agents
+
+If you are working in a **consumer site repo** (not this package), read this file from the installed package:
+
+```
+node_modules/@stackbox/cms/AGENTS.md
+```
+
+Recommended snippet for the site's own `AGENTS.md`:
+
+```md
+This site uses @stackbox/cms. Before adding features, read
+`node_modules/@stackbox/cms/AGENTS.md` and follow its plugin catalog.
+Do not reimplement bundled plugins.
+```
+
+When a request matches a catalog row, open **only** that plugin's instructions file (e.g. `node_modules/@stackbox/cms/src/plugins/blog/AGENTS.md`).

package/README.md

@@ -1,12 +1,22 @@
 # @stackbox/cms
 
-A small, code-first CMS engine for building dynamic [Cloudflare Worker](https://developers.cloudflare.com/workers/) sites. Stackbox is designed to be driven by AI: pages, templates, and content modules are plain TypeScript files with typed, composable APIs, so an agent can author and assemble a site without a database, admin UI, or hand-written backend.
+A small, code-first CMS engine for building dynamic sites behind a standard **fetch handler**. Stackbox is designed to be driven by AI: pages, templates, blocks, and plugins are plain TypeScript files with typed, composable APIs, so an agent can author and assemble a site without a database, admin UI, or hand-written backend.
 
-Pages are rendered on each request inside a Cloudflare Worker, so content, templates, and modules can be fully dynamic — driven by request data, bindings (KV, D1, R2), and async data fetching.
+`createSite()` returns an object with a `fetch(request, env)` method — the same shape used by Cloudflare Workers, Bun, Deno, and other runtimes that serve HTTP via the Fetch API:
+
+```ts
+export default {
+  fetch(req: Request): Response | Promise<Response> {
+    return new Response(...);
+  },
+};
+```
+
+Pages are rendered on each request, so content, templates, blocks, and plugins can be fully dynamic — driven by request data, environment bindings, and async data fetching.
 
 ## Why this exists
 
-Traditional CMSes assume a human clicking around an admin panel. Stackbox inverts that: a site is TypeScript modules assembled into a Worker. Every primitive (`createSiteConfig`, `createSite`, `createTemplate`, `createPage`, `createModule`) is a typed factory suited for AI to generate, edit, and validate site content as code — and the same files render dynamically on Cloudflare Workers at request time.
+Traditional CMSes assume a human clicking around an admin panel. Stackbox inverts that: a site is TypeScript assembled into a fetch handler. Every primitive (`createSiteConfig`, `createSite`, `createTemplate`, `createPage`, `createBlock`) is a typed factory suited for AI to generate, edit, and validate site content as code — and the same files render dynamically at request time.
 
 ## Requirements
 
@@ -23,19 +33,21 @@ npm install @stackbox/cms
 | Primitive | Factory | Purpose |
 | --- | --- | --- |
 | **Site config** | `createSiteConfig(config)` | Definition-time settings shared by templates and pages. |
-| **Site** | `createSite(siteConfig, { pages }` | Runtime router with `fetch(request, env)` for Cloudflare Workers. |
-| **Template** | `createTemplate({ siteConfig, slots, render }` | A reusable page layout that declares named **slots**. |
-| **Page** | `createPage(template, { path, title, slots }` | A single URL, built by filling a template's slots with content. |
-| **Module** | `createModule({ name, render }` | A self-contained content block placed into a slot. |
+| **Site** | `createSite(siteConfig, { pages })` | Runtime router with `fetch(request, env)` — a fetch-handler-compatible server. |
+| **Template** | `createTemplate({ siteConfig, slots, render })` | A reusable page layout that declares named **slots**. |
+| **Page** | `createPage(template, { path, title, slots })` | A single URL, built by filling a template's slots with content. |
+| **Block** | `createBlock({ name, render })` | A self-contained content block placed into a slot at request time. |
 
-**Slots** are named regions in a template. Page content — strings, HTML, or modules — is dropped into slots, and the engine resolves and renders everything (including `async` modules, concurrently) to a single HTML string.
+**Plugins vs blocks:** **Plugins** package whole features (blog, newsletter) under `@stackbox/cms/plugins/<name>` — they may export factories, content objects, blocks, types, and helpers. **Blocks** are the core slot primitive via `createBlock()`; plugins can ship blocks alongside other exports.
+
+**Slots** are named regions in a template. Page content — strings, HTML, or blocks — is dropped into slots, and the engine resolves and renders everything (including async blocks, concurrently) to a single HTML string.
 
 ## Project layout
 
 ```
-my-worker/
+my-site/
   site.config.ts      # createSiteConfig({ name, url, ... })
-  worker.ts           # createSite(siteConfig, { pages }) — default export for Cloudflare
+  server.ts           # createSite(...) — default export is your fetch handler
   templates/
     site-template.ts  # shared createTemplate() layouts
   pages/
@@ -60,8 +72,7 @@ export default createSiteConfig({
 `templates/site-template.ts`:
 
 ```ts
-import { html } from "@hyperspan/html";
-import { createTemplate } from "@stackbox/cms";
+import { createTemplate, html } from "@stackbox/cms";
 import siteConfig from "../site.config";
 
 export const siteTemplate = createTemplate({
@@ -88,7 +99,7 @@ const homePage = createPage(siteTemplate, {
 export default homePage;
 ```
 
-`worker.ts`:
+`server.ts`:
 
 ```ts
 import { createSite } from "@stackbox/cms";
@@ -101,9 +112,13 @@ export default createSite(siteConfig, {
 });
 ```
 
-Deploy with [`wrangler`](https://developers.cloudflare.com/workers/wrangler/). The default export's `fetch(request, env)` handles each request.
+The default export implements `fetch(request, env)` and returns a `Response` — drop it into any runtime that speaks the fetch-handler pattern. For example:
+
+- **[Cloudflare Workers](https://developers.cloudflare.com/workers/)** — deploy with [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) (often as `worker.ts`)
+- **[Bun](https://bun.sh/docs/api/http#fetch-handler)** — `Bun.serve({ fetch: site.fetch })`
+- **[Deno](https://docs.deno.com/runtime/fundamentals/http_server/)** — `Deno.serve(site.fetch)`
 
-## Blog module
+## Blog plugin
 
 `createBlog()` loads markdown at bundle time and returns **content objects** you wire into your own pages with `createPage()` — so you control templates, slots, and any extra content alongside blog output.
 
@@ -111,7 +126,7 @@ Deploy with [`wrangler`](https://developers.cloudflare.com/workers/wrangler/). T
 // pages/blog.ts
 import { join } from "node:path";
 import { createPage } from "@stackbox/cms";
-import { createBlog } from "@stackbox/cms/modules/blog";
+import { createBlog } from "@stackbox/cms/plugins/blog";
 import { siteTemplate } from "../templates/site-template";
 
 const blog = createBlog({
@@ -141,7 +156,7 @@ export const blogPostPages = blog.posts.map((post) =>
 ```
 
 ```ts
-// worker.ts
+// server.ts
 import { blogListingPages, blogPostPages } from "./pages/blog";
 
 export default createSite(siteConfig, {
@@ -149,10 +164,34 @@ export default createSite(siteConfig, {
 });
 ```
 
-## Bundled modules
+## Bundled plugins
+
+**Blog** — content objects wired into pages:
+
+```ts
+import { createBlog } from "@stackbox/cms/plugins/blog";
+```
+
+**Random quote** — block-only plugin (drop into any slot):
 
 ```ts
-import { createBlog } from "@stackbox/cms/modules/blog";
+import { randomQuoteBlock } from "@stackbox/cms/plugins/random-quote";
+import myQuotes from "../content/quotes.json" with { type: "json" };
+
+slots: { sidebar: [randomQuoteBlock()] } // bundled quotes
+slots: { sidebar: [randomQuoteBlock({ quotes: myQuotes })] } // your own
+```
+
+## AI agents
+
+Bundled plugins include agent playbooks. See [`AGENTS.md`](AGENTS.md) for site conventions and a plugin catalog. When a user asks for a feature (e.g. "add a blog"), read **only** the matching plugin's `AGENTS.md` — do not load every plugin file.
+
+If you are building a site that uses this package, add this to your project's `AGENTS.md`:
+
+```md
+This site uses @stackbox/cms. Before adding features, read
+`node_modules/@stackbox/cms/AGENTS.md` and follow its plugin catalog.
+Do not reimplement bundled plugins.
 ```
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbox/cms",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Stackbox CMS engine",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -17,13 +17,21 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./modules/blog": {
-      "types": "./dist/modules/blog/module.d.ts",
-      "import": "./dist/modules/blog/module.js"
+    "./plugins/blog": {
+      "types": "./dist/plugins/blog/index.d.ts",
+      "import": "./dist/plugins/blog/index.js"
+    },
+    "./plugins/random-quote": {
+      "types": "./dist/plugins/random-quote/index.d.ts",
+      "import": "./dist/plugins/random-quote/index.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "import": "./dist/link.js"
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/copy-plugin-assets.mjs",
     "test": "npm run build && node --import tsx --test test/*.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepublishOnly": "npm run build"

package/scripts/copy-plugin-assets.mjs

@@ -0,0 +1,30 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pluginsDir = join(root, "src/plugins");
+
+if (!existsSync(pluginsDir)) {
+  process.exit(0);
+}
+
+for (const name of readdirSync(pluginsDir)) {
+  const pluginDir = join(pluginsDir, name);
+  if (!statSync(pluginDir).isDirectory()) {
+    continue;
+  }
+
+  const publicAssets = join(pluginDir, "public_assets");
+  if (!existsSync(publicAssets)) {
+    continue;
+  }
+
+  const publicDest = join(root, "dist/public/_sb/plugins", name);
+  mkdirSync(dirname(publicDest), { recursive: true });
+  cpSync(publicAssets, publicDest, { recursive: true });
+
+  const importDest = join(root, "dist/plugins", name, "public_assets");
+  mkdirSync(dirname(importDest), { recursive: true });
+  cpSync(publicAssets, importDest, { recursive: true });
+}

package/src/blocks.ts

@@ -0,0 +1,58 @@
+import type { RenderContext } from "./pages.js";
+import type { HSHtml } from "@hyperspan/html";
+
+export type BlockRenderResult = HSHtml | Promise<HSHtml>;
+
+export type Block = {
+  readonly __kind: "block";
+  readonly name: string;
+  render(ctx: RenderContext): BlockRenderResult;
+};
+
+type BlockDef<TOptions = undefined> = {
+  name: string;
+  render(options: TOptions, ctx?: RenderContext): BlockRenderResult;
+};
+
+export type BlockOptionsOf<F> = F extends (options?: infer O) => unknown
+  ? [O] extends [undefined]
+    ? undefined
+    : O
+  : never;
+
+export type BlockFactory<TOptions = undefined> = (
+  options?: TOptions,
+) => Block;
+
+function validateBlockName(name: string): void {
+  if (!name || name.length === 0) {
+    throw new Error("createBlock(def): name is required");
+  }
+}
+
+export function createBlock<TOptions = undefined>(
+  def: BlockDef<TOptions>,
+): BlockFactory<TOptions> {
+  validateBlockName(def.name);
+
+  if (typeof def.render !== "function") {
+    throw new Error("createBlock(def): render is required");
+  }
+
+  return ((options?: TOptions) => ({
+    __kind: "block" as const,
+    name: def.name,
+    render: (ctx: RenderContext) => def.render(options as TOptions, ctx),
+  })) as BlockFactory<TOptions>;
+}
+
+export function isBlock(value: unknown): value is Block {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Block).__kind === "block" &&
+    typeof (value as Block).name === "string" &&
+    (value as Block).name.length > 0 &&
+    typeof (value as Block).render === "function"
+  );
+}

package/src/index.ts

@@ -1,11 +1,12 @@
+export { html } from "@hyperspan/html";
 export {
-  createModule,
-  isModule,
-  type Module,
-  type ModuleFactory,
-  type ModuleOptionsOf,
-  type ModuleRenderResult,
-} from "./modules.js";
+  createBlock,
+  isBlock,
+  type Block,
+  type BlockFactory,
+  type BlockOptionsOf,
+  type BlockRenderResult,
+} from "./blocks.js";
 export {
   createPage,
   isPage,
@@ -33,7 +34,7 @@ export {
 export { createContext, Stackbox } from "./stackbox/context.js";
 export {
   anySlotContentSchema,
-  moduleSlotContentSchema,
+  blockSlotContentSchema,
   slotHasContent,
   SlotContentValidationError,
   stringSlotContentSchema,

package/src/link.ts

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, normalize, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizePathname } from "./routing.js";
+
+export const PLUGIN_PUBLIC_PREFIX = "/_sb/plugins";
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+function assertSafeSegment(segment: string, label: string): void {
+  if (
+    !segment ||
+    segment === "." ||
+    segment === ".." ||
+    segment.includes("/") ||
+    segment.includes("\\")
+  ) {
+    throw new Error(`pluginAssetPath: invalid ${label}`);
+  }
+}
+
+export function pluginAssetPath(pluginName: string, relativePath: string): string {
+  assertSafeSegment(pluginName, "plugin name");
+  const segments = relativePath
+    .split(/[/\\]+/)
+    .filter((segment) => segment.length > 0);
+  for (const segment of segments) {
+    assertSafeSegment(segment, "relative path segment");
+  }
+  return `${PLUGIN_PUBLIC_PREFIX}/${pluginName}/${segments.join("/")}`;
+}
+
+export type PluginAssetRequest = {
+  plugin: string;
+  relativePath: string;
+};
+
+export function parsePluginAssetRequest(
+  pathname: string,
+): PluginAssetRequest | null {
+  const normalized = normalizePathname(pathname);
+  const prefix = `${PLUGIN_PUBLIC_PREFIX}/`;
+  if (!normalized.startsWith(prefix)) {
+    return null;
+  }
+
+  const rest = normalized.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  if (slash <= 0 || slash === rest.length - 1) {
+    return null;
+  }
+
+  const plugin = rest.slice(0, slash);
+  const relativePath = rest.slice(slash + 1);
+  if (
+    !plugin ||
+    !relativePath ||
+    relativePath.includes("..") ||
+    relativePath.includes("\\")
+  ) {
+    return null;
+  }
+
+  try {
+    assertSafeSegment(plugin, "plugin name");
+    for (const segment of relativePath.split("/")) {
+      assertSafeSegment(segment, "relative path segment");
+    }
+  } catch {
+    return null;
+  }
+
+  return { plugin, relativePath };
+}
+
+export function getPluginPublicRootDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const fromDist = join(here, "public", "_sb", "plugins");
+  if (existsSync(fromDist)) {
+    return fromDist;
+  }
+
+  const fromSrcDev = join(here, "..", "dist", "public", "_sb", "plugins");
+  if (existsSync(fromSrcDev)) {
+    return fromSrcDev;
+  }
+
+  return fromDist;
+}
+
+function contentTypeForPath(relativePath: string): string {
+  const dot = relativePath.lastIndexOf(".");
+  if (dot === -1) {
+    return "application/octet-stream";
+  }
+  return CONTENT_TYPES[relativePath.slice(dot).toLowerCase()] ??
+    "application/octet-stream";
+}
+
+function resolvePluginAssetFile(request: PluginAssetRequest): string | null {
+  const root = getPluginPublicRootDir();
+  const absolute = normalize(join(root, request.plugin, request.relativePath));
+  const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
+  if (!absolute.startsWith(rootWithSep)) {
+    return null;
+  }
+  if (!existsSync(absolute)) {
+    return null;
+  }
+  return absolute;
+}
+
+export function servePluginAsset(
+  pathname: string,
+  method: string,
+): globalThis.Response | null {
+  const request = parsePluginAssetRequest(pathname);
+  if (!request) {
+    return null;
+  }
+
+  const filePath = resolvePluginAssetFile(request);
+  if (!filePath) {
+    return new globalThis.Response("Not Found", { status: 404 });
+  }
+
+  const contentType = contentTypeForPath(request.relativePath);
+  if (method === "HEAD") {
+    const body = readFileSync(filePath);
+    return new globalThis.Response(null, {
+      status: 200,
+      headers: {
+        "content-type": contentType,
+        "content-length": String(body.byteLength),
+      },
+    });
+  }
+
+  const body = readFileSync(filePath);
+  return new globalThis.Response(body, {
+    status: 200,
+    headers: { "content-type": contentType },
+  });
+}

package/src/pages.ts

@@ -180,7 +180,7 @@ export function createPage(
     const items = def.slots[required as keyof typeof def.slots];
     if (!items || items.length === 0 || !slotHasContent(items)) {
       throw new PageValidationError(
-        `required slot "${required}" must have at least one module or non-empty HTML string`,
+        `required slot "${required}" must have at least one block or non-empty HTML string`,
       );
     }
   }