# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
node index.js          # Start the server (port 3000)
npx prettier --write . # Format code
```

No build step. No test suite. Restart the server to pick up changes to `index.js` or `db.js`; changes to Eta templates in `views/` are picked up live (cache is disabled).

Requires a `.env` file with `VAPID_PUBLIC_KEY` and `VAPID_PRIVATE_KEY` for web push.

## What This Is

Bliss is a browser-based low-code platform where users build mini web apps ("Structures") entirely through a `/workshop` UI. Each Structure has routes, templates, and SQLite databases — all stored in the main app database and executed at runtime via Node's `vm` module.

## Design philosophy: this is a hypermedia homestead

Bliss templates are not a web-app-with-an-API. There is no client-side framework,
no JSON contract, no build step — the HTML *is* the application, and it composes
by embedding more HTML (see "page-nesting primitive" below). Every template you
write or edit should lean into that instead of fighting it:

- **Prefer `<%~ %>` (raw) over `<%= %>` (HTML-escaped) in Eta templates, always,
  unless you are interpolating into an HTML attribute value.** Attribute values
  (`id="..."`, `data-*="..."`, `href="..."`, `style="..."`, `value="..."`) are
  the one place escaping is not optional — an unescaped `"` there breaks the tag
  itself, not just a security nicety. Everywhere else (text content, `<script>`
  string literals, anything that isn't sitting inside `attr="…"`) use `<%~ %>`.
  Arbitrary HTML/JS in user content is a *feature* here, not a bug to guard
  against — see the `aim` structure's `message` template for the canonical
  comment explaining why. When in doubt: default to raw, escape only when the
  HTML would literally break otherwise.
- **Prefer htmx attributes over hand-rolled JS for anything hypermedia-shaped**
  — polling (`hx-trigger="every 10s"`), lazy loading (`hx-trigger="load"`),
  swapping (`hx-swap-oob`), cross-fragment events (`hx-trigger="foo from:body"`)
  — instead of `setTimeout`/`fetch`/manual DOM patching. If htmx (or Hyperscript
  for small imperative glue) can express it declaratively, don't write the
  imperative version.

### Two layers of routes

The Express app has two kinds of routes:

1. **Workshop routes** (hardcoded in `index.js`) — The `/workshop/*` editor UI for managing structures, routes, templates, databases, and files.
2. **User routes** (dynamic, loaded from DB) — Caught by the `app.all("*")` handler at the bottom of `index.js`. At request time it matches the path against the `routes` in-memory array (rebuilt by `buildRoutes()`), finds the matching route record, and executes the user's `handler` JS string inside a sandboxed VM context.

`buildRoutes()` must be called after any route is created/updated to refresh the in-memory matcher array.

### Sandboxed execution (`bootstrapContext`)

User route handlers run in `vm.createContext()` with a restricted API:
- `require('eta')` — Eta template instance scoped to the structure
- `require('db')` — getter for named database instances. `require('db')(alias)` returns `{ library, sql }`: `sql` is the raw `better-sqlite3` instance for that db, and `library` is `module.exports` from that db's own "library" script (arbitrary JS, edited via `/workshop/:structure_id/db/:db_id/library`, run once per request with `sql`, `console`, and `fetch` bound in its own vm context — see `runLibrary` in `index.js`). Handlers typically call helper functions off `library` rather than writing raw SQL inline.
- `require('push')` — web-push library
- `require('files')` — `{ saveFile }` helper
- `console.log` — writes to the app's `logs` table (not stdout)
- `fetch`, `setTimeout`, `clearTimeout`
- `route(url)` — prefixes a URL with the structure's `route_prefix`

Handlers call `res.render(templateName, context)` or `ws.render(templateName, context)` to render Eta templates. These are injected onto `req`/`res` after the context is created (not available inside `bootstrapContext` itself).

WebSocket routes are bootstrapped once by `bootstrapWebsocketHandler` and stored in `wsRoutes`; subsequent saves only update the handler function without re-registering the ws path.

### Template rendering (`bootstrapTemplateWithHTMXetc`)

Every HTML response passes through this function, which uses Cheerio to inject HTMX, Tailwind, Hyperscript, and `bliss_inspector.js` into the `<head>`, and attaches `data-bliss-route` / `data-bliss-clone` / `data-bliss-copy` attributes to `<body>` (or to fragment children for HTMX partial swaps). These attributes drive the in-page editor overlay.

- `data-bliss-route` — link to the workshop editor page for whatever produced this element.
- `data-bliss-clone` — `hx-get` target for the clone-structure modal.
- `data-bliss-copy` — only set for GET routes, via `embedHTML(url)` (`index.js`): `<div hx-get="{url}" hx-trigger="load"></div>`. This is the actual page-nesting primitive — the inspector's 📋 button copies this snippet to the clipboard, and pasting it into any other template lazy-loads that route as a live child page via HTMX. This is how Structures compose: pages nesting pages nesting pages, each one an independently addressable, independently editable route.

### The inspector (`bliss_inspector.js`) and where it's headed

Currently the 🔍 overlay (injected into every rendered page, see above) only highlights `[data-bliss-route]` elements and offers links out to the editor, a copy-embed button, and a clone-structure modal — it does not let you edit anything in place yet.

The long-term goal is for the inspector to become a real-time, in-page structure editor: instead of jumping out to `/workshop/...`, you'd edit a nested page's route/template directly where it's embedded and see it update live. Two things that design needs and don't exist yet:
- Each embedded view needs to carry its **source** (which structure/route/template produced it) — `data-bliss-route` currently only gives a link out, not enough info to edit inline.
- Each embedded view needs to carry its **args** — the context/params it was rendered with (e.g. `res.render(template, context)`'s `context`, URL/query params) — so the in-place editor can show and modify what was actually passed in, not just the output.

Cross-fragment interaction (nested pages talking to each other) isn't a bespoke Bliss feature — it rides on standard HTMX/Hyperscript behavior since every nested page lives in the same DOM: `hx-swap-oob` for out-of-band updates (already used for head injection), and bubbling custom events (Hyperscript `send`/`trigger`, `hx-trigger="eventName from:body"`) for one nested page to notify siblings/ancestors.

### Database layer (`db.js`)

- Main app DB: `./dbs/0.sqlite` — stores structures, routes, templates, dbs metadata, files, logs.
- User databases: `./dbs/{id}.sqlite` — one SQLite file per user-created DB, opened on demand and cached via LRU (max 25 connections).
- Eta template instances are also LRU-cached per structure (max 100). The cache must be invalidated if template content changes — currently the cache is not explicitly invalidated on update, relying on the LRU eviction policy.
- Migrations in `migrations/` are applied sequentially on startup (tracked in a `migrations` table).

### Structure cloning

`cloneStructure` (in `db.js`) deep-copies a structure's routes, templates, scaffold pages, and optionally its databases (full copy vs. aliased reference). Aliased DBs share the same SQLite file across structures.

### Views vs. user templates

- `views/` — Eta templates for the workshop UI itself (not user content).
- User-created templates are stored as rows in the `templates` table and resolved at render time via `getTemplater()` / `readFile`.

### Scaffold pages

Non-GET routes (POST, PUT, DELETE, WS) get auto-generated scaffold pages — test forms or WebSocket test UIs — stored in `scaffold_pages`. These are served at `/workshop/:structure_id/route/:route_id/preview`.

### Frontend stack (workshop UI)

HTMX + Hyperscript + Tailwind (CDN, preflight disabled) + `bliss_inspector.js` (the in-page editor overlay). All served from `public/js/`.