npm - jskelet - Versions diffs - 0.6.3 → 0.6.4 - Mend

jskelet 0.6.3 → 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (153) hide show

package/AGENTS.md +136 -136
package/CHANGELOG.md +628 -620
package/LICENSE +21 -21
package/README.md +2 -0
package/bin/jskelet.mjs +130 -130
package/docs/01-baslangic.md +291 -291
package/docs/02-mimari.md +310 -310
package/docs/03-routing.md +515 -515
package/docs/04-render-ve-sablonlar.md +667 -661
package/docs/05-islands.md +486 -486
package/docs/06-cache.md +1467 -1443
package/docs/07-yapilandirma.md +1208 -1197
package/docs/08-build.md +429 -429
package/docs/09-dev-araclari.md +364 -364
package/docs/10-dagitim.md +348 -338
package/docs/12-panel-ve-oturum.md +479 -478
package/docs/README.md +83 -83
package/docs/en/01-getting-started.md +298 -298
package/docs/en/02-architecture.md +329 -329
package/docs/en/03-routing.md +531 -531
package/docs/en/04-rendering.md +675 -669
package/docs/en/05-islands.md +497 -497
package/docs/en/06-caching.md +1476 -1453
package/docs/en/07-configuration.md +1229 -1219
package/docs/en/08-build.md +447 -447
package/docs/en/09-dev-tools.md +373 -373
package/docs/en/10-deployment.md +351 -340
package/docs/en/11-migration.md +398 -398
package/docs/en/12-dashboards-and-sessions.md +489 -488
package/docs/en/README.md +87 -87
package/package.json +137 -137
package/src/build/ensure-build.mjs +19 -19
package/src/build/paths.mjs +153 -153
package/src/build/resolve-peer.mjs +36 -36
package/src/build/tasks/client.mjs +349 -349
package/src/build/tasks/css.mjs +235 -235
package/src/build/tasks/fonts.mjs +146 -146
package/src/build/tasks/icons.mjs +357 -357
package/src/build/tasks/images.mjs +244 -244
package/src/build/tasks/precompress.mjs +78 -78
package/src/build/tasks/templates.mjs +20 -20
package/src/client/admin/i18n.js +764 -764
package/src/client/admin/login.html +74 -74
package/src/client/admin/panel.css +809 -809
package/src/client/admin/panel.html +495 -495
package/src/client/admin/panel.js +1251 -1251
package/src/client/devtools/report.html +185 -185
package/src/client/devtools/report.js +745 -745
package/src/client/devtools/seo.js +628 -628
package/src/client/dom.js +95 -95
package/src/client/form.js +192 -192
package/src/client/index.js +45 -45
package/src/client/registry.js +305 -305
package/src/client/safe-image.js +91 -91
package/src/client/shared-cookie.js +225 -225
package/src/client/store.js +36 -36
package/src/client/swap.js +188 -188
package/src/compile/codegen.js +336 -336
package/src/compile/compile-all.js +149 -149
package/src/compile/errors.js +66 -66
package/src/compile/expr.js +409 -409
package/src/compile/index.js +17 -17
package/src/compile/parse.js +541 -541
package/src/compile/resolve.js +211 -211
package/src/compile/scan-exports.js +51 -51
package/src/config/defaults.js +541 -534
package/src/config/index.js +1500 -1469
package/src/config/pattern.js +107 -107
package/src/generate.mjs +163 -163
package/src/http/control-flow.js +71 -71
package/src/http/cookies-entry.js +21 -21
package/src/http/cookies.js +277 -277
package/src/http/request-cache.js +46 -46
package/src/http/request-context.js +165 -165
package/src/http/shared-cookie.js +178 -178
package/src/index.js +101 -101
package/src/init.mjs +232 -230
package/src/migrate/apply.mjs +262 -262
package/src/migrate/babel.mjs +79 -79
package/src/migrate/classify.mjs +155 -155
package/src/migrate/config.mjs +126 -126
package/src/migrate/fs-walk.mjs +191 -191
package/src/migrate/parse.mjs +26 -26
package/src/migrate/scan.mjs +177 -177
package/src/migrate/transform/expr-source.mjs +168 -168
package/src/migrate/transform/island.mjs +67 -67
package/src/migrate/transform/jsx-to-component.mjs +302 -302
package/src/migrate/transform/jsx-to-jsk.mjs +330 -330
package/src/migrate/transform/page-split.mjs +435 -435
package/src/migrate/write.mjs +81 -81
package/src/migrate.mjs +171 -171
package/src/runtime/alias-hooks.mjs +119 -119
package/src/runtime/register.mjs +4 -4
package/src/server/admin/actions.js +229 -229
package/src/server/admin/auth.js +125 -125
package/src/server/admin/event-log.js +151 -151
package/src/server/admin/gate.js +209 -209
package/src/server/admin/inventory.js +188 -188
package/src/server/admin/mount.js +56 -56
package/src/server/admin/router.js +216 -216
package/src/server/admin/snapshot.js +241 -241
package/src/server/assets.js +147 -147
package/src/server/auth/handoff.js +309 -309
package/src/server/cache-blob.js +70 -70
package/src/server/cache-control.js +45 -0
package/src/server/cache-deps.js +42 -42
package/src/server/cache-vary.js +113 -113
package/src/server/cloudflare.js +607 -607
package/src/server/create-app.js +366 -366
package/src/server/data-cache.js +553 -553
package/src/server/dev/report.js +485 -485
package/src/server/dev/socket.js +170 -170
package/src/server/dev/version-check.mjs +139 -139
package/src/server/disk-cache.js +233 -233
package/src/server/ejs-adapter.js +59 -59
package/src/server/html-cache.js +1196 -1196
package/src/server/image-optimizer.js +500 -500
package/src/server/logs/access-middleware.js +66 -66
package/src/server/logs/file-sink.js +193 -193
package/src/server/logs/pipeline.js +165 -165
package/src/server/logs/s3-put.js +214 -214
package/src/server/logs/s3-sink.js +112 -112
package/src/server/metadata.js +102 -102
package/src/server/middleware/compression.js +205 -205
package/src/server/middleware/csrf.js +134 -134
package/src/server/middleware/dev-gate.js +75 -75
package/src/server/middleware/headers.js +37 -37
package/src/server/middleware/redirects.js +32 -32
package/src/server/middleware/robots-txt.js +341 -341
package/src/server/middleware/static-precompressed.js +121 -121
package/src/server/middleware/trailing-slash.js +53 -53
package/src/server/middleware/upstream-proxy.js +141 -141
package/src/server/og-image.js +369 -356
package/src/server/port-guard.js +255 -255
package/src/server/prewarm.js +1082 -1082
package/src/server/redis.js +588 -588
package/src/server/render.js +910 -910
package/src/server/router.js +157 -157
package/src/server/status-page.js +265 -265
package/src/server/upstream-limiter.js +376 -376
package/src/server/upstream-tracking.js +166 -166
package/src/shared/cookie-domain.js +66 -66
package/src/start.mjs +22 -22
package/src/templates/layout.ejs +30 -30
package/src/templates/layout.jsk +30 -30
package/src/version.mjs +31 -31
package/src/views/components/loader.js +101 -101
package/src/views/helpers/html.js +102 -102
package/src/views/helpers/tags.js +375 -375
package/types/config/defaults.d.ts +6 -0
package/types/config/index.d.ts +6 -0
package/types/server/cache-control.d.ts +28 -0
package/types/server/og-image.d.ts +5 -0

package/docs/en/04-rendering.md CHANGED Viewed

@@ -1,669 +1,675 @@
-# 04 — Rendering and templates
-This document explains how server HTML is produced: the EJS engine settings,
-how the layout file is resolved and which locals it can use, the page templates
-under `views/pages`, the automatic registration of the components under
-`views/components/**`, the `html`/`tags` helpers that templates receive for
-free, the translation of the `metadata` object into `<head>` tags, and the
-three render hooks. What the controller sends into this layer is covered in
-[03-routing.md](./03-routing.md), and `asset()`/`hasAsset()`, which produce
-asset URLs, in [08-build.md](./08-build.md).
-## The render pipeline
-```
-route(controller)
- └─ produce()
-     ├─ controller(ctx)  → page definition
-     └─ renderPage(page)
-         ├─ hooks.metadata(page) + page.metadata      → metadata
-         ├─ Promise.all([
-         │     renderView(page.view, { …data, metadata }),   → body
-         │     hooks.layoutContext({ pathname, metadata }),  → context
-         │   ])
-         └─ layout (.jsk compiled or .ejs)  → full HTML
-```
-The layout context and the body are produced **in parallel**. The reason comes
-from measurement: in most projects navigation comes from upstream, and waiting
-for it in sequence with the body render adds needless latency to every page.
-## `.jsk` — build-time compiled templates
-New apps default to `.jsk`. At build time they become normal ESM modules under
-`.jskelet/templates/*.mjs`. There is **no request-time parsing, `eval`, or
-`new Function`**. Production path:
-```
-controller data → imported render(data, helpers) → HTML
-```
-### Syntax summary
-```html
-<section class="wrapper">
-  <h1>{{ title }}</h1>
-  <div>{{{ trustedHtml }}}</div>
-  {#if items.length}
-    <List :items="items" />
-  {#else}
-    <p>Empty</p>
-  {/if}
-  {#each items as item, i}
-    <li :data-i="i">{{ item }}</li>
-  {/each}
-  <Link href="/" text="Home" />
-  <div data-island="counter" data-island-props='{"start":0}'></div>
-</section>
-```
-| Feature | Form |
-| --- | --- |
-| Escaped text | `{{ expr }}` |
-| Raw HTML | `{{{ expr }}}` |
-| Conditional | `{#if expr}` … `{#else}` … `{/if}` |
-| Loop | `{#each list as item}` or `as item, i` |
-| Include | `{#include "partials/header"}` (compiled `.jsk`) |
-| Component | PascalCase tag; `:prop="expr"`, `prop="literal"`, boolean `disabled` |
-| Built-ins | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage`, `Stylesheets`, `BodyScripts`, `JsonLd` |
-The expression language is intentionally small (access, compare, ternary,
-`.length`). No assignments, object literals, or arbitrary calls — keep logic in
-controllers or JS components.
-#### Template or component?
-When moving off EJS, draw the line early:
-| Stay in `.jsk` | Move to a JS component |
-| --- | --- |
-| Text, conditionals, lists, prop binding | Function calls, object construction, formatting |
-| Built-in tags (`Link`, `Image`, …) | Composing HTML from several helpers |
-| Ready-made data from the controller | Upstream / error-aware UI (`LoadErrorState`) |
-If the template cannot write `format(x)` or `{ a: 1 }`, that is intentional: the
-work belongs in `views/components/*.js` or the controller. Prefer a clear
-component boundary over widening the expression language when complex pages
-“escape” into JS.
-### Editor support
-`extensions/vscode-jsk` is a VS Code / Cursor extension in this repo: syntax
-highlighting, language configuration, and snippets. Local install:
-```bash
-code --install-extension extensions/vscode-jsk
-```
-See the extension README for details.
-### Coexistence with EJS
-If a compiled `.jsk` exists for a view id it wins; otherwise `.ejs` is rendered
-with EJS. Existing apps keep working unchanged. `jskelet init` scaffolds `.jsk`.
-Legacy `.ejs` needs the optional `ejs` peer installed in the application
-(`npm install ejs`); without it only `.jsk` templates run.
-## The EJS engine (legacy)
-EJS remains supported as an **optional peer dependency** for legacy templates.
-The engine is set up once on the first render; the component scan touches the
-file system, so it cannot be done on every request and cannot be computed
-before the config is loaded.
-Settings:
-| Setting | Value | Reason |
-| --- | --- | --- |
-| `root`, `views` | the `views` directory | `include('partials/header')` calls resolve from the views root |
-| `cache` | `false` in dev, `true` in prod | so template edits show up instantly in dev |
-| `rmWhitespace` | `true` | output size |
-| `async` | `true` | `await` can be used inside templates |
-For embedded uses (tests, scripts) `resetRenderEngine()` is exported: it
-refreshes the registry when component files change. It is not needed in the
-normal flow because the dev server restarts the process.
-## Layout
-### How the layout file is found
-1. `jskelet.config.mjs` → if `layout` is given, it is used. The path is
-   resolved relative to the **parent directory of the views directory**: if
-   `views` is the default, `layout: "views/custom.jsk"` → `<root>/views/custom.jsk`.
-2. If it is not given and `views/layout.jsk` exists (compiled), that is used.
-3. Else if `views/layout.ejs` exists (legacy), that is used.
-4. If that does not exist either, the framework's own minimal layout is used
-   (`node_modules/jskelet/src/templates/layout.jsk`, also reachable through the
-   `jskelet/layout` specifier).
-These fallbacks exist so that a new project can work with a single route. The
-most practical way to move to your own layout is to copy that file to
-`views/layout.jsk`.
-### The framework's default layout
-```html
-<!DOCTYPE html>
-<html :lang="lang">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    {{{ extraHead }}}
-    <Stylesheets :styles="styles" />
-    {{{ headMeta }}}
-    <JsonLd :items="structuredData" />
-  </head>
-  <body :class="bodyClass">
-    {{{ body }}}
-    <BodyScripts :entries="entries" :devtools="devtools" :devBasePath="devBasePath" />
-  </body>
-</html>
-```
-The `.jsk` expression language has no function calls, so asset loops live in the
-built-in `<Stylesheets />`, `<BodyScripts />` and `<JsonLd />` tags instead of
-inline `hasAsset` / `asset` / `forEach` in the layout.
-Points to watch:
-- **`extraHead` comes first.** Delaying resource hints (`preconnect`, LCP
-  `preload`) writes straight into LCP.
-- **`<Stylesheets />` emits global `app.css` (render-blocking)** plus controller
-  `styles: [...]`, with the reasoning in
-  [02-architecture.md](./02-architecture.md). If the build has not run,
-  `hasAsset` is false inside the tag and nothing is emitted.
-- **`<BodyScripts />` emits `main.js`, page `entries`, and the
-  development-only overlay.** The overlay script exists only when
-  `NODE_ENV=development`; it is absent from production output.
-- **`<JsonLd />` turns `structuredData` into safe
-  `application/ld+json` scripts.**
-### Layout locals
-| Local | Type | Source |
-| --- | --- | --- |
-| `metadata` | `object` | `hooks.metadata()` + controller `metadata` (the controller wins) |
-| `headMeta` | `string` | ready-made `<head>` tags produced from `metadata` |
-| `extraHead` | `string` | `preconnect` hints + `navigation` hints + controller `head` + `context.extraHead` |
-| `structuredData` | `unknown[]` | `hooks.layoutContext()` → `structuredData`; defaults to `[]` |
-| `body` | `string` | The render output of the page template |
-| `bodyClass` | `string` | controller `bodyClass` → `context.bodyClass` → `""` |
-| `entries` | `string[]` | controller `entries`; defaults to `[]` |
-| `styles` | `string[]` | controller `styles`; defaults to `[]` |
-| `pathname` | `string` | `req.path`; **defaults to the empty string** |
-| `lang` | `string` | `context.lang` → `brand.lang` → `"en"` |
-| `devtools` | `boolean` | `NODE_ENV === "development"` |
-| `devBasePath` | `string` | `brand.devBasePath`, defaults to `/__jskelet/dev` |
-| `asset`, `hasAsset` | function | Manifest access |
-| html/tags helpers | function | `esc`, `attrs`, `cx`, `cn`, `jsonScript`, `link`, `image`, `icon`, `preloadImage`, `toKebab` |
-| exports of `views/components/**` | function | Automatic registration |
-| every field returned by `hooks.layoutContext()` | — | Becomes a local directly |
-The empty default for `pathname` is deliberate: writing `"/"` leads to the kind
-of bug where every page thinks it is the home page and renders the logo as an
-`<h1>`.
-## Page templates
-The `view` field gives the path under `views/` without an extension:
-`"pages/home"` → `views/pages/home.jsk` (else legacy `home.ejs`). The locals
-passed to the template are the contents of the `data` field plus `metadata` —
-**not** the layout locals. The page template still has access to all helpers
-and components.
-```html
-{# views/pages/home.jsk #}
-<section class="wrapper">
-  <h1 class="text-3xl font-bold">{{ heading }}</h1>
-  {# `list` is defined in views/components/list.js; no import needed. #}
-  <List :items="items" />
-  <div class="mt-8" data-island="counter" data-island-props='{"start":5}'></div>
-</section>
-```
-In `.jsk`, `{{ }}` escapes and `{{{ }}}` emits raw HTML (trusted strings only).
-Legacy EJS keeps `<%= %>` / `<%- %>` with the same meaning; because `async: true`
-is on there, `await` can also be used inside an `.ejs` template, but keeping
-data fetching in the controller makes diagnosis easier.
-## Components: `views/components/**`
-Components are not EJS partials but **functions that return HTML strings**.
-Every `.js` file under `views/components/**` is scanned and **every named
-export** becomes a template local. There is no hand-maintained barrel file:
-creating the file is enough to add a new component.
-```js
-// views/components/list.js
-import { esc } from "jskelet/html";
-/**
- * @param {{ items: string[] }} props
- * @returns {string}
- */
-export function list({ items }) {
-  if (!items?.length) return "";
-  const rows = items.map((item) => `<li class="py-1">${esc(item)}</li>`).join("");
-  return `<ul class="mt-6 list-disc pl-6">${rows}</ul>`;
-}
-```
-In the template:
-```ejs
-<%- list({ items }) %>
-```
-Rules:
-- The scan is recursive; subdirectories are covered too.
-- `default` exports are ignored — only named exports are registered.
-- The compile-time known-component set is read from **named exports in the
-  source**, not from the file basename. `sectionHead` in `ui.js` →
-  `<SectionHead />` in the template (runtime already adds a PascalCase alias
-  for camelCase exports). You do not need a stub re-export named after the
-  file.
-- `loader.js` and `index.js` do not count as component files.
-- If `views/components/index.js` exists it is loaded first as a **barrel**,
-  with the lowest priority. Its only purpose is to turn `lib/` re-exports into
-  template locals; the components' own files come later and silently overwrite
-  it.
-- If the same name (or the same PascalCase tag) is defined in two different
-  component files, that is an **error, not a warning**: build and server
-  startup stop with `Component 'card' is defined twice: …`. Overwriting the
-  barrel is the deliberate exception.
-- If the `views/components` directory does not exist the component registry
-  stays empty; a project that uses no components works fine too.
-## Helpers: `jskelet/html`
-They are passed to templates automatically; in component files you get them
-with `import { … } from "jskelet/html"`.
-### `esc(value)`
-Escaping for text content and attribute values (`&`, `<`, `>`, `"`, `'`).
-`null`, `undefined` and `false` are turned into the empty string — so in
-conditional rendering an expression like `false && "…"` does not print
-`"false"`.
-```js
-esc('<b>"x"</b>');  // "&lt;b&gt;&quot;x&quot;&lt;/b&gt;"
-```
-### `attrs(object)`
-Turns an attribute object into a string. `null`/`undefined`/`false` are
-skipped, `true` is written as a boolean attribute, and the remaining values are
-escaped. If the output is not empty it comes back **with a leading space**, so
-`<div${attrs(...)}>` is always formatted correctly.
-```js
-`<input${attrs({ type: "text", required: true, value: null })}>`;
-// '<input type="text" required>'
-```
-### `cx(...inputs)`
-The `clsx` equivalent: it accepts strings, numbers, arrays and
-`{ className: condition }` objects, and drops falsy values. It does **not**
-resolve Tailwind conflicts.
-```js
-cx("btn", isActive && "btn-active", { "btn-lg": size === "lg" });
-```
-### `cn(...inputs)`
-Merges with `cx()`, then resolves Tailwind conflicts with `tailwind-merge`. Use
-this when a component's default classes need to be overridable by the caller.
-```js
-cn("px-4 py-2 bg-slate-100", className);  // if className is "bg-white", bg-slate-100 drops
-```
-`tailwind-merge` is kept as a runtime dependency because class computation
-happens only on the server; it never enters the client bundle.
-### `jsonScript(value)`
-Safe JSON for the body of a `<script type="application/ld+json">`: `<`, `>`,
-`&` and U+2028/U+2029 are escaped, so a `</script` or `<!--` sequence cannot
-close the body.
-```ejs
-<script type="application/ld+json"><%- jsonScript(article) %></script>
-```
-## Helpers: `jskelet/tags`
-The equivalents of `next/link`, `next/image` and `@phosphor-icons/react`. They
-all return HTML strings and are emitted from EJS with `<%- %>`.
-### `link(props)`
-```js
-link({
-  href: "/about",
-  text: "About",
-  class: "font-semibold",
-  // optional: html, title, ariaLabel, target, rel, attrs
-});
-```
-- If `title` is not given it is filled in automatically in the order
-  `ariaLabel` → `text` → `href`.
-- If `href` starts with `http://` or `https://`, `target="_blank"` and
-  `rel="noopener noreferrer"` are added automatically; if you give them
-  explicitly your values are used.
-- If `html` is given the content is emitted raw; if `text` is given it is
-  escaped.
-- The `attrs` object passes extra attributes through and overrides the previous
-  ones.
-### `image(props)`
-```js
-image({
-  src: "/hero.png",
-  alt: "Kapak",
-  priority: true,
-  // optional: width, height, class, sizes, srcset, fill, loading,
-  //           unoptimized, attrs
-});
-```
-Behaviour:
-- For local raster images under `public/`, the webp variants generated at build
-  time (`.jskelet/images.json`) are added automatically as `srcset` plus
-  intrinsic `width`/`height`. Local paths missing from the manifest are emitted
-  as-is.
-- When `images.remote.allowHosts` is set, remote `http(s)` URLs are rewritten to
-  the `/_jskelet/image?url=&w=` proxy (webp). If `width` is set, `srcset`
-  includes 1x/2x plus config `widths`.
-- If `srcset` is given by hand, or `unoptimized: true` is set, neither the
-  manifest nor the remote proxy is used.
-- If only **one** variant was produced (because the source is already small),
-  `srcset`/`sizes` are not written; they would be pure noise. For remote images,
-  a single width still rewrites `src` to the optimized URL.
-- If `sizes` is not given a reasonable default is produced: the image is not
-  scaled beyond its own intrinsic width, and it fills the viewport on narrow
-  screens (`(max-width: Npx) 100vw, Npx`).
-- `priority: true` → `loading="eager"`, `decoding="sync"`,
-  `fetchpriority="high"`. For the LCP image.
-- Without `priority` → `loading="lazy"`, `decoding="async"`.
-- `fill: true` → `width`/`height` are not written and the classes
-  `absolute inset-0 h-full w-full object-cover` are merged in with `cn()`.
-### `icon(props)`
-Emits a `<use>` from the SVG sprite generated at build time.
-```js
-icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
-// <svg width="20" height="20" class="…" aria-hidden="true" focusable="false"
-//   fill="currentColor" viewBox="0 0 256 256"><use href="/assets/sprite.<hash>.svg#arrow-right-bold"></use></svg>
-```
-- `name` is the Phosphor name; the forms `ArrowRightIcon` and `ArrowRight` are
-  accepted too and converted to `arrow-right` (`toKebab()`).
-- `weight` is part of the sprite id: `thin`, `light`, `regular` (the default),
-  `bold`, `fill`, `duotone`.
-- `size` defaults to 24; it is written as `width` and `height`.
-- In development a one-time warning is printed when a symbol that is not in the
-  sprite is requested. The sprite contains only the names that are visible
-  **statically** in the source; if a call whose name is computed at runtime
-  points at a missing symbol, the screen is silently left blank
-  ([08-build.md](./08-build.md)).
-### `preloadImage(props)`
-```js
-preloadImage({ href: "/assets/img/hero-1280.abc.webp", imagesrcset, imagesizes });
-// <link rel="preload" as="image" href="…" fetchpriority="high">
-```
-In practice `headHints()` is used rather than calling this directly:
-```js
-import { headHints } from "jskelet";
-return {
-  view: "pages/article",
-  head: headHints({ href: cover, imageSrcSet, imageSizes }),
-};
-```
-`headHints()` returns the empty string when there is no `href`, so you do not
-need to write a condition. Preconnects are not repeated here because the layout
-already emits them on every page.
-## Metadata → `<head>`
-The controller returns `metadata` and the framework turns it into tags (the
-equivalent of Next.js's Metadata API). The schema is deliberately small; if you
-need more, raw HTML is added through `extraTags`, so the framework does not
-have to cut a release for every new kind of meta tag.
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `title` | `string` | `<title>` |
-| `titleTemplate` | `string` | `"%s \| Site"` — `title` is embedded into it. Applied only if `title` is also present. |
-| `description` | `string` | `<meta name="description">` |
-| `canonical` | `string` | Absolute or relative URL |
-| `siteUrl` | `string` | Base for making a relative `canonical` absolute |
-| `robots` | `{ index?: boolean, follow?: boolean }` | Defaults to `index, follow` |
-| `locale` | `string` | `og:locale` |
-| `openGraph` | `{ title, description, url, type, siteName, image, imageWidth, imageHeight }` | `og:*` tags |
-| `twitter` | `{ card, site, creator, title, description, image }` | `twitter:*` tags |
-| `extraTags` | `string[]` | Raw tags to be emitted as-is |
-Generation rules:
-- **The robots default is indexable.** Hiding a page should be an explicit
-  decision: `robots: { index: false }` → `noindex, follow`.
-- **OpenGraph uses `property`, not `name`.** Some scrapers ignore og tags
-  written with `name`.
-- **Inheritance chain:** if there is no `og:title` then `title`, no
-  `og:description` then `description`, no `og:url` then the absolutised
-  `canonical`, no `twitter:title` then `og:title` → `title`, no
-  `twitter:image` then `og:image`.
-- **`twitter:card`**, if not given, is `summary_large_image` when there is an
-  `og:image` and `summary` otherwise.
-- **Empty values are never emitted:** fields that are `null`, `undefined` or
-  `""` produce no tag.
-- If `og:type` is not given it is `website`.
-Example:
-```js
-return {
-  view: "pages/article",
-  metadata: {
-    title: article.title,
-    description: article.summary,
-    canonical: `/news/${article.slug}`,
-    openGraph: {
-      type: "article",
-      image: article.cover,
-      imageWidth: 1200,
-      imageHeight: 630,
-    },
-    extraTags: [`<meta property="article:published_time" content="${article.date}">`],
-  },
-};
-```
-Put fields that are the same on every page, such as `titleTemplate` and
-`siteUrl`, into `hooks.metadata()`; the controller only supplies what is
-specific to the page.
-The `renderHeadMeta(metadata)` function is exported; it can be used when you
-need to produce the same tags outside the layout (for example in a fragment or
-an email).
-## robots.txt
-The application writes `robots.txt`: `public/robots.txt` or a plain route.
-The framework does not change that body; it appends a JSkelet note and
-`Disallow` rules **under** a successful text response. If there is no file
-and no route, the framework does not invent a `robots.txt`.
-Paths added:
-- `/_jskelet/` — admin panel, remote image proxy, auth handoff
-- `/__jskelet/` — development tools
-- `/_fragment/` — partial responses without a layout
-An endpoint moved off those prefixes is added too, but only when it is
-actually mounted: `admin.basePath`, `images.remote.path`,
-`auth.crossSubdomainHandoff.path`. `brand.devBasePath` is written only in
-development; in production that path may be the application's own page.
-The note starts with the configured brand name (`brand.name`, default
-`JSkelet`). The trailing group repeats `User-agent: *` together with every
-other agent already named in the file. Google does not merge a
-crawler-specific group with `*`; it does merge a second group for the same
-agent. If the note is already in the file, it is not appended again.
-## Dynamic OG images
-Counterpart to Next.js `ImageResponse` / `opengraph-image.tsx`. There is no JSX:
-pass card fields (`title`, `description`, `siteName`, colours) or a raw `svg`.
-With the optional `sharp` peer installed the response is PNG; otherwise SVG.
-Most social scrapers expect PNG, so install `sharp` in production.
-Because the response is an image, not HTML, do not use `route()` — `ogHandler`
-returns a plain Express handler. `notFound()` and a `null` return yield 404.
-```js
-// routes/35-og.mjs
-export default function register(app, { ogHandler, notFound }) {
-  app.get(
-    "/og/blog/:slug.png",
-    ogHandler(async ({ params }) => {
-      const post = getPost(params.slug);
-      if (!post) notFound();
-      return {
-        title: post.title,
-        description: post.excerpt,
-        siteName: "Blog",
-      };
-    }),
-  );
-}
-```
-Point page metadata at the absolute URL and size:
-```js
-openGraph: {
-  type: "article",
-  image: `${SITE_URL}/og/blog/${post.slug}.png`,
-  imageWidth: 1200,
-  imageHeight: 630,
-},
-```
-Raw SVG or a Next-like class:
-```js
-import { ImageResponse, sendOgImage, OG_SIZE } from "jskelet";
-app.get("/og/custom.png", async (req, res) => {
-  const image = new ImageResponse(
-    `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">…</svg>`,
-    OG_SIZE,
-  );
-  await image.send(res);
-  // or: await sendOgImage(res, { title: "…", format: "svg" });
-});
-```
-Default `Cache-Control`:
-`public, max-age=0, s-maxage=86400, stale-while-revalidate=604800`.
-Override with `cacheControl`. Working example: `examples/blog/routes/35-og.mjs`.
-## Hooks
-Hooks are defined in `jskelet.config.mjs` under `hooks`. They are all optional
-and they can all be `async`. **A failing hook does not take the page down:**
-the framework falls back to its own default and warns.
-### `hooks.metadata(page)`
-The metadata default for every page. It receives the page definition being
-rendered as its argument and returns a metadata object. The controller's
-`metadata` field is layered **on top of it** (field by field, shallow merge).
-```js
-hooks: {
-  metadata() {
-    return {
-      titleTemplate: "%s | JSkelet",
-      description: "A site built with JSkelet.",
-      siteUrl: "https://example.com",
-    };
-  },
-}
-```
-### `hooks.layoutContext({ pathname, metadata })`
-The locals added to the layout on every render. **Every field** of the returned
-object becomes a layout local; in addition three fields are interpreted
-specially:
-- `lang` → `<html lang>`
-- `structuredData` → JSON-LD scripts (an array)
-- `extraHead` → appended to `<head>` (after the controller's `head`)
-- `bodyClass` → used if the controller did not supply a `bodyClass`
-```js
-hooks: {
-  async layoutContext({ pathname }) {
-    return {
-      bodyClass: "min-h-full",
-      navigation: await getNavigation(),
-      isHome: pathname === "/",
-    };
-  },
-}
-```
-This hook runs **in parallel** with the body render; calling upstream inside it
-does not add sequential latency to the page.
-### `hooks.notFound()`
-The 404 page definition. The object it returns is handed to `renderPage` with
-`pathname: "/404"`. Details: [03-routing.md](./03-routing.md).
-### Other hooks
-`hooks.prewarmPaths()` belongs to prewarming rather than the render layer; see
-[06-caching.md](./06-caching.md).
-## The overlay portal point
-`jskelet/client` → `getOverlayRoot()` gives the target that modal and drawer
-content will be moved into: if the layout has
-`<div id="jskelet-overlays"></div>` it goes there, otherwise into `body`. The
-portal prevents an ancestor element carrying `overflow` or `transform` from
-clipping a `position: fixed` overlay. If you are going to use modals, adding
-this div at the end of the layout's `<body>` is enough
-([05-islands.md](./05-islands.md)).
-## What's next
-- Islands and `entries`: [05-islands.md](./05-islands.md)
-- `asset()`, the manifest and the Tailwind scan: [08-build.md](./08-build.md)
-- Where hooks live in the config: [07-configuration.md](./07-configuration.md)
+# 04 — Rendering and templates
+This document explains how server HTML is produced: the EJS engine settings,
+how the layout file is resolved and which locals it can use, the page templates
+under `views/pages`, the automatic registration of the components under
+`views/components/**`, the `html`/`tags` helpers that templates receive for
+free, the translation of the `metadata` object into `<head>` tags, and the
+three render hooks. What the controller sends into this layer is covered in
+[03-routing.md](./03-routing.md), and `asset()`/`hasAsset()`, which produce
+asset URLs, in [08-build.md](./08-build.md).
+## The render pipeline
+```
+route(controller)
+ └─ produce()
+     ├─ controller(ctx)  → page definition
+     └─ renderPage(page)
+         ├─ hooks.metadata(page) + page.metadata      → metadata
+         ├─ Promise.all([
+         │     renderView(page.view, { …data, metadata }),   → body
+         │     hooks.layoutContext({ pathname, metadata }),  → context
+         │   ])
+         └─ layout (.jsk compiled or .ejs)  → full HTML
+```
+The layout context and the body are produced **in parallel**. The reason comes
+from measurement: in most projects navigation comes from upstream, and waiting
+for it in sequence with the body render adds needless latency to every page.
+## `.jsk` — build-time compiled templates
+New apps default to `.jsk`. At build time they become normal ESM modules under
+`.jskelet/templates/*.mjs`. There is **no request-time parsing, `eval`, or
+`new Function`**. Production path:
+```
+controller data → imported render(data, helpers) → HTML
+```
+### Syntax summary
+```html
+<section class="wrapper">
+  <h1>{{ title }}</h1>
+  <div>{{{ trustedHtml }}}</div>
+  {#if items.length}
+    <List :items="items" />
+  {#else}
+    <p>Empty</p>
+  {/if}
+  {#each items as item, i}
+    <li :data-i="i">{{ item }}</li>
+  {/each}
+  <Link href="/" text="Home" />
+  <div data-island="counter" data-island-props='{"start":0}'></div>
+</section>
+```
+| Feature | Form |
+| --- | --- |
+| Escaped text | `{{ expr }}` |
+| Raw HTML | `{{{ expr }}}` |
+| Conditional | `{#if expr}` … `{#else}` … `{/if}` |
+| Loop | `{#each list as item}` or `as item, i` |
+| Include | `{#include "partials/header"}` (compiled `.jsk`) |
+| Component | PascalCase tag; `:prop="expr"`, `prop="literal"`, boolean `disabled` |
+| Built-ins | `Link`, `Image`, `Icon`, `CsrfField`, `PreloadImage`, `Stylesheets`, `BodyScripts`, `JsonLd` |
+The expression language is intentionally small (access, compare, ternary,
+`.length`). No assignments, object literals, or arbitrary calls — keep logic in
+controllers or JS components.
+#### Template or component?
+When moving off EJS, draw the line early:
+| Stay in `.jsk` | Move to a JS component |
+| --- | --- |
+| Text, conditionals, lists, prop binding | Function calls, object construction, formatting |
+| Built-in tags (`Link`, `Image`, …) | Composing HTML from several helpers |
+| Ready-made data from the controller | Upstream / error-aware UI (`LoadErrorState`) |
+If the template cannot write `format(x)` or `{ a: 1 }`, that is intentional: the
+work belongs in `views/components/*.js` or the controller. Prefer a clear
+component boundary over widening the expression language when complex pages
+“escape” into JS.
+### Editor support
+`extensions/vscode-jsk` is a VS Code / Cursor extension in this repo: syntax
+highlighting, language configuration, and snippets. Local install:
+```bash
+code --install-extension extensions/vscode-jsk
+```
+See the extension README for details.
+### Coexistence with EJS
+If a compiled `.jsk` exists for a view id it wins; otherwise `.ejs` is rendered
+with EJS. Existing apps keep working unchanged. `jskelet init` scaffolds `.jsk`.
+Legacy `.ejs` needs the optional `ejs` peer installed in the application
+(`npm install ejs`); without it only `.jsk` templates run.
+## The EJS engine (legacy)
+EJS remains supported as an **optional peer dependency** for legacy templates.
+The engine is set up once on the first render; the component scan touches the
+file system, so it cannot be done on every request and cannot be computed
+before the config is loaded.
+Settings:
+| Setting | Value | Reason |
+| --- | --- | --- |
+| `root`, `views` | the `views` directory | `include('partials/header')` calls resolve from the views root |
+| `cache` | `false` in dev, `true` in prod | so template edits show up instantly in dev |
+| `rmWhitespace` | `true` | output size |
+| `async` | `true` | `await` can be used inside templates |
+For embedded uses (tests, scripts) `resetRenderEngine()` is exported: it
+refreshes the registry when component files change. It is not needed in the
+normal flow because the dev server restarts the process.
+## Layout
+### How the layout file is found
+1. `jskelet.config.mjs` → if `layout` is given, it is used. The path is
+   resolved relative to the **parent directory of the views directory**: if
+   `views` is the default, `layout: "views/custom.jsk"` → `<root>/views/custom.jsk`.
+2. If it is not given and `views/layout.jsk` exists (compiled), that is used.
+3. Else if `views/layout.ejs` exists (legacy), that is used.
+4. If that does not exist either, the framework's own minimal layout is used
+   (`node_modules/jskelet/src/templates/layout.jsk`, also reachable through the
+   `jskelet/layout` specifier).
+These fallbacks exist so that a new project can work with a single route. The
+most practical way to move to your own layout is to copy that file to
+`views/layout.jsk`.
+### The framework's default layout
+```html
+<!DOCTYPE html>
+<html :lang="lang">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {{{ extraHead }}}
+    <Stylesheets :styles="styles" />
+    {{{ headMeta }}}
+    <JsonLd :items="structuredData" />
+  </head>
+  <body :class="bodyClass">
+    {{{ body }}}
+    <BodyScripts :entries="entries" :devtools="devtools" :devBasePath="devBasePath" />
+  </body>
+</html>
+```
+The `.jsk` expression language has no function calls, so asset loops live in the
+built-in `<Stylesheets />`, `<BodyScripts />` and `<JsonLd />` tags instead of
+inline `hasAsset` / `asset` / `forEach` in the layout.
+Points to watch:
+- **`extraHead` comes first.** Delaying resource hints (`preconnect`, LCP
+  `preload`) writes straight into LCP.
+- **`<Stylesheets />` emits global `app.css` (render-blocking)** plus controller
+  `styles: [...]`, with the reasoning in
+  [02-architecture.md](./02-architecture.md). If the build has not run,
+  `hasAsset` is false inside the tag and nothing is emitted.
+- **`<BodyScripts />` emits `main.js`, page `entries`, and the
+  development-only overlay.** The overlay script exists only when
+  `NODE_ENV=development`; it is absent from production output.
+- **`<JsonLd />` turns `structuredData` into safe
+  `application/ld+json` scripts.**
+### Layout locals
+| Local | Type | Source |
+| --- | --- | --- |
+| `metadata` | `object` | `hooks.metadata()` + controller `metadata` (the controller wins) |
+| `headMeta` | `string` | ready-made `<head>` tags produced from `metadata` |
+| `extraHead` | `string` | `preconnect` hints + `navigation` hints + controller `head` + `context.extraHead` |
+| `structuredData` | `unknown[]` | `hooks.layoutContext()` → `structuredData`; defaults to `[]` |
+| `body` | `string` | The render output of the page template |
+| `bodyClass` | `string` | controller `bodyClass` → `context.bodyClass` → `""` |
+| `entries` | `string[]` | controller `entries`; defaults to `[]` |
+| `styles` | `string[]` | controller `styles`; defaults to `[]` |
+| `pathname` | `string` | `req.path`; **defaults to the empty string** |
+| `lang` | `string` | `context.lang` → `brand.lang` → `"en"` |
+| `devtools` | `boolean` | `NODE_ENV === "development"` |
+| `devBasePath` | `string` | `brand.devBasePath`, defaults to `/__jskelet/dev` |
+| `asset`, `hasAsset` | function | Manifest access |
+| html/tags helpers | function | `esc`, `attrs`, `cx`, `cn`, `jsonScript`, `link`, `image`, `icon`, `preloadImage`, `toKebab` |
+| exports of `views/components/**` | function | Automatic registration |
+| every field returned by `hooks.layoutContext()` | — | Becomes a local directly |
+The empty default for `pathname` is deliberate: writing `"/"` leads to the kind
+of bug where every page thinks it is the home page and renders the logo as an
+`<h1>`.
+## Page templates
+The `view` field gives the path under `views/` without an extension:
+`"pages/home"` → `views/pages/home.jsk` (else legacy `home.ejs`). The locals
+passed to the template are the contents of the `data` field plus `metadata` —
+**not** the layout locals. The page template still has access to all helpers
+and components.
+```html
+{# views/pages/home.jsk #}
+<section class="wrapper">
+  <h1 class="text-3xl font-bold">{{ heading }}</h1>
+  {# `list` is defined in views/components/list.js; no import needed. #}
+  <List :items="items" />
+  <div class="mt-8" data-island="counter" data-island-props='{"start":5}'></div>
+</section>
+```
+In `.jsk`, `{{ }}` escapes and `{{{ }}}` emits raw HTML (trusted strings only).
+Legacy EJS keeps `<%= %>` / `<%- %>` with the same meaning; because `async: true`
+is on there, `await` can also be used inside an `.ejs` template, but keeping
+data fetching in the controller makes diagnosis easier.
+## Components: `views/components/**`
+Components are not EJS partials but **functions that return HTML strings**.
+Every `.js` file under `views/components/**` is scanned and **every named
+export** becomes a template local. There is no hand-maintained barrel file:
+creating the file is enough to add a new component.
+```js
+// views/components/list.js
+import { esc } from "jskelet/html";
+/**
+ * @param {{ items: string[] }} props
+ * @returns {string}
+ */
+export function list({ items }) {
+  if (!items?.length) return "";
+  const rows = items.map((item) => `<li class="py-1">${esc(item)}</li>`).join("");
+  return `<ul class="mt-6 list-disc pl-6">${rows}</ul>`;
+}
+```
+In the template:
+```ejs
+<%- list({ items }) %>
+```
+Rules:
+- The scan is recursive; subdirectories are covered too.
+- `default` exports are ignored — only named exports are registered.
+- The compile-time known-component set is read from **named exports in the
+  source**, not from the file basename. `sectionHead` in `ui.js` →
+  `<SectionHead />` in the template (runtime already adds a PascalCase alias
+  for camelCase exports). You do not need a stub re-export named after the
+  file.
+- `loader.js` and `index.js` do not count as component files.
+- If `views/components/index.js` exists it is loaded first as a **barrel**,
+  with the lowest priority. Its only purpose is to turn `lib/` re-exports into
+  template locals; the components' own files come later and silently overwrite
+  it.
+- If the same name (or the same PascalCase tag) is defined in two different
+  component files, that is an **error, not a warning**: build and server
+  startup stop with `Component 'card' is defined twice: …`. Overwriting the
+  barrel is the deliberate exception.
+- If the `views/components` directory does not exist the component registry
+  stays empty; a project that uses no components works fine too.
+## Helpers: `jskelet/html`
+They are passed to templates automatically; in component files you get them
+with `import { … } from "jskelet/html"`.
+### `esc(value)`
+Escaping for text content and attribute values (`&`, `<`, `>`, `"`, `'`).
+`null`, `undefined` and `false` are turned into the empty string — so in
+conditional rendering an expression like `false && "…"` does not print
+`"false"`.
+```js
+esc('<b>"x"</b>');  // "&lt;b&gt;&quot;x&quot;&lt;/b&gt;"
+```
+### `attrs(object)`
+Turns an attribute object into a string. `null`/`undefined`/`false` are
+skipped, `true` is written as a boolean attribute, and the remaining values are
+escaped. If the output is not empty it comes back **with a leading space**, so
+`<div${attrs(...)}>` is always formatted correctly.
+```js
+`<input${attrs({ type: "text", required: true, value: null })}>`;
+// '<input type="text" required>'
+```
+### `cx(...inputs)`
+The `clsx` equivalent: it accepts strings, numbers, arrays and
+`{ className: condition }` objects, and drops falsy values. It does **not**
+resolve Tailwind conflicts.
+```js
+cx("btn", isActive && "btn-active", { "btn-lg": size === "lg" });
+```
+### `cn(...inputs)`
+Merges with `cx()`, then resolves Tailwind conflicts with `tailwind-merge`. Use
+this when a component's default classes need to be overridable by the caller.
+```js
+cn("px-4 py-2 bg-slate-100", className);  // if className is "bg-white", bg-slate-100 drops
+```
+`tailwind-merge` is kept as a runtime dependency because class computation
+happens only on the server; it never enters the client bundle.
+### `jsonScript(value)`
+Safe JSON for the body of a `<script type="application/ld+json">`: `<`, `>`,
+`&` and U+2028/U+2029 are escaped, so a `</script` or `<!--` sequence cannot
+close the body.
+```ejs
+<script type="application/ld+json"><%- jsonScript(article) %></script>
+```
+## Helpers: `jskelet/tags`
+The equivalents of `next/link`, `next/image` and `@phosphor-icons/react`. They
+all return HTML strings and are emitted from EJS with `<%- %>`.
+### `link(props)`
+```js
+link({
+  href: "/about",
+  text: "About",
+  class: "font-semibold",
+  // optional: html, title, ariaLabel, target, rel, attrs
+});
+```
+- If `title` is not given it is filled in automatically in the order
+  `ariaLabel` → `text` → `href`.
+- If `href` starts with `http://` or `https://`, `target="_blank"` and
+  `rel="noopener noreferrer"` are added automatically; if you give them
+  explicitly your values are used.
+- If `html` is given the content is emitted raw; if `text` is given it is
+  escaped.
+- The `attrs` object passes extra attributes through and overrides the previous
+  ones.
+### `image(props)`
+```js
+image({
+  src: "/hero.png",
+  alt: "Kapak",
+  priority: true,
+  // optional: width, height, class, sizes, srcset, fill, loading,
+  //           unoptimized, attrs
+});
+```
+Behaviour:
+- For local raster images under `public/`, the webp variants generated at build
+  time (`.jskelet/images.json`) are added automatically as `srcset` plus
+  intrinsic `width`/`height`. Local paths missing from the manifest are emitted
+  as-is.
+- When `images.remote.allowHosts` is set, remote `http(s)` URLs are rewritten to
+  the `/_jskelet/image?url=&w=` proxy (webp). If `width` is set, `srcset`
+  includes 1x/2x plus config `widths`.
+- If `srcset` is given by hand, or `unoptimized: true` is set, neither the
+  manifest nor the remote proxy is used.
+- If only **one** variant was produced (because the source is already small),
+  `srcset`/`sizes` are not written; they would be pure noise. For remote images,
+  a single width still rewrites `src` to the optimized URL.
+- If `sizes` is not given a reasonable default is produced: the image is not
+  scaled beyond its own intrinsic width, and it fills the viewport on narrow
+  screens (`(max-width: Npx) 100vw, Npx`).
+- `priority: true` → `loading="eager"`, `decoding="sync"`,
+  `fetchpriority="high"`. For the LCP image.
+- Without `priority` → `loading="lazy"`, `decoding="async"`.
+- `fill: true` → `width`/`height` are not written and the classes
+  `absolute inset-0 h-full w-full object-cover` are merged in with `cn()`.
+### `icon(props)`
+Emits a `<use>` from the SVG sprite generated at build time.
+```js
+icon({ name: "ArrowRight", weight: "bold", size: 20, class: "text-slate-500" });
+// <svg width="20" height="20" class="…" aria-hidden="true" focusable="false"
+//   fill="currentColor" viewBox="0 0 256 256"><use href="/assets/sprite.<hash>.svg#arrow-right-bold"></use></svg>
+```
+- `name` is the Phosphor name; the forms `ArrowRightIcon` and `ArrowRight` are
+  accepted too and converted to `arrow-right` (`toKebab()`).
+- `weight` is part of the sprite id: `thin`, `light`, `regular` (the default),
+  `bold`, `fill`, `duotone`.
+- `size` defaults to 24; it is written as `width` and `height`.
+- In development a one-time warning is printed when a symbol that is not in the
+  sprite is requested. The sprite contains only the names that are visible
+  **statically** in the source; if a call whose name is computed at runtime
+  points at a missing symbol, the screen is silently left blank
+  ([08-build.md](./08-build.md)).
+### `preloadImage(props)`
+```js
+preloadImage({ href: "/assets/img/hero-1280.abc.webp", imagesrcset, imagesizes });
+// <link rel="preload" as="image" href="…" fetchpriority="high">
+```
+In practice `headHints()` is used rather than calling this directly:
+```js
+import { headHints } from "jskelet";
+return {
+  view: "pages/article",
+  head: headHints({ href: cover, imageSrcSet, imageSizes }),
+};
+```
+`headHints()` returns the empty string when there is no `href`, so you do not
+need to write a condition. Preconnects are not repeated here because the layout
+already emits them on every page.
+## Metadata → `<head>`
+The controller returns `metadata` and the framework turns it into tags (the
+equivalent of Next.js's Metadata API). The schema is deliberately small; if you
+need more, raw HTML is added through `extraTags`, so the framework does not
+have to cut a release for every new kind of meta tag.
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `title` | `string` | `<title>` |
+| `titleTemplate` | `string` | `"%s \| Site"` — `title` is embedded into it. Applied only if `title` is also present. |
+| `description` | `string` | `<meta name="description">` |
+| `canonical` | `string` | Absolute or relative URL |
+| `siteUrl` | `string` | Base for making a relative `canonical` absolute |
+| `robots` | `{ index?: boolean, follow?: boolean }` | Defaults to `index, follow` |
+| `locale` | `string` | `og:locale` |
+| `openGraph` | `{ title, description, url, type, siteName, image, imageWidth, imageHeight }` | `og:*` tags |
+| `twitter` | `{ card, site, creator, title, description, image }` | `twitter:*` tags |
+| `extraTags` | `string[]` | Raw tags to be emitted as-is |
+Generation rules:
+- **The robots default is indexable.** Hiding a page should be an explicit
+  decision: `robots: { index: false }` → `noindex, follow`.
+- **OpenGraph uses `property`, not `name`.** Some scrapers ignore og tags
+  written with `name`.
+- **Inheritance chain:** if there is no `og:title` then `title`, no
+  `og:description` then `description`, no `og:url` then the absolutised
+  `canonical`, no `twitter:title` then `og:title` → `title`, no
+  `twitter:image` then `og:image`.
+- **`twitter:card`**, if not given, is `summary_large_image` when there is an
+  `og:image` and `summary` otherwise.
+- **Empty values are never emitted:** fields that are `null`, `undefined` or
+  `""` produce no tag.
+- If `og:type` is not given it is `website`.
+Example:
+```js
+return {
+  view: "pages/article",
+  metadata: {
+    title: article.title,
+    description: article.summary,
+    canonical: `/news/${article.slug}`,
+    openGraph: {
+      type: "article",
+      image: article.cover,
+      imageWidth: 1200,
+      imageHeight: 630,
+    },
+    extraTags: [`<meta property="article:published_time" content="${article.date}">`],
+  },
+};
+```
+Put fields that are the same on every page, such as `titleTemplate` and
+`siteUrl`, into `hooks.metadata()`; the controller only supplies what is
+specific to the page.
+The `renderHeadMeta(metadata)` function is exported; it can be used when you
+need to produce the same tags outside the layout (for example in a fragment or
+an email).
+## robots.txt
+The application writes `robots.txt`: `public/robots.txt` or a plain route.
+The framework does not change that body; it appends a JSkelet note and
+`Disallow` rules **under** a successful text response. If there is no file
+and no route, the framework does not invent a `robots.txt`.
+Paths added:
+- `/_jskelet/` — admin panel, remote image proxy, auth handoff
+- `/__jskelet/` — development tools
+- `/_fragment/` — partial responses without a layout
+An endpoint moved off those prefixes is added too, but only when it is
+actually mounted: `admin.basePath`, `images.remote.path`,
+`auth.crossSubdomainHandoff.path`. `brand.devBasePath` is written only in
+development; in production that path may be the application's own page.
+The note starts with the configured brand name (`brand.name`, default
+`JSkelet`). The trailing group repeats `User-agent: *` together with every
+other agent already named in the file. Google does not merge a
+crawler-specific group with `*`; it does merge a second group for the same
+agent. If the note is already in the file, it is not appended again.
+## Dynamic OG images
+Counterpart to Next.js `ImageResponse` / `opengraph-image.tsx`. There is no JSX:
+pass card fields (`title`, `description`, `siteName`, colours) or a raw `svg`.
+With the optional `sharp` peer installed the response is PNG; otherwise SVG.
+Most social scrapers expect PNG, so install `sharp` in production.
+Because the response is an image, not HTML, do not use `route()` — `ogHandler`
+returns a plain Express handler. `notFound()` and a `null` return yield 404.
+```js
+// routes/35-og.mjs
+export default function register(app, { ogHandler, notFound }) {
+  app.get(
+    "/og/blog/:slug.png",
+    ogHandler(async ({ params }) => {
+      const post = getPost(params.slug);
+      if (!post) notFound();
+      return {
+        title: post.title,
+        description: post.excerpt,
+        siteName: "Blog",
+      };
+    }),
+  );
+}
+```
+Point page metadata at the absolute URL and size:
+```js
+openGraph: {
+  type: "article",
+  image: `${SITE_URL}/og/blog/${post.slug}.png`,
+  imageWidth: 1200,
+  imageHeight: 630,
+},
+```
+Raw SVG or a Next-like class:
+```js
+import { ImageResponse, sendOgImage, OG_SIZE } from "jskelet";
+app.get("/og/custom.png", async (req, res) => {
+  const image = new ImageResponse(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">…</svg>`,
+    OG_SIZE,
+  );
+  await image.send(res);
+  // or: await sendOgImage(res, { title: "…", format: "svg" });
+});
+```
+Default headers (the durations are not tied to the HTML setting):
+```
+Cache-Control: public, max-age=0
+CDN-Cache-Control: max-age=86400, stale-while-revalidate=604800
+```
+`cacheControl` overrides `Cache-Control`; in that case `CDN-Cache-Control` is
+not written. Working example: `examples/blog/routes/35-og.mjs`.
+## Hooks
+Hooks are defined in `jskelet.config.mjs` under `hooks`. They are all optional
+and they can all be `async`. **A failing hook does not take the page down:**
+the framework falls back to its own default and warns.
+### `hooks.metadata(page)`
+The metadata default for every page. It receives the page definition being
+rendered as its argument and returns a metadata object. The controller's
+`metadata` field is layered **on top of it** (field by field, shallow merge).
+```js
+hooks: {
+  metadata() {
+    return {
+      titleTemplate: "%s | JSkelet",
+      description: "A site built with JSkelet.",
+      siteUrl: "https://example.com",
+    };
+  },
+}
+```
+### `hooks.layoutContext({ pathname, metadata })`
+The locals added to the layout on every render. **Every field** of the returned
+object becomes a layout local; in addition three fields are interpreted
+specially:
+- `lang` → `<html lang>`
+- `structuredData` → JSON-LD scripts (an array)
+- `extraHead` → appended to `<head>` (after the controller's `head`)
+- `bodyClass` → used if the controller did not supply a `bodyClass`
+```js
+hooks: {
+  async layoutContext({ pathname }) {
+    return {
+      bodyClass: "min-h-full",
+      navigation: await getNavigation(),
+      isHome: pathname === "/",
+    };
+  },
+}
+```
+This hook runs **in parallel** with the body render; calling upstream inside it
+does not add sequential latency to the page.
+### `hooks.notFound()`
+The 404 page definition. The object it returns is handed to `renderPage` with
+`pathname: "/404"`. Details: [03-routing.md](./03-routing.md).
+### Other hooks
+`hooks.prewarmPaths()` belongs to prewarming rather than the render layer; see
+[06-caching.md](./06-caching.md).
+## The overlay portal point
+`jskelet/client` → `getOverlayRoot()` gives the target that modal and drawer
+content will be moved into: if the layout has
+`<div id="jskelet-overlays"></div>` it goes there, otherwise into `body`. The
+portal prevents an ancestor element carrying `overflow` or `transform` from
+clipping a `position: fixed` overlay. If you are going to use modals, adding
+this div at the end of the layout's `<body>` is enough
+([05-islands.md](./05-islands.md)).
+## What's next
+- Islands and `entries`: [05-islands.md](./05-islands.md)
+- `asset()`, the manifest and the Tailwind scan: [08-build.md](./08-build.md)
+- Where hooks live in the config: [07-configuration.md](./07-configuration.md)