@transclude/core 0.11.1 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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",
@@ -57,7 +57,7 @@
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
-    "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 && npm test --prefix examples/elements && npm test --prefix examples/markdown",
+    "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 && npm test --prefix examples/elements && npm test --prefix examples/markdown && npm test --prefix examples/atlas",
     "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
     "todomvc": "npm run dev --prefix examples/todomvc",
@@ -69,6 +69,7 @@
     "live": "npm run dev --prefix examples/live",
     "elements": "npm run dev --prefix examples/elements",
     "markdown": "npm run dev --prefix examples/markdown",
+    "atlas": "npm run dev --prefix examples/atlas",
     "www": "npm run dev --prefix www",
     "check:src": "tsc -p tsconfig.src.json",
     "release": "node bin/release.js"

package/skills/transclude/SKILL.md

@@ -277,6 +277,14 @@ 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.
 
+**`app.get()` in `app/server.js` is not how a route is made.** The `app` there
+is a real Hono instance and accepts one, but the directory tree is the route
+table, and a handler registered by hand is invisible to the build, the sitemap
+and `npm run check`. Middleware is what belongs in that file. Most of Hono's
+API has an answer here already, and
+[references/server.md](references/server.md) has the line between the two next
+to Hono's own documentation for agents.
+
 **Middleware does not run during the build.** A page gated only by
 `app/server.js` is prerendered to a file and served by any static host. Declare
 the paths so the build knows:
@@ -305,6 +313,6 @@ directly. It is the object the whole chain holds.
 - [references/fragments.md](references/fragments.md) — fragments, includes and
   transclusion
 - [references/server.md](references/server.md) — cookies, middleware, security,
-  config, deployment
+  config, caching, deployment, and where Hono's own docs are
 
 Full documentation: https://transclude.dev/docs

package/skills/transclude/references/server.md

@@ -16,6 +16,57 @@ export default (app) => {
 It runs before anything that serves bytes, so a guard there covers prerendered
 pages and public files.
 
+## Hono's documentation
+
+Hono publishes its documentation in a form an agent can read. Fetch it rather
+than recall it. The dependency is `hono@^4`, and it moves.
+
+| URL | Size | What it holds |
+| --- | --- | --- |
+| `https://hono.dev/llms.txt` | 6 KB | An index. Every page, one line each. |
+| `https://hono.dev/llms-small.txt` | 190 KB | The core: routing, the `Context`, middleware, the helpers. |
+| `https://hono.dev/llms-full.txt` | 360 KB | All of it, a page per built-in middleware. |
+
+Read `llms.txt` and follow the one link the question needs. The other two are
+whole manuals, and a question about `cors` does not need one.
+
+### What this framework already answers
+
+Most of Hono's surface has an answer here, and reaching past it is the common
+mistake. A route registered by hand answers requests. The build, the sitemap
+and `npm run check` never see it.
+
+| In Hono | Here |
+| --- | --- |
+| `app.get('/notes', …)` | `app/routes/notes.html` |
+| `c.req.param('id')` | `params.id` in the loader |
+| `c.req.query('q')` | `new URL(url).searchParams` |
+| `c.req.formData()` | `request.formData()` in a verb export |
+| `getCookie(c, 'theme')` | `ctx.cookies` |
+| `csrf()` | on by default, `csrf` in the config |
+| `secureHeaders()` for a policy | `csp` in the config |
+| `trimTrailingSlash()` | `trailingSlash` in the config |
+| `compress()`, `etag()` | both are built in, per response and at rest |
+| `cache()` | `export const revalidate` |
+| `serveStatic()` | `app/public/` |
+| `c.executionCtx.waitUntil(p)` | `ctx.after(p)` |
+| `c.html()`, `hono/html`, `hono/jsx` | a page is an `.html` file |
+| `hono/ssg` | `npm run build` |
+
+Hono's `Context` reaches an app in one place, the middleware in `app/server.js`.
+A loader, an action and an endpoint are handed `ctx`, which belongs to this
+framework and carries no `c`. Reading a form should not cost an author a
+router's API.
+
+### What is still Hono's
+
+`app` in `app/server.js` is a real Hono instance, so its built-in middleware
+works unchanged: `cors`, `basicAuth`, `bearerAuth`, `logger`, `bodyLimit`,
+`ipRestriction`, `requestId`, `timeout`, `timing`. So do the helpers `accepts`,
+`conninfo` and `streaming`.
+
+`app.request()` in a test is Hono's too. See [Testing](#testing).
+
 ## Cookies
 
 `ctx.cookies` reads and writes.
@@ -104,6 +155,7 @@ Source is JavaScript with JSDoc. Do not convert it to TypeScript.
 | `sitemap` | `false` | `{ hostname }` mounts `/sitemap.xml`. |
 | `feed` | `false` | `{ hostname, title, items }` mounts a feed. |
 | `proxy` | `false` | `{ allow: [...] }` for cross-site includes. |
+| `cache` | — | Where a page held by `revalidate` is kept. A bounded map in this process by default. |
 | `precache` | `false` | `true` writes `/precache.json`. |
 | `onError` | `null` | `(error, { request, url, method })` per failed request. |
 
@@ -149,6 +201,81 @@ skipped. Deployed, the URL is a 404. Publishing is deleting the line.
 `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.
 
+## Holding a render
+
+Between a file written once and a render on every request, there is a page held
+for a while.
+
+```js
+// app/routes/notes.html
+export const prerender = false;
+export const revalidate = 3600;
+```
+
+The number is seconds. Inside that window a request is answered from the store
+and the loader does not run. Past it the held page goes out immediately and a
+fresh one renders behind the response, so nobody waits for a re-render. One
+render happens at a time per URL, however many requests arrive together.
+
+The key is the path and the query, because a page reading `?q=` renders
+differently for each one. A rebuild that throws leaves the held page where it is,
+and the error goes to `onError` with the request that started it.
+
+Three things hold nothing:
+
+- **`npm run dev`.** The dev server renders every request and keeps nothing
+  between them. A window has no effect there at all.
+- **A page the build wrote to a file.** The static handler answers before the
+  route handler that holds anything, so the window never runs. Adding
+  `prerender = false` puts the page back on the path that has one, which is why
+  the example above carries both lines.
+- **A fragment.** `?fragment=list` is rendered on demand, for every route,
+  prerendered or not.
+
+**What is never held:** a page that read a cookie, set a header, answered with a
+`Response`, or has a status outside 2xx. A shared store holding any of those
+hands one visitor's page, or one visitor's `Set-Cookie`, to the next. It is the
+same rule the build uses to decide a route can be a file.
+
+### Tags
+
+Seconds say when a page may be out of date. A tag says when it is.
+
+```js
+// app/routes/notes.html
+export const prerender = false;
+export const revalidate = { seconds: 3600, tags: ['notes'] };
+
+export default async () => ({ notes: await notes.all() });
+```
+
+```js
+// app/routes/api/notes.js
+export const POST = async ({ request, revalidateTag }) => {
+  await notes.add(await request.json());
+
+  // Every held page carrying this tag is dropped. The next request for one
+  // renders it again.
+  revalidateTag('notes');
+
+  return new Response(null, { status: 204 });
+};
+```
+
+`ctx.revalidateTag` belongs where the change was written, which is an action or
+an endpoint: whatever made the change is what says it happened. A prerendered
+page's loader calling it stops the build, since a build holds nothing yet to
+drop.
+
+`revalidate` takes a number of seconds, or `{ seconds, tags }`. Anything else
+throws when the app starts. `revalidate: '1h'` would otherwise hold forever or
+not at all, and say nothing either way.
+
+The default store is a bounded map in this process. That is right for one server
+and wrong for several: each holds its own copy, and `revalidateTag` reaches one
+of them. `cache` in the config takes anything with the same `get`, `set`,
+`delete` and `deleteByTag`.
+
 ## Runtimes
 
 The same app runs on Node, Bun, Deno and workerd. `bin/serve.js`,