@transclude/core 0.1.1 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Joe Dakroub
+Copyright (c) 2026 Atelier Dakroub
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,8 +4,8 @@ HTML is the product. A page is an `.html` file, the directory tree is the route
 table, and any fragment of a page is a URL of its own. Nothing has to run in the
 browser for the page to be correct.
 
-The same app runs on Node, Bun, Deno and workerd, and ships no client JavaScript
-by default.
+The same app runs on Node, Bun, Deno and workerd, the runtime behind
+Cloudflare Workers, and ships no client JavaScript by default.
 
 **[transclude.dev](https://transclude.dev)** has the documentation.
 
@@ -74,9 +74,10 @@ so a swap cannot drift from the page it replaces part of.
 
 - **No client-side router, and no swapper.** Every link is a document request
   unless you bring something that swaps. That is a decision, not a gap.
-- **No streaming.** The body is buffered so it can be hashed, which is what buys
-  the ETag. A `Link: rel=preload` goes out first, so a proxy can turn it into a
-  103 while the page is still being made.
+- **A page does not stream.** Its body is buffered so it can be hashed, which is
+  what buys the ETag. A `Link: rel=preload` goes out first, so a proxy can turn
+  it into a 103 while the page is still being made. An endpoint returns a
+  `Response` you build, so it can answer with a `ReadableStream` and stay open.
 - **No session store and no database opinion.** Signed cookies are the building
   block.
 - **No byte ranges on workerd.** A Range request gets 200 rather than 206.
@@ -96,26 +97,57 @@ so a swap cannot drift from the page it replaces part of.
 ```sh
 npm install
 npm test              # the framework's own, and they need no app
-npm run test:examples # the demo's, against a build
-npm run showcase      # the demo on http://localhost:1961
+npm run test:examples # the examples', against a build
+npm run showcase      # the showcase on http://localhost:1961
+npm run todomvc       # TodoMVC on http://localhost:1962
+npm run blog          # a prerendered blog on http://localhost:1963
+npm run search        # search over a fragment on http://localhost:1964
+npm run htmx          # the same, driven by htmx, on http://localhost:1965
+npm run includes      # transclusion on http://localhost:1966
+npm run auth          # a guarded section on http://localhost:1967
+npm run live          # server-sent events on http://localhost:1968
 npm run check:src     # type-check the framework itself
 ```
 
-`examples/showcase` is an app built against this package the same way any other
-project would be. It is where the browser checks live, because those need an app
-to run against, and it is what the four runtimes are checked with. `docs/` is the
-site at transclude.dev, and is itself built with the framework.
+`examples/` holds apps built against this package the same way any other project
+would be. `todomvc` is TodoMVC with forms and no client JavaScript, `blog` is a
+prerendered site with a sitemap and a feed, `search` swaps a fragment into a
+page that works without it, `htmx` does the same with htmx and the
+`HX-Target` header, `includes` shows transclusion from three sources,
+`auth` guards a section with a layout and a signed cookie, `live` pushes
+updates over server-sent events, and `showcase` uses every feature and is where the
+browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
+documentation under `/docs`, and itself built with the framework.
 
 ### Trying the CLI against this checkout
 
 ```sh
-npm link                                  # once, puts create-transclude on PATH
+cd create && npm link && cd ..            # once, puts create-transclude on PATH
 create-transclude my-app --template blank --link
 ```
 
 `--link` points the new project at this checkout rather than the registry, which
 is what you want while changing the framework: an edit here is an edit there.
 
+## Working with an AI agent
+
+`skills/transclude/` is an [Agent Skill](https://agentskills.io): the framework's
+conventions, its API and the mistakes it refuses, in the format Claude Code,
+Cursor, Copilot and others read. It ships with the package, so an installed
+project has it at `node_modules/@transclude/core/skills/transclude/`.
+
+Every HTML example in it is compiled by the real compiler in `npm test`. A skill
+is documentation an agent acts on without a human reading it first, so an
+example that stops compiling is worse than a missing one.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers the layout, the tests and the writing
+style. Everyone taking part agrees to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+Security problems go to admin@dakroub.co, not to a public issue.
+
 ## License
 
 MIT

package/bin/build.js

@@ -316,8 +316,20 @@ const publicSrc = config.publicDir
 const publicOut = path.join(dist, 'public');
 let publicFiles = 0;
 
+/**
+ * What an operating system leaves in a directory, which nobody put there.
+ *
+ * These were copied into the build and served: `/.DS_Store` answered 200 on the
+ * docs site and lists every file beside it. Dotfiles are not skipped wholesale,
+ * because `.well-known` is a directory people mean to publish.
+ */
+const JUNK = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
 if (publicSrc && fs.existsSync(publicSrc)) {
-  fs.cpSync(publicSrc, publicOut, { recursive: true });
+  fs.cpSync(publicSrc, publicOut, {
+    recursive: true,
+    filter: (from) => !JUNK.has(path.basename(from)),
+  });
   publicFiles = countFiles(publicOut);
 }
 

package/bin/release.js

@@ -85,15 +85,30 @@ function setVersion(version) {
 
 /** Everything, in the order that fails cheapest first. */
 function verify() {
+  // Read rather than listed, so an example added to the repository is covered by
+  // the next release without anyone remembering this file.
+  const examples = fs
+    .readdirSync(path.join(root, 'examples'), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, 'examples', entry.name, 'package.json')))
+    .map((entry) => entry.name)
+    .sort();
+
   const steps = [
     // `check:src` is not here. It exits non-zero on any diagnostic, and most of
     // what it reports is a pattern TypeScript cannot model rather than a defect.
     // The part that is a gate is a test, and `npm test` runs it.
     ['the framework', 'npm', ['test']],
-    ['the demo', 'npm', ['run', 'test:examples']],
-    ['the docs', 'npm', ['test', '--prefix', 'docs']],
-    ['the docs types', 'npm', ['run', 'check', '--prefix', 'docs']],
-    ['the docs build', 'npm', ['run', 'build', '--prefix', 'docs']],
+
+    // Built before tested, and that order is the gate rather than a nicety:
+    // every example's tests ask the built app for URLs and skip when there is
+    // nothing to ask. Without this a release could pass with all of them
+    // skipped, which is a green tick over nothing.
+    ...examples.map((name) => [`${name}, built`, 'npm', ['run', 'build', '--prefix', `examples/${name}`]]),
+    ['the examples', 'npm', ['run', 'test:examples']],
+
+    ['the docs types', 'npm', ['run', 'check', '--prefix', 'www']],
+    ['the docs build', 'npm', ['run', 'build', '--prefix', 'www']],
+    ['the docs', 'npm', ['test', '--prefix', 'www']],
   ];
 
   for (const [what, command, args] of steps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",
@@ -52,14 +52,22 @@
     "LICENSE",
     "bin",
     "editor",
+    "skills",
     "src"
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
-    "test:examples": "npm test --prefix examples/showcase",
-    "test:docs": "npm test --prefix docs",
+    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live",
+    "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
-    "docs": "npm run dev --prefix docs",
+    "todomvc": "npm run dev --prefix examples/todomvc",
+    "blog": "npm run dev --prefix examples/blog",
+    "search": "npm run dev --prefix examples/search",
+    "htmx": "npm run dev --prefix examples/htmx",
+    "includes": "npm run dev --prefix examples/includes",
+    "auth": "npm run dev --prefix examples/auth",
+    "live": "npm run dev --prefix examples/live",
+    "www": "npm run dev --prefix www",
     "check:src": "tsc -p tsconfig.src.json",
     "release": "node bin/release.js"
   },

package/skills/transclude/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: transclude
+description: Build web apps with the transclude framework (@transclude/core), an HTML-first server-side framework on Hono. Use when working in a project that has a transclude.config.js, when writing .html pages, layouts or custom elements under app/routes/ and app/elements/, or when the user mentions transclude, fragments, transclusion, hypermedia pages, or server-rendered HTML with no client bundle.
+license: MIT
+metadata:
+  homepage: https://transclude.dev
+  package: "@transclude/core"
+---
+
+# transclude
+
+HTML is the product. A page is an `.html` file, the server renders it, and what
+arrives is markup a browser already knows how to display. Nothing has to run in
+the browser for the page to be correct.
+
+The directory tree is the route table. The same app runs on Node, Bun, Deno and
+workerd.
+
+## Start a project
+
+```sh
+npm create @transclude my-app
+cd my-app
+npm install
+npm run dev
+```
+
+## Where files go
+
+```
+app/
+  routes/          # .html is a page, .js is an endpoint
+    index.html     # /
+    notes.html     # /notes
+    notes/[id].html    # /notes/:id
+    _layout.html   # wraps every route beside and below it
+    api/people.js  # /api/people
+    api/_shared.js # not a route, the _ prefix says so
+  elements/        # every custom element, one file each
+    note-card.html # <note-card>, the name needs a dash
+  public/          # copied to the site root as-is
+transclude.config.js
+```
+
+## A page
+
+```html
+<script server>
+  import { notes } from '../data/notes.js';
+
+  export default async ({ url }) => {
+    const q = new URL(url).searchParams.get('q') ?? '';
+    return { q, notes: notes.filter((n) => n.text.includes(q)) };
+  };
+</script>
+
+<title>Notes</title>
+
+<h1>Notes</h1>
+
+<div id="list" fragment>
+  <p if="!notes.length">Nothing yet.</p>
+  <ul else>
+    <li each="note of notes">${note.text}</li>
+  </ul>
+</div>
+```
+
+The `<script server>` default export is the loader. It runs on the server and
+returns the data the markup reads. Every name in `${…}` is a field of that data.
+
+### Directives
+
+| | |
+| --- | --- |
+| `${expr}` | interpolation, escaped |
+| `if="expr"` | render this element only when true |
+| `else` | pairs with the `if` above it |
+| `each="item of items"` | repeat the element |
+| `key="expr"` | identity for a repeated element |
+| `fragment` | this element has its own URL, see references/fragments.md |
+| `slot="name"` | fill a named slot |
+
+`html(value)` renders markup without escaping. It is a claim that the markup is
+yours. It sanitizes nothing.
+
+Globals available in an expression: `html`, `json`, `Math`, `JSON`, `String`,
+`Number`, `Boolean`, `Array`, `Object`, `Date`, `isNaN`, `parseInt`,
+`parseFloat`, `undefined`, `NaN`, `Infinity`. Every other name is data.
+
+### The loader context
+
+`ctx` carries `url`, `request`, `params`, `cookies`, `fragment`, `response` and
+`absolute()`. Returning a `Response` from a loader answers the request and skips
+the render, which is how a layout does a login redirect.
+
+## Forms and actions
+
+A page answers GET with its loader. Other verbs are named exports on the same
+file.
+
+```html
+<script server>
+  import { notes } from '../data/notes.js';
+
+  export default async () => ({ notes: notes.all() });
+
+  export const POST = async ({ request }) => {
+    const form = await request.formData();
+    notes.add(String(form.get('text')));
+  };
+</script>
+
+<form method="post">
+  <input name="text" required />
+  <button>Add</button>
+</form>
+
+<ul id="list" fragment>
+  <li each="note of notes">${note.text}</li>
+</ul>
+```
+
+The action runs, then the loader renders what it left behind. `POST`, `PUT`,
+`PATCH` and `DELETE` are the verbs. Return nothing to re-render, or return a
+`Response` to redirect.
+
+## Endpoints
+
+A `.js` file in `routes/` returns a `Response`.
+
+```js
+// app/routes/api/people.js
+import { people } from '../../data/people.js';
+
+export const GET = (ctx) => Response.json(people);
+
+export const POST = async ({ request }) => {
+  const body = await request.json();
+  people.push(body);
+  return Response.json(body, { status: 201 });
+};
+```
+
+## Layouts
+
+`_layout.html` wraps every route in its directory and below. The page renders
+into `<slot>`. Layouts nest, and each one loads its own data.
+
+```html
+<script server>
+  export default async () => ({ year: 2026 });
+</script>
+
+<header><a href="/">Home</a></header>
+<main><slot></slot></main>
+<footer>${year}</footer>
+```
+
+## Commands
+
+```sh
+npm run dev     # dev server, hot reload
+npm run build   # writes dist/, prerenders what it can
+npm start       # serves the build
+npm run check   # type-check every .html and .js route
+```
+
+## Traps
+
+These are the mistakes to avoid. Each one is a real compile error or a real
+bug, not a style preference.
+
+**`${…}` inside a nested `<script>` or `<style>` is a compile error.** Text
+there reaches the page as written, so a value would land in code. `json(value)`
+is the one way through, and only as the entire text of the script. For a style,
+pass the value through a custom property, which is an attribute and is escaped.
+
+**A literal `${` cannot be written in a template.** There is no escape. Pass any
+text containing it in from the loader as data.
+
+**Directive values are expressions, not interpolations.** Write
+`each="note of notes"`, never `each="${notes}"`.
+
+**A `fragment` element cannot carry `if`, `else` or `each`.** A fragment is one
+element with one id, so it cannot be conditional or repeated. Put the condition
+on something inside it.
+
+**A light element cannot `if` or `each` over a value that changes.** It writes
+into the DOM it already rendered and never replaces a child. That is a compile
+error naming `shadow`. Add `export const shadow = true` or keep the list still.
+
+**`setHTMLUnsafe()`, never `innerHTML`.** `innerHTML` does not process nested
+declarative shadow roots, so a child element becomes a dead `<template>`.
+
+**An element file name needs a dash.** `note-card.html` is a valid custom
+element name. `card.html` is not, and the file is dropped.
+
+**`<transclude>` has no self-closing form.** `<transclude src="#a" />` is read
+as an open tag and the rest of the page becomes its fallback content.
+
+**Reading a cookie makes a page personal.** It is then not cached and not
+prerendered. Writing one does not do this; reading one does.
+
+**`ctx.response` is shared by reference.** Set `ctx.status` and headers on it
+directly. It is the object the whole chain holds.
+
+**A `<template>`'s children are not `childNodes`.** They live on `.content`.
+
+## Going further
+
+- [references/elements.md](references/elements.md) — custom elements, light and
+  shadow, props, state, form association
+- [references/fragments.md](references/fragments.md) — fragments, includes and
+  transclusion
+- [references/server.md](references/server.md) — cookies, middleware, security,
+  config, deployment
+
+Full documentation: https://transclude.dev/docs

package/skills/transclude/references/elements.md

@@ -0,0 +1,206 @@
+# Elements
+
+An `.html` file in `app/elements/` becomes a custom element. The file name is
+the tag name and it needs a dash.
+
+## Light DOM, the default
+
+No shadow root, no boundary. Page CSS reaches it, `<label for>` works, and no
+JavaScript is shipped.
+
+```html
+<!-- app/elements/site-note.html -->
+<script properties>
+  export default {
+    tone: 'neutral',
+  };
+</script>
+
+<style>
+  :scope {
+    display: block;
+    border-left: 3px solid var(--rule);
+    padding: 0.5rem 0.9rem;
+  }
+  :scope[tone='warn'] {
+    border-color: #b4232c;
+  }
+</style>
+
+<p><slot>Nothing to say.</slot></p>
+```
+
+```html
+<site-note tone="warn">Rendered into the page's own DOM.</site-note>
+```
+
+`:scope` styles the element itself. Those rules are hoisted into `<head>` and
+lose to page CSS of equal specificity, so a page can override an element it did
+not write.
+
+## Shadow root, opt-in
+
+```html
+<!-- app/elements/user-card.html -->
+<script properties>
+  export default {
+    name: '',
+    tags: [],
+  };
+  export const shadow = true;
+</script>
+
+<style>
+  h3 {
+    margin: 0;
+  }
+</style>
+
+<h3>${name}</h3>
+<ul>
+  <li each="tag of tags">${tag}</li>
+</ul>
+<slot></slot>
+```
+
+Reach for a shadow root when the element has to seal its styles and DOM off from
+the page, or re-render on its own. Otherwise stay light: it is cheaper, and it
+renders the same way whether the browser asked for a whole page or one fragment.
+
+## Props
+
+`<script properties>` declares them, with defaults that set the type. An
+attribute is the value.
+
+```html
+<user-card name="Ada Lovelace" tags='["math", "engines"]'></user-card>
+```
+
+An object or an array serializes as JSON, so the browser reads the same data
+back off the element that the server had.
+
+`false`, `null` and `undefined` drop an attribute rather than writing
+`class="false"`. `true` writes the name bare.
+
+## State
+
+`<script state>` is data the element owns. Nothing observes it: assigning to it
+schedules the render, the way an attribute change does for a prop.
+
+```html
+<!-- app/elements/tally-box.html -->
+<script properties>
+  export default {
+    label: 'tally',
+  };
+</script>
+
+<script state>
+  export default {
+    n: 0,
+  };
+</script>
+
+<output>${n}</output>
+<span>${label}</span>
+
+<script>
+  export const prototype = {
+    bump(by = 1) {
+      this.n += by;
+    },
+  };
+
+  host.addEventListener('click', () => host.bump(), { signal });
+</script>
+```
+
+```html
+<tally-box label="clicks"></tally-box>
+<script type="module">
+  const box = document.querySelector('tally-box');
+  box.n = 10; // schedules a re-render
+  box.bump(); // 11
+  await box.updateComplete;
+</script>
+```
+
+## Behavior
+
+A plain `<script>` block is the element's own code. `host` is the element,
+`shadow` is its shadow root when it has one, `signal` is an `AbortSignal` that
+fires when the element disconnects, and `internals` is its `ElementInternals`.
+
+`export const prototype` puts members on the class prototype, shared by every
+instance. The rest of the block is per-element setup and runs once each.
+
+```js
+export const prototype = {
+  dismiss() {
+    this.hidden = true;
+    this.dispatchEvent(new CustomEvent('dismiss', { bubbles: true }));
+  },
+};
+```
+
+A prototype member cannot read `host`, `shadow`, `signal` or `internals`. Those
+are per-element, and reaching one from a shared member is a compile error.
+
+**Always pass `{ signal }` to a listener on `document`, `window` or
+`globalThis`.** One on `host` is collected with the element. One on `document`
+holds its closure forever, and every element after it adds another.
+
+```js
+document.addEventListener(
+  'keydown',
+  (event) => {
+    if (event.key === 'Escape') host.dismiss();
+  },
+  { signal },
+);
+```
+
+## Form association
+
+```html
+<!-- app/elements/tag-picker.html -->
+<script properties>
+  export default {
+    name: '',
+    value: '',
+  };
+  export const formAssociated = true;
+</script>
+
+<button type="button">${value || 'Pick tags'}</button>
+```
+
+```html
+<form method="post">
+  <input name="text" />
+  <tag-picker name="tags"></tag-picker>
+  <button type="submit">Add</button>
+</form>
+```
+
+The element is then a real form field: it submits, resets and validates with the
+rest of them.
+
+## Traps
+
+**A light element cannot `if` or `each` over a value that changes.** It does not
+own its children, so it writes into the DOM it already rendered rather than
+replacing it. That is a compile error naming `shadow`. A shadow element compiles
+the same `each` to a block with anchors and rebuilds it.
+
+**A shadow element in a fragment paints on connect.** A declarative shadow root
+is built when a browser parses a document, and nothing that swaps HTML parses
+one. A light element arrives whole.
+
+**An element with `<script state>` and no `<script>` still gets registered.**
+State is behavior. Without the definition, `el.n = 1` sets a value no node hears
+about.
+
+**`setHTMLUnsafe()`, never `innerHTML`,** when inserting markup that holds an
+element. `innerHTML` leaves a nested declarative shadow root as a dead
+`<template>`.

package/skills/transclude/references/fragments.md

@@ -0,0 +1,168 @@
+# Fragments and includes
+
+## Fragments
+
+A fragment is a part of a page that has its own URL. Give the element an `id`
+and a `fragment` attribute.
+
+```html
+<script server>
+  import { people } from '../data/people.js';
+
+  export default async ({ url }) => {
+    const q = new URL(url).searchParams.get('q') ?? '';
+    return { q, matches: people.filter((p) => p.name.includes(q)) };
+  };
+</script>
+
+<h1>People</h1>
+
+<input name="q" value="${q}" />
+
+<ul id="matches" fragment>
+  <li each="person of matches">${person.name}</li>
+</ul>
+```
+
+That page answers three URLs.
+
+| | |
+| --- | --- |
+| `GET /?q=ada` | the whole document |
+| `GET /?q=ada&fragment=matches` | the `<ul>` and nothing else |
+| `GET /?fragment=nope` | 404 |
+
+The `id` is the name. The page and the fragment come from one template, so the
+two always agree.
+
+### Asking for one
+
+A fragment is an ordinary URL. Anything that fetches HTML can use it.
+
+```js
+const res = await fetch('/?q=ada&fragment=matches');
+document.getElementById('matches').setHTMLUnsafe(await res.text());
+```
+
+**This framework ships nothing that swaps a fragment into a page.** htmx, Turbo,
+htmz or a short `fetch` does that. Do not look for a trigger attribute and do
+not invent one.
+
+htmx sends the target's id in an `HX-Target` header. Setting `fragmentHeader:
+'HX-Target'` in the config makes `?fragment=` optional. The query parameter is
+strict and an unknown name is a 404; a header naming an unknown fragment is
+ignored, because clients send it on every request.
+
+### Actions and fragments
+
+`POST /?fragment=nope` changes nothing and returns 404. The fragment is checked
+before the action runs. `ctx.fragment` tells a form submission from a fetch: the
+first wants a redirect, the second wants markup.
+
+### Styles for swapped-in markup
+
+A fragment can land on a page that never rendered the elements inside it. Set
+`watchElements: true` in the config and every page carries a small script that
+notices a new tag, loads its definition and adds its styles once. It is off by
+default.
+
+## Includes
+
+`<transclude src>` puts the same content in more than one place. It is resolved
+on the server and leaves no trace in the output.
+
+### Same page
+
+```html
+<div id="pricing" fragment>
+  <p>Two pounds.</p>
+</div>
+
+<aside>
+  <transclude src="#pricing"></transclude>
+</aside>
+```
+
+Renders as:
+
+```html
+<div id="pricing">
+  <p>Two pounds.</p>
+</div>
+
+<aside>
+  <div>
+    <p>Two pounds.</p>
+  </div>
+</aside>
+```
+
+The included copy drops the `id`. Two elements carrying one id is invalid, and a
+swap aimed at it would find the wrong one.
+
+### Another route
+
+```html
+<transclude src="/notes#notes">
+  <p>The notes could not be read.</p>
+</transclude>
+```
+
+The children are the fallback. The route is rendered in this process, not
+fetched over HTTP.
+
+### Another site
+
+Off unless a host is allowed. Default deny.
+
+```js
+export default {
+  proxy: {
+    allow: ['developer.mozilla.org', '*.docs.example'],
+  },
+};
+```
+
+```html
+<transclude src="https://developer.mozilla.org/en-US/docs/Web/HTML#reference">
+  <p>The reference could not be read just now.</p>
+</transclude>
+```
+
+This copies someone else's work onto your origin. Name a host only when you have
+the right to republish what it holds, and read its license: a share-alike
+license can put conditions on the page you put the fragment in. Nothing is
+attributed for you. Write the credit yourself.
+
+Tuning:
+
+```js
+proxy: {
+  allow: ['developer.mozilla.org'],
+  maxBytes: 5 * 1024 * 1024,
+  timeout: 10_000,
+  redirects: 5,
+  maxAge: 60_000,
+  sanitize: true,
+  styles: 'keep',
+}
+```
+
+`<base>`, `<link>` and `<style>` are stripped from foreign markup, because none
+of them stops at the fragment. `styles: 'strip'` drops `style` attributes too.
+
+## Traps
+
+**`<transclude>` has no self-closing form.** `<transclude src="#a" />` is read
+as an open tag. The children are the fallback, so the rest of the page becomes
+them, silently, and the include still works.
+
+**An interpolated `src` is a compile error.** `src="/docs/${slug}#intro"` cannot
+be resolved, because the set of includes has to be known before the render that
+would produce the value.
+
+**A page including itself is refused,** and so is a chain that comes back
+around.
+
+**A route include shares the host page's cookies.** That is deliberate: it makes
+the host page personal too, so one visitor's render is never served to the next.

package/skills/transclude/references/server.md

@@ -0,0 +1,155 @@
+# The server
+
+The server is [Hono](https://hono.dev). An app adds its own middleware in
+`app/server.js`.
+
+```js
+// app/server.js
+export default (app) => {
+  app.use('*', async (c, next) => {
+    await next();
+    c.res.headers.set('X-Served-By', 'transclude');
+  });
+};
+```
+
+It runs before anything that serves bytes, so a guard there covers prerendered
+pages and public files.
+
+## Cookies
+
+`ctx.cookies` reads and writes.
+
+```js
+export default async ({ cookies }) => {
+  const theme = cookies.get('theme') ?? 'light';
+  return { theme };
+};
+
+export const POST = async ({ cookies, request }) => {
+  const form = await request.formData();
+  cookies.set('theme', String(form.get('theme')), { maxAge: 31536000 });
+  return Response.redirect('/', 303);
+};
+```
+
+`cookies.signed.get` and `cookies.signed.set` need `cookieSecret` in the config.
+A signed cookie can be read by the client and not forged, which is what a
+session needs. Without a secret, `cookies.signed` throws.
+
+`Secure` follows the connection, so `http://localhost` works in dev and a
+proxied TLS connection still gets it.
+
+**Reading a cookie makes a page personal.** It is then not cached and not
+prerendered. Writing one does not.
+
+## Security
+
+CSRF is on by default. A Content-Security-Policy is not:
+
+```js
+export default {
+  csp: true,
+};
+```
+
+Each page gets a policy built from the hashes of what that page inlines. There
+is nothing to stamp and no nonce to thread through.
+
+Every `${…}` is escaped. `html(value)` turns that off for one value and
+sanitizes nothing, so never wrap anything a visitor typed.
+
+`frame-ancestors`, `report-uri`, `report-to` and `sandbox` are ignored in a
+`<meta>` tag, so they ride in a response header. A static host serves the meta
+half and not the header.
+
+## Types
+
+```sh
+npm run check
+```
+
+Runs TypeScript over every `.html` and `.js` route. With no annotations it
+catches a misspelled field in a template, an unknown prop on an element, and a
+prop given the wrong type. `strict: true` in the config turns on full
+strictness.
+
+Source is JavaScript with JSDoc. Do not convert it to TypeScript.
+
+## Configuration
+
+`transclude.config.js` at the project root. An unknown key throws.
+
+| Key | Default | What it does |
+| --- | --- | --- |
+| `appDir` | `'app'` | Where the app lives, relative to the project root. |
+| `routesDir` | `'routes'` | Pages and endpoints. Relative to `appDir`. |
+| `elementsDir` | `'elements'` | Custom elements. Relative to `appDir`. |
+| `publicDir` | `'public'` | Copied to the site root as-is. Relative to `appDir`. |
+| `outDir` | `'dist'` | Where the build writes. |
+| `stylesheet` | — | One global stylesheet, relative to the project root. |
+| `port` | `1960` | Dev and production both listen here. `PORT` wins. |
+| `lang` | `'en'` | The `lang` on `<html>`. |
+| `strict` | `false` | Full TypeScript strictness. |
+| `csrf` | `true` | `false` to turn it off, or an object for `hono/csrf`. |
+| `csp` | `false` | `true`, or `{ directives, reportOnly }`. |
+| `cookieSecret` | `null` | Signs cookies. |
+| `fragmentParam` | `'fragment'` | The query parameter that asks for a fragment. |
+| `fragmentHeader` | `null` | A request header that may name one. Adds it to `Vary`. |
+| `watchElements` | `false` | Defines and styles an element arriving in a swap. |
+| `trailingSlash` | `'never'` | `'never'` redirects. `'ignore'` serves both. |
+| `metadataBase` | — | The origin `ctx.absolute()` resolves against. |
+| `sitemap` | `false` | `{ hostname }` mounts `/sitemap.xml`. |
+| `feed` | `false` | `{ hostname, title, items }` mounts a feed. |
+| `proxy` | `false` | `{ allow: [...] }` for cross-site includes. |
+| `precache` | `false` | `true` writes `/precache.json`. |
+| `onError` | `null` | `(error, { request, url, method })` per failed request. |
+
+## The build
+
+```sh
+npm run build
+```
+
+Writes `dist/`. Every route with no per-request state is rendered to a file. Add
+this to a page that has to run for each request:
+
+```js
+export const prerender = false;
+```
+
+`prerender` is read off the page, never off its layouts. A layout that reads a
+cookie makes every page under it request-dependent, and nothing says so.
+
+## Runtimes
+
+The same app runs on Node, Bun, Deno and workerd. `bin/serve.js`,
+`bin/serve.bun.js` and `bin/serve.deno.js` only listen.
+
+**workerd refuses to compile WebAssembly at runtime.** A loader that reaches
+something built on Wasm fails there and nowhere else. A prerendered page never
+runs its loader in production, so this stays hidden until something asks for a
+fragment.
+
+## Testing
+
+The app is a function from a request to a response.
+
+```js
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { app } from '@transclude/core/production';
+
+test('the notes page lists notes', async () => {
+  const res = await app.request('http://localhost/notes');
+  assert.equal(res.status, 200);
+  assert.match(await res.text(), /<li/);
+});
+```
+
+`app` is a named export, and the URL has to be absolute. A relative one skips
+the origin checks a real request goes through.
+
+Nothing is stubbed. `node --test` does not read `.env` the way `npm start`
+does, so add `--env-file-if-exists=.env` to the test script when the config
+reads a secret.

package/src/compiler/codegen.js

@@ -44,6 +44,28 @@ export class CompileError extends Error {
  * @param {object} [opts]
  * @returns {object} the render body, the regions, the slots, the includes and the warnings
  */
+/**
+ * An attribute name is emitted exactly as written, so `${…}` in one reaches the
+ * page as those characters rather than as a value. Nothing downstream reads it,
+ * which made this the one interpolation mistake that rendered instead of
+ * failing. A spread parses as an attribute name too, and is caught here.
+ *
+ * @param {object} el
+ * @throws {CompileError} when a name holds an interpolation
+ */
+function assertStaticAttrNames(el) {
+  for (const attr of el.attrs ?? []) {
+    if (!attr.name.includes('${')) continue;
+
+    throw new CompileError(
+      `<${el.tagName}> interpolates an attribute name: "${attr.name}". ` +
+        `Only a value takes \${…}, so write the name out. To choose between two, ` +
+        `put the condition in the value: class="\${cond ? 'a' : 'b'}".`,
+      el,
+    );
+  }
+}
+
 export function compileFragment(nodes, opts = {}) {
   const gen = new Codegen(opts);
   gen.emitChildren(nodes, gen.body, gen.rootScope, true);
@@ -553,6 +575,7 @@ class Codegen {
   }
 
   emitElement(el, out, scope, topLevel) {
+    assertStaticAttrNames(el);
     const tag = el.tagName;
 
     // In a layout, <slot> is where the child's content goes. In a component it
@@ -832,6 +855,8 @@ class Codegen {
    * taking the first, which is the outermost. `renderDocument` serializes.
    */
   htmlAttrsJs(el, scope) {
+    // <html> is read by a second parse, so it never reaches emitElement.
+    assertStaticAttrNames(el);
     const pairs = el.attrs
       .filter((attr) => !DIRECTIVES.has(attr.name))
       .map((attr) => {

package/src/compiler/index.js

@@ -15,7 +15,13 @@ import {
 
 export { CompileError, ScriptError };
 
-const PAGE_EXPORTS = new Set(['css', 'load', 'render', 'renderHead', 'renderTitle', 'renderHtmlAttrs', 'layouts', 'client', 'elements', 'headScript']);
+// Everything the generated page and layout modules define at the top level. A
+// block naming one of these is checked whether it exports it or merely declares
+// it, because both land in the same scope.
+const PAGE_EXPORTS = new Set([
+  'css', 'load', 'render', 'renderHead', 'renderTitle', 'renderHtmlAttrs',
+  'layouts', 'client', 'elements', 'headScript', 'hasTitle', 'includes',
+]);
 const COMPONENT_EXPORTS = new Set([
   'tag', 'light', 'css', 'elements', 'propDefs', 'propAttrs', 'stateDefs', 'members', 'render',
   'coerce', 'def', 'init', 'define', 'default', 'bind', 'update', 'volatile', 'formAssociated',
@@ -141,6 +147,12 @@ export function splitBlocks(source) {
       // before first paint, or a `pagereveal` listener, which fires too early for
       // any script in the body to see.
       else if (attrs.has('head')) out.head.push({ ...block, attrs: node.attrs ?? [] });
+      // A `src` means there is no code here to compile, so this is markup: an
+      // ordinary external script the page wants in its body. Read as a client
+      // block it became an empty one and the tag was dropped, `src` and all,
+      // with nothing said. A nested `<script src>` was always markup; only a
+      // top-level one went missing.
+      else if (attrs.has('src')) out.nodes.push(node);
       else out.client.push(block);
       continue;
     }
@@ -375,8 +387,9 @@ export function compilePage(
 
   const server = blocks.server
     ? bindDefaultExport(blocks.server, '__load', where)
-    : { code: 'const __load = null;', exports: [], imports: [], defaultNode: null };
+    : { code: 'const __load = null;', exports: [], imports: [], declared: [], defaultNode: null };
   assertNoCollisions(server.exports, PAGE_EXPORTS, where);
+  assertNoCollisions(server.declared ?? [], PAGE_EXPORTS, where, 'declares');
   assertNoActionsObject(server.exports, where);
 
   const template = compileFragment(blocks.nodes, { components, shadowTags, page: true, html: blocks.html });
@@ -485,8 +498,9 @@ export function compileLayout(source, { id, components = new Map(), shadowTags =
 
   const server = blocks.server
     ? bindDefaultExport(blocks.server, '__load', where)
-    : { code: 'const __load = null;', exports: [], imports: [], defaultNode: null };
+    : { code: 'const __load = null;', exports: [], imports: [], declared: [], defaultNode: null };
   assertNoCollisions(server.exports, PAGE_EXPORTS, where);
+  assertNoCollisions(server.declared ?? [], PAGE_EXPORTS, where, 'declares');
   assertNoActionsObject(server.exports, where);
 
   const template = compileFragment(blocks.nodes, {

package/src/compiler/script.js

@@ -34,7 +34,7 @@ const PARSE_OPTIONS = {
  * @param {{ flags?: string[] }} [options]
  * @returns {{ code: string, exports: string[],
  *   imports: Array<{ source: string, specifiers: string }>,
- *   defaultNode: object|null, flags: object }}
+ *   declared: string[], defaultNode: object|null, flags: object }}
  */
 export function bindDefaultExport(block, name, label, { flags = [] } = {}) {
   const { code: source, line = 1 } = block;
@@ -56,9 +56,10 @@ export function bindDefaultExport(block, name, label, { flags = [] } = {}) {
   const node = ast.body.find((s) => s.type === 'ExportDefaultDeclaration') ?? null;
   const exports = namedExportsOf(ast, source, line, label).filter((n) => !flags.includes(n));
   const imports = importsOf(ast);
+  const declared = topLevelNames(ast);
 
   if (!node) {
-    return { code: `${code}\nconst ${name} = null;`, exports, imports, defaultNode: null, flags: found };
+    return { code: `${code}\nconst ${name} = null;`, exports, imports, declared, defaultNode: null, flags: found };
   }
 
   // Slicing the *declaration* rather than the statement means
@@ -71,7 +72,7 @@ export function bindDefaultExport(block, name, label, { flags = [] } = {}) {
     ';' +
     code.slice(node.end);
 
-  return { code: rewritten, exports, imports, defaultNode: node.declaration, flags: found };
+  return { code: rewritten, exports, imports, declared, defaultNode: node.declaration, flags: found };
 }
 
 /**
@@ -506,19 +507,20 @@ function importsOf(ast) {
 }
 
 /**
- * Guards against a block exporting a name the generated module already uses.
+ * Guards against a block using a name the generated module already defines.
  *
- * @param {string[]} exports
+ * @param {string[]} names
  * @param {Set<string>} reserved
  * @param {string} label
+ * @param {string} [verb] how the block used it, for the message
  * @returns {void}
  * @throws naming the first collision
  */
-export function assertNoCollisions(exports, reserved, label) {
-  for (const name of exports) {
+export function assertNoCollisions(names, reserved, label, verb = 'exports') {
+  for (const name of names) {
     if (reserved.has(name)) {
       throw new ScriptError(
-        `${label}: exports "${name}", which the generated module already defines. ` +
+        `${label}: ${verb} "${name}", which the generated module already defines. ` +
           `Reserved: ${[...reserved].join(', ')}.`,
       );
     }
@@ -586,6 +588,26 @@ function namedExportsOf(ast, code, lineOffset, label) {
   return names;
 }
 
+/**
+ * Every name a block binds at the top level, imports included.
+ *
+ * The generated module puts this block's code beside its own `export const`
+ * statements, so any of these can collide, not only the exported ones. An
+ * import was the case that got through: `import { elements } from './x.js'`
+ * binds `elements` and exports nothing, so the export check never saw it and
+ * the build failed inside rolldown, pointing at a virtual module.
+ *
+ * @param {object} ast
+ * @returns {string[]}
+ */
+function topLevelNames(ast) {
+  return ast.body.flatMap((statement) =>
+    statement.type === 'ImportDeclaration'
+      ? statement.specifiers.map((spec) => spec.local.name)
+      : declaredNames(statement),
+  );
+}
+
 function patternNames(node) {
   switch (node.type) {
     case 'Identifier':

package/src/compiler/shim.js

@@ -2,7 +2,7 @@
 // check it.
 //
 // JavaScript rather than TypeScript, on purpose. A JSDoc `@type` in the
-// author's own `<script props>` is honoured in a .js file and silently ignored
+// author's own `<script props>` is honored in a .js file and silently ignored
 // in a .ts one. The job is to check what the author wrote, so the shim speaks the
 // same language they do. The scaffolding uses JSDoc too.
 //
@@ -187,7 +187,7 @@ export function buildEndpointShim(source, { contextType }) {
     // Anything not spelled like a method is a helper and gets no signature.
     if (declared?.type === 'VariableDeclaration') {
       const name = declared.declarations[0]?.id?.name;
-      // `@satisfies` on the initialiser: it contextually types the handler's own
+      // `@satisfies` on the initializer: it contextually types the handler's own
       // `ctx` *and* holds the return type, which an annotation would flatten.
       if (isVerb(name)) edits.push({ at: node.start, insert: `/** @satisfies {${signature}} */\n` });
       continue;
@@ -465,10 +465,16 @@ function emitModule(block, out, contextType, name = '__Data', binding = '__defau
     return;
   }
 
+  // A loader answering with a Response answers the request, and the template
+  // never renders. So the data a template reads is the loader's return with
+  // Response taken out of it. Without this, the documented way to write a login
+  // guard, `return Response.redirect(...)` from a layout, makes every name in
+  // that layout's own markup an error about a union it can never see.
+  // `ctx.action` has excluded Response since it was written, for the same reason.
   out.add(
     contextType
-      ? `/** @typedef {__Shape<Awaited<ReturnType<typeof ${binding}>>>} ${name} */\n\n`
-      : `/** @typedef {__Shape<typeof ${binding}>} ${name} */\n\n`,
+      ? `/** @typedef {__Shape<Exclude<Awaited<ReturnType<typeof ${binding}>>, Response>>} ${name} */\n\n`
+      : `/** @typedef {__Shape<Exclude<typeof ${binding}, Response>>} ${name} */\n\n`,
   );
 }
 

package/src/negotiate.js

@@ -1,7 +1,7 @@
 /**
  * Picks a content encoding from an Accept-Encoding header.
  *
- * Getting this wrong is not a missed optimisation, it is a corrupt response: a
+ * Getting this wrong is not a missed optimization, it is a corrupt response: a
  * client that did not ask for brotli must never be handed brotli. So the rules
  * are followed properly: q-values, `*`, and `q=0` as a refusal.
  *

package/src/project.js

@@ -69,6 +69,34 @@ export function findRoot(from = process.cwd()) {
   );
 }
 
+/**
+ * What a config means when it says nothing.
+ *
+ * These were documented as defaults and were not applied anywhere: `loadProject`
+ * handed the object back as written, so a config that left `outDir` out reached
+ * `path.join(root, undefined)` and threw `ERR_INVALID_ARG_TYPE`, which names
+ * neither the key nor the file. The starter templates set every one of them,
+ * which is why nothing caught it.
+ *
+ * `port` is not here. `portOf` already answers it, and it reads the environment
+ * first, which a plain default cannot do.
+ */
+const DEFAULTS = {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  publicDir: 'public',
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+  stylesheet: null,
+  lang: 'en',
+  fragmentParam: 'fragment',
+  trailingSlash: 'never',
+  strict: false,
+  csrf: true,
+  csp: false,
+};
+
 /**
  * The root and its config together, because nothing needs one without the other.
  *
@@ -87,7 +115,7 @@ export async function loadProject(from = process.cwd()) {
     throw new Error(`[transclude] ${CONFIG_FILE} must export a config object as its default`);
   }
   assertNoSplitDirs(config, file);
-  return { root, config, configFile: file };
+  return { root, config: { ...DEFAULTS, ...config }, configFile: file };
 }
 
 /**

package/src/routes.js

@@ -145,7 +145,7 @@ function idOf(parts) {
 }
 
 // Static beats dynamic, dynamic beats catch-all, and among equals the longer
-// path wins. Registration order then makes Hono's behaviour deterministic
+// path wins. Registration order then makes Hono's behavior deterministic
 // rather than something to reason about per-router.
 function bySpecificity(a, b) {
   if (a.hasRest !== b.hasRest) return a.hasRest ? 1 : -1;

package/src/runtime/index.js

@@ -940,7 +940,7 @@ export function watch(loaders, root = globalThis.document) {
  */
 /**
  * A light element has no shadow root to repaint, and repainting would destroy
- * the children the page put inside it. So it upgrades for behaviour only: the
+ * the children the page put inside it. So it upgrades for behavior only: the
  * markup it was served is the markup it keeps.
  *
  * @param {object} def
@@ -949,17 +949,17 @@ export function watch(loaders, root = globalThis.document) {
  */
 export function defineLight(def, init) {
   // Before every other exit below: styles are the half of this that an element
-  // with no behaviour still has, and the half a swapped-in one arrives without.
+  // with no behavior still has, and the half a swapped-in one arrives without.
   adoptStyles(def);
 
   if (typeof customElements === 'undefined') return;
   if (customElements.get(def.tag)) return;
-  // No behaviour to attach means nothing to register. A light element with no
+  // No behavior to attach means nothing to register. A light element with no
   // <script> is markup that was already rendered, and it ships no JavaScript at
   // all, accessors included. That is the trade the
   // zero-JS default makes.
   //
-  // Being a form control counts as behaviour: a shadow root is not required to be
+  // Being a form control counts as behavior: a shadow root is not required to be
   // one, and an element that submits a value has to exist to do it.
   if (!init && !hasMembers(def) && !def.formAssociated && !hasState(def)) return;
 
@@ -1253,7 +1253,7 @@ export function defineComponent(def, init) {
         this.#adopt();
       }
       // Runs on every connect, not just the first: moving an element in the DOM
-      // disconnects and reconnects it, and behaviour that was torn down on the
+      // disconnects and reconnects it, and behavior that was torn down on the
       // way out has to come back on the way in.
       this.#ready = true;
       this.#abort = new AbortController();

package/src/server.js

@@ -1,7 +1,7 @@
 // The Hono app both servers start from.
 //
 // One function rather than two `new Hono()` calls, because the order things are
-// registered in *is* the behaviour: a guard registered after the static handler
+// registered in *is* the behavior: a guard registered after the static handler
 // does not guard a prerendered page. Two copies of that order is two servers
 // that disagree, which has happened twice in this codebase already.
 
@@ -83,7 +83,7 @@ export function baseApp(options = {}) {
   if (csrfOption) app.use('*', csrf(csrfOption === true ? undefined : csrfOption));
 
   /**
-   * The one security header with no judgement in it.
+   * The one security header with no judgment in it.
    *
    * Without it a browser may sniff a response's bytes and decide the declared
    * type was wrong, so a text file an app serves can be read as HTML and a

package/src/static-cache.js

@@ -41,7 +41,7 @@ const TYPES = {
  * @property {number} onDisk left on disk because the budget ran out
  * @property {number} encoded how many have a precompressed variant
  * @property {Map<string, Entry|{ file: string }>} entries for the build, which
- *   serialises these for a runtime with no filesystem
+ *   serializes these for a runtime with no filesystem
  * @property {(pathname: string) => Entry|null} get
  */
 
@@ -94,7 +94,7 @@ function load(dir, urlFor, { maxBytes = DEFAULT_MAX_BYTES } = {}) {
     count: entries.size,
     bytes,
     onDisk,
-    /** For the build, which serialises these for runtimes with no filesystem. */
+    /** For the build, which serializes these for runtimes with no filesystem. */
     entries,
     encoded: [...entries.values()].filter((e) => e.encodings?.size).length,
 

package/src/typecheck.js

@@ -6,7 +6,7 @@
 // and rewriting is where source mapping breaks down.
 //
 // JavaScript rather than TypeScript because a JSDoc `@type` in the author's own
-// `<script props>` is honoured in a .js file and silently ignored in a .ts one.
+// `<script props>` is honored in a .js file and silently ignored in a .ts one.
 //
 // Shims are self-contained: route contexts and component props are inlined as
 // type literals rather than imported. transclude-env.d.ts is written *from* the shims,