jskelet 0.5.4 → 0.6.0

package/docs/en/07-configuration.md

@@ -55,7 +55,7 @@ export default {
     lang: "tr",
   },
 
-  layout: "views/layout.ejs",
+  layout: "views/layout.jsk",
   routes: ["./routes/10-pages.mjs", "./routes/99-catch-all.mjs"],
   trailingSlash: false,
 
@@ -92,7 +92,7 @@ export default {
   watch: ["data"],
 
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["downloads"] },
   clientEnv: ["PUBLIC_WS_URL"],
 
@@ -213,27 +213,32 @@ cross-subdomain handoff bridge for a short session id.
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` or `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | When on: `POST /_jskelet/auth/handoff` + `?handoff=` redeem. Object: `allowedCookieNames` (required), `ttlSeconds?`, `path?`, `maxValueBytes?`, `maxPendingTickets?`, `maxMintsPerIpPerMinute?` |
 
 ```js
 auth: {
-  crossSubdomainHandoff: { ttlSeconds: 60 },
+  crossSubdomainHandoff: {
+    allowedCookieNames: ["sid"],
+    ttlSeconds: 60,
+  },
 },
 ```
 
-Details and the `window.name` fallback:
-[12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
+The mint endpoint is mounted **after** the CSRF middleware (origin checks).
+Cookie names outside the allowlist or that are not RFC 6265 tokens get 400.
+Details: [12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
 
 ## `layout`
 
 **Type:** `string` — **Default:** none (automatic resolution)
 
-Path of the layout `.ejs` file. The value given is resolved relative to the
-**parent directory of the views directory**, so with the default `views`,
-`"views/custom.ejs"` → `<root>/views/custom.ejs`.
+Path of the layout file (`.jsk` or legacy `.ejs`). The value given is resolved
+relative to the **parent directory of the views directory**, so with the default
+`views`, `"views/custom.jsk"` → `<root>/views/custom.jsk`.
 
-If not given, in order: `views/layout.ejs` if it exists, otherwise the
-framework's minimal layout. Details: [04-rendering.md](./04-rendering.md).
+If not given, in order: `views/layout.jsk`, `views/layout.ejs` (legacy),
+otherwise the framework's `src/templates/layout.jsk` default. Details:
+[04-rendering.md](./04-rendering.md).
 
 ## `routes`
 
@@ -335,7 +340,7 @@ field reference.
 | `trustProxy` | `boolean` | `true` | Express's `trust proxy` setting. Needed behind a reverse proxy for the correct protocol and client IP. |
 | `cookieSecret` | `string \| null` | `null` | The signed cookie secret. When absent, `JSKELET_SECRET` is read. |
 | `csrf.enabled` | `boolean` | `true` | The origin / `Sec-Fetch-Site` check. |
-| `csrf.token` | `boolean` | `false` | The double-submit token layer. |
+| `csrf.token` | `boolean` | `false` | The double-submit token layer. **Turn on** for cookie-session forms. |
 | `csrf.allowedOrigins` | `string[]` | `[]` | Origins accepted alongside our own host. |
 | `csrf.exclude` | `string[]` | `[]` | Paths exempt from the check; `source` pattern syntax. |
 | `csrf.cookieName` | `string` | `"csrf_token"` | Name of the token cookie. |
@@ -343,14 +348,17 @@ field reference.
 | `csrf.headerName` | `string` | `"x-csrf-token"` | Header the token is also accepted in. |
 
 `trustProxy` should be **turned off** on a server exposed directly to the
-internet: while it is on, a client can forge its own `X-Forwarded-For` and rate
-limiting or audit logs see the wrong address.
+internet: while it is on, a client can forge `X-Forwarded-For` /
+`X-Forwarded-Proto` / Host, and rate limits, admin IP allowlists, Secure
+cookies, and cache `vary.host` see the wrong address. Behind a reverse proxy
+(nginx, Caddy, Cloudflare), `true` is the right default.
 
 The CSRF check only rejects requests that are **known** to be cross-site — when
 `Origin` does not match or `Sec-Fetch-Site: cross-site` arrives. If neither is
 present the request passes, because browsers always send `Origin` on a
-cross-origin POST while webhooks never do. Even so, listing non-browser
-endpoints in `csrf.exclude` makes the intent readable.
+cross-origin POST while webhooks never do. For cookie-session dashboards,
+enable `csrf.token: true` and `csrfField()` as a second layer; put webhook
+paths in `csrf.exclude`.
 
 ## `navigation`
 
@@ -500,21 +508,29 @@ fonts: [
 
 ## `icons`
 
-**Type:** `{ scan?: string[] } | false` — **Default:** `{}`
+**Type:** `{ scan?: string[], dir?: string } | false` — **Default:** `{ dir: "icons" }`
 
-Phosphor SVG sprite generation.
+SVG icon sprite generation. The source is chosen **XOR**: if the `icons.dir`
+directory exists, only the flat SVGs there are used; otherwise
+`@phosphor-icons/core` (when installed).
 
 | Value | Result |
 | --- | --- |
-| `{}` (default) | The sprite is generated; scanned directories are `["views", "client", "routes", "lib"]` |
+| `{}` (default) | `dir: "icons"`; scanned directories are `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Changes the local SVG root |
 | `{ scan: [...] }` | Changes the scanned directories |
 | `false` | The sprite step is skipped entirely |
 
-If `@phosphor-icons/core` is not in the application's `node_modules`, the step is
-silently skipped. Details: [08-build.md](./08-build.md).
+A local directory (when present) uses flat file names: `house.svg` →
+`house:regular`, `house-bold.svg` → `house:bold`. An empty `icons/` directory
+does not fall back to Phosphor — delete the directory to open the fallback.
+Details: [08-build.md](./08-build.md).
 
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 
 ## `images`
@@ -547,8 +563,9 @@ When `remote.allowHosts` is set, also proxies remote images at runtime
 
 If `false` is given, neither surface runs. The build step requires `sharp` and
 never runs on a watch pass. With remote enabled, `sharp` is also needed at
-**runtime**; without it the optimizer 302-redirects to the source URL. Details:
-[08-build.md](./08-build.md).
+**runtime**; without it the optimizer 302-redirects to the source URL. Fetch
+does not auto-follow redirects: every hop is re-checked against `allowHosts`
+and private addresses. Details: [08-build.md](./08-build.md).
 
 ```js
 images: {
@@ -580,7 +597,10 @@ that is not in the list returns `undefined` instead of crashing.
 clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 ```
 
-**Do not put secrets here** — the values sit in the bundle in plain text.
+**Do not put secrets here** — the values sit in the bundle in plain text. Keys
+whose names look secret-like (`SECRET`, `PASSWORD`, `TOKEN`, `API_KEY`,
+`PRIVATE`, …) are **rejected at build time** (`PUBLIC` / `PUBLISHABLE` names
+are exempt).
 
 ## `headers()`
 
@@ -590,6 +610,7 @@ clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 Response headers by path pattern. The framework only writes long-lived cache
 headers for static files; every other header (CSP, COOP, HSTS,
 X-Frame-Options…) comes from here and takes precedence over the defaults.
+Production sites should at least define the security headers below.
 
 **All** matching rules are applied (unlike redirects, it does not stop at the
 first match), in order; if two rules write the same header, the later one wins.
@@ -604,11 +625,18 @@ async headers() {
       source: "/:path*",
       headers: [
         { key: "X-Frame-Options", value: "SAMEORIGIN" },
+        { key: "X-Content-Type-Options", value: "nosniff" },
         { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
         {
           key: "Content-Security-Policy",
-          value: "default-src 'self'; img-src 'self' https://cdn.example.com data:",
+          value: "default-src 'self'; img-src 'self' https://cdn.example.com data:; script-src 'self'",
         },
+        // Only when you terminate HTTPS yourself:
+        // { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains" },
       ],
     },
     {
@@ -1098,7 +1126,7 @@ and no warning is printed.
 | Variable | Who reads it | Default | Meaning |
 | --- | --- | --- | --- |
 | `NODE_ENV` | everywhere | `production` (start/build), `development` (dev) | Determines the dev overlay, EJS cache, manifest re-reading, route error behaviour and prewarm defaults. `jskelet dev` sets it itself — `cross-env` is not needed. |
-| `PORT` | `startServer` | `3000` | Port to listen on |
+| `PORT` | `startServer` | `3000` | Port to listen on. If busy, the process refuses to start; `jskelet start|dev --murder` kills the listener |
 | `HOST` | `startServer` | `::` | Interface to bind to. The default listens dual-stack (IPv6 + IPv4); it falls back to `0.0.0.0` where IPv6 is unavailable |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | The signed cookie secret. Read when `security.cookieSecret` is not set; if neither exists, the signed cookie API throws. [12](./12-dashboards-and-sessions.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |

package/docs/en/08-build.md

@@ -174,8 +174,10 @@ a new utility is written. Changes are coalesced over 120 ms.
 
 ## Client JS — esbuild
 
-Every `.js` file inside `client/entries/*.js` is an entry. If the directory does
-not exist or is empty, the step is skipped.
+Every source file under `client/entries/*.{js,ts,mts}` is an entry (no `.tsx`).
+The manifest key is always `*.js` (`main.ts` → `main.js`). Multiple extensions
+for the same stem fail the build. If the directory does not exist or is empty,
+the step is skipped.
 
 esbuild settings:
 
@@ -185,7 +187,7 @@ esbuild settings:
 | `format` | `esm` | `type="module"` scripts |
 | `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | The lower bound of the ESM + dynamic import + `IntersectionObserver` island model; transpiling to anything older grows the output without winning a single visitor |
 | `minify` | `true` | — |
-| `sourcemap` | `true` | Diagnostics in the browser |
+| `sourcemap` | only when `NODE_ENV=development` | Production builds do not publish `.map` files under `public/assets` |
 | `entryNames` | `[name].[hash]` | `immutable` cache |
 | `chunkNames` | `chunks/[name].[hash]` | — |
 | `legalComments` | `none` | — |
@@ -196,17 +198,19 @@ The output lands under `public/assets/js/` and is cleaned first on every pass.
 ### The `@/` alias
 
 On the esbuild side, `@/` resolves to the project root and extension completion
-is performed (`.js`, `.mjs`, `.json`, `/index.js`). The same behaviour as
-`alias-hooks.mjs` on the Node side, so the modules under `lib/` can use the same
-import style both on the server and in the browser.
+is performed (`.js`, `.mjs`, `.ts`, `.mts`, `.json`, `/index.js`, `/index.ts`).
+Node `alias-hooks.mjs` resolves only `.js` / `.mjs` / `.json` on the server, so
+shared `@/lib` modules must stay `.js`. Client-only `.ts` imports work on the
+esbuild path.
 
 ### Inlining `clientEnv`
 
 There is no `process` in the browser; modules shared with the server still read
 `process.env`. The keys declared through `config.clientEnv` plus `NODE_ENV` are
 defined as a single object at build time, which means that reading a key not in
-the list returns `undefined` instead of crashing. Details:
-[07-configuration.md](./07-configuration.md).
+the list returns `undefined` instead of crashing. Secret-like key names
+(`SECRET`, `API_KEY`, …) fail the build; names containing `PUBLIC` /
+`PUBLISHABLE` are exempt. Details: [07-configuration.md](./07-configuration.md).
 
 ### Manifest keys
 
@@ -259,17 +263,33 @@ Because the `.woff2` extension and the `/fonts/` prefix are in the default
 
 ## Icon sprite
 
-From the individual SVGs inside `@phosphor-icons/core`, it produces a `<symbol>`
-set for **only the icons actually used in the source**. Shipping the whole set
-means 1500+ icons, i.e. several megabytes; usage scanning typically keeps the
-sprite at 10-30 symbols.
+Produces a `<symbol>` set for **only the icons actually used in the source**.
+Shipping the whole set means 1500+ icons, i.e. several megabytes; usage scanning
+typically keeps the sprite at 10-30 symbols. The hashed `sprite.svg` is written
+under `public/assets/` and is covered by precompress.
+
+The source is chosen **XOR** — the two are never merged:
+
+1. If `icons.dir` (default `icons/`) **exists as a directory**, only the flat
+   SVGs there. An empty directory does not fall back to Phosphor; delete the
+   directory to open the fallback.
+2. Otherwise `@phosphor-icons/core` (from the application's `node_modules`). If
+   it is not installed, the step is silently skipped.
+
+Local file names:
+
+| File | Sprite key |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 
 - Symbol id: `<kebab-name>-<weight>`, e.g. `arrow-right-bold`.
-- The package is resolved from the **application's** `node_modules` (the icon set
-  is the application's devDependency); if it is not installed, the step is
-  silently skipped.
-- The scanned directories default to `views`, `client`, `routes`, `lib`; they can
-  be changed with `icons.scan`. Scanned extensions: `.ejs`, `.js`, `.mjs`.
+- `viewBox` is copied from the source SVG onto the `<symbol>`; if missing,
+  `0 0 256 256` (recommended for Phosphor / `icon()` compatibility).
+- The scanned directories default to `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; they can be changed with `icons.scan`. Scanned
+  extensions: `.ejs`, `.jsk`, `.js`, `.mjs`, `.ts`, `.mts`.
 - Weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. An
   unrecognised weight counts as `regular`.
 
@@ -296,8 +316,8 @@ If you see this warning, either write the name as a constant, or add the relevan
 directory to the `icons.scan` list, or keep the name in a configuration field in
 the form `icon: "XLogo"`.
 
-Names that cannot be found in Phosphor are warned about as a summary at the end
-of the build: `N icons missing → …`
+Names that cannot be found in the chosen source are warned about as a summary at
+the end of the build: `N icons missing → …`
 
 ## Image optimisation
 
@@ -339,7 +359,9 @@ and `image()` falls back to the original file. It never runs on a watch pass.
 When `images.remote.allowHosts` is set, `createApp` mounts `/_jskelet/image`.
 CMS / CDN covers never enter the build, so `image()` rewrites those host URLs to
 `?url=&w=`; the endpoint encodes webp with sharp and stores files under
-`.jskelet/image-cache/`. Details: [07-configuration.md](./07-configuration.md).
+`.jskelet/image-cache/`. Upstream fetch follows redirects manually: every hop is
+re-checked against the allowlist and private IP / DNS rules (open-redirect SSRF
+is closed). Details: [07-configuration.md](./07-configuration.md).
 
 ## Precompress
 
@@ -373,7 +395,7 @@ copy, the request is handed over to `express.static`
 | `tailwindcss` | CSS (peer) | Tailwind directives cannot be resolved |
 | `lightningcss` | CSS minification | Tailwind's output is used, a few kB bigger |
 | `sharp` | Image optimisation | The step is skipped; `image()` uses the original |
-| `@phosphor-icons/core` | Icon sprite | The step is skipped; `icon()` produces an empty `<use>` |
+| `@phosphor-icons/core` | Icon sprite (when no local `icons/` dir) | The step is skipped; `icon()` produces an empty `<use>` |
 
 If you are not going to use CSS, simply never create the `paths.styles` file: the
 step is skipped with a warning and postcss is not needed.

package/docs/en/09-dev-tools.md

@@ -23,6 +23,11 @@ jskelet dev
 (suppresses the build banner) and, if a TTY is present, `JSKELET_COLOR=1`
 (forces color on piped output).
 
+If the listen port (`PORT`, default `3000`) is already taken, the server
+**does not start**; the error line includes the PID and a `--murder` hint.
+`jskelet dev --murder` kills the listener and binds the same port (for a
+process left running in another terminal).
+
 Startup order: banner → build steps → server ready → `Ready` summary. The
 summary is printed once both the build and the server are ready; otherwise it
 got buried among the build lines arriving afterwards.
@@ -75,7 +80,7 @@ WATCH_DIRS = [
 The `jskelet.config.mjs` file itself is watched as well: when the config
 changes, both the server and the build must come up with the new settings.
 
-Watched extensions: `.js`, `.mjs`, `.json`, `.ejs`.
+Watched extensions: `.js`, `.mjs`, `.json`, `.jsk`, `.ejs`.
 
 `views` is watched too, because most components live in
 `views/components/**.js` and, since those modules are imported into the server

package/docs/en/10-deployment.md

@@ -23,6 +23,10 @@ runs the build itself. In a Docker image the build has already happened, so this
 is a no-op; the point is that someone running `npm start` directly does not end
 up with an unstyled page.
 
+If the listen port is already taken, the process **does not start** (PID + hint).
+`jskelet start --murder` kills that listener and binds — useful for a leftover
+dev process; production orchestrators usually do not need it.
+
 When the server is ready it prints a single line:
 
 ```
@@ -64,7 +68,8 @@ Using both sources together blurs which value actually applies; not shipping a
 `.env` in the prod image is the cleanest option.
 
 **Secret keys must not go into the `clientEnv` list:** those values are embedded
-into the client bundle as plain text ([08-build.md](./08-build.md)).
+into the client bundle as plain text ([08-build.md](./08-build.md)). Secret-like
+names (`SECRET`, `API_KEY`, …) now fail the build.
 
 ## Docker
 

package/docs/en/11-migration.md

@@ -8,6 +8,29 @@ modeled on the subset of Next that people actually use — concepts like the
 will feel familiar. The *reasons* behind the differences are in
 [02-architecture.md](./02-architecture.md).
 
+## `jskelet migrate` (codemod)
+
+Run the codemod against an App Router tree. Babel (`@babel/parser`,
+`@babel/types`) ships with JSkelet — no extra install.
+
+```bash
+npx jskelet migrate scan ../my-next-app
+npx jskelet migrate apply ../my-next-app --out . --write
+npx jskelet migrate config ../my-next-app --write
+```
+
+| Command | What it does |
+| --- | --- |
+| `migrate` / `migrate scan` | Inventory pages, layouts, `"use client"` modules, blockers (nested layouts, Server Actions, Suspense). |
+| `migrate apply` | **Automatic convert:** `page.*` → feature controller + `.jsk`; presentational components → `views/components/*.js`; clients → island `mount()` stubs. Default is dry-run; pass `--write`. Never overwrites (conflicts get a `.migrate` suffix). |
+| `migrate config` | Draft `jskelet.config.mjs` from `next.config` (`headers` / `redirects` / `rewrites`, `images.widths`, `NEXT_PUBLIC_*` → `clientEnv`). |
+
+Flags: `--out <dir>`, `--only pages,components,islands`, `--json`, `--strict` (exit 1 on partial/skipped).
+
+**Converted automatically:** `className`, `{{ }}` / `{{{ }}}`, `{#if}` / `{#each}`, `next/image` → `<Image />`, `next/link` → `<Link />`, `dangerouslySetInnerHTML`, `revalidate`, simple controller prelude (`await` data + `notFound()`).
+
+**Not converted (reported):** React hooks, Server Actions, nested layout flattening, Streaming/Suspense, client-side routing. Confidence per file is `ok` / `partial` / `skipped`.
+
 ## Equivalence table
 
 ### Configuration
@@ -31,8 +54,8 @@ will feel familiar. The *reasons* behind the differences are in
 | `app/page.js` (file-based routing) | `app.get(...)` inside `routes/*.mjs` | The order is written explicitly ([03](./03-routing.md)) |
 | `app/[slug]/page.js` | `app.get("/:slug", route(...))` | Express pattern syntax |
 | `params`, `searchParams` | `ctx.params`, `ctx.query` | The controller's single argument |
-| `layout.js` | `views/layout.ejs` + `hooks.layoutContext()` | A single layout; no nested layouts |
-| Server component (RSC) | Controller + EJS template + `views/components/**` | A function returns an HTML string |
+| `layout.js` | `views/layout.jsk` + `hooks.layoutContext()` | A single layout; no nested layouts |
+| Server component (RSC) | Controller + `.jsk` template + `views/components/**` | A function returns an HTML string |
 | Client component (`"use client"`) | Island (`data-island` + `mount`) | The whole page is not hydrated ([05](./05-islands.md)) |
 | `notFound()` | `notFound()` | Same name, same control flow |
 | `redirect()` | `redirect()` (307) | For permanent, `permanentRedirect()` (308) |
@@ -88,8 +111,11 @@ Account for these from the start in your migration plan:
 
 - **React itself.** Components turn into functions that return HTML strings. No
   JSX, no hooks, no virtual DOM.
-- **TypeScript.** The project is plain JS + JSDoc. With `checkJs: true` in
-  `jsconfig.json` you get type checking from the editor.
+- **TypeScript.** Framework source is plain JS + JSDoc and publishes `.d.ts` for
+  consumers. Client entries and islands may be `.ts` / `.mts` (esbuild strips
+  types; the manifest key stays `*.js`). Server routes, hooks and
+  `jskelet.config.mjs` remain Node ESM JavaScript — use `checkJs: true` in
+  `jsconfig.json` for editor checking there.
 - **Nested layouts.** There is a single layout; you share common sections with
   EJS `include` or component functions.
 - **Streaming / Suspense / partial prerendering.** The response is produced as a
@@ -172,12 +198,12 @@ export default function register(app, { route, notFound }) {
 }
 ```
 
-```ejs
-<%# views/pages/article.ejs %>
+```jsk
+{# views/pages/article.jsk #}
 <article class="wrapper">
-  <h1 class="text-3xl font-bold"><%= article.title %></h1>
-  <%- image({ src: article.cover, alt: article.title, priority: true, width: 1200, height: 630 }) %>
-  <div><%- article.body %></div>
+  <h1 class="text-3xl font-bold">{{ article.title }}</h1>
+  <Image :src="article.cover" :alt="article.title" priority :width="1200" :height="630" />
+  <div>{{{ article.body }}}</div>
 </article>
 ```
 
@@ -190,7 +216,8 @@ single upstream request is made ([06-caching.md](./06-caching.md)).
 ### 1. Set up the skeleton (half a day)
 
 Run `npx jskelet init` in a new directory and watch `jskelet dev` come up. Leave
-the existing Next project as it is; let the migration run in parallel.
+the existing Next project as it is; let the migration run in parallel. Optionally
+run `jskelet migrate scan <next-root>` first to list pages and blockers.
 
 Carry over the `paths` aliases from your `jsconfig.json` — prefixes like `@/`
 work the same way both on the server and in the bundle
@@ -198,6 +225,8 @@ work the same way both on the server and in the bundle
 
 ### 2. Translate `next.config.mjs` (1-2 hours)
 
+`jskelet migrate config <next-root> --write` drafts most of this. Then review:
+
 The `headers()`, `redirects()` and `rewrites()` sections are copied almost
 verbatim. Check the pattern syntax: JSkelet supports the `:slug`, `:path*`,
 `/a-:b` and `/:path*.svg` forms; more complex `path-to-regexp` expressions are
@@ -218,9 +247,9 @@ they are copied as-is. Make two changes:
 
 ### 4. Set up the layout (half a day)
 
-Translate `app/layout.jsx` into `views/layout.ejs`. Copying the framework's
-default layout (`node_modules/jskelet/src/templates/layout.ejs`) and editing it
-is the fastest path.
+Translate `app/layout.jsx` into `views/layout.jsk` (or let `migrate apply` draft
+it). Copying the framework's default layout (`jskelet/layout` → `.jsk`) and
+editing it is the fastest path.
 
 If you fetch data inside `layout.jsx` (navigation, site settings), move it into
 `hooks.layoutContext()`: it runs in parallel with the body render, and every
@@ -231,6 +260,10 @@ into `hooks.metadata()`.
 
 ### 5. Translate the components (the longest step)
 
+`jskelet migrate apply --only components --write` converts presentational
+components that are props + JSX with no hooks. Everything else you finish by
+hand:
+
 Every React component turns into a function:
 
 ```jsx
@@ -264,8 +297,9 @@ Keep components small and pure; leave data fetching in the controller.
 
 ### 6. Migrate the pages (hours per page)
 
-Every `page.jsx` splits into a controller plus an EJS template. File them with
-the order in mind:
+`jskelet migrate apply --only pages --write` splits each `page.*` into a
+feature controller plus a `.jsk` template. Review `partial` / `skipped` rows,
+then finish the TODO markers. File them with the order in mind:
 
 ```
 routes/
@@ -342,7 +376,8 @@ especially for verifying that the redirect rules are correct.
 ## Common mistakes during migration
 
 - **Forgetting `esc()`.** Writing `${value}` out of JSX habit means XSS. In
-  templates, mind the distinction between `<%= %>` (escaped) and `<%- %>` (raw).
+  `.jsk` templates use `{{ }}` (escaped) vs `{{{ }}}` (raw); in components call
+  `esc()` yourself.
 - **Opening a new directory without adding `@source`.** The classes are silently
   dropped.
 - **Putting the catch-all route in the wrong order.** `/:slug` always goes last.

package/docs/en/12-dashboards-and-sessions.md

@@ -145,7 +145,9 @@ export default {
     sharedCookieRoots: [".investvio.com", ".localhost"],
   },
   auth: {
-    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+    crossSubdomainHandoff: {
+      allowedCookieNames: ["sid"], // required allowlist
+    },
   },
 };
 ```
@@ -210,17 +212,20 @@ a **read-back** runs; if the browser rejected the Domain, `handoff: true`.
 
 With `auth.crossSubdomainHandoff` on:
 
-1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (with `?handoff=`)
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (with
+   `?handoff=`). Mint is mounted **after** the CSRF middleware; `name` must be
+   in `allowedCookieNames` and an RFC 6265 token.
 2. On the target host a GET middleware redeems the one-time ticket, sets the
    cookie (shared Domain first, else host-only), and 303-redirects without
    `handoff`
 
 `next` must be under the same `sharedCookieRoots`. Tickets live ~60s in process
-memory. Do not put a JWT in the URL.
+memory, with pending-ticket and per-IP mint limits. Do not put a JWT in the URL.
 
 The `window.name` bridge is the cookie-less fallback:
 `handoffViaWindowName` on the source page, `consumeWindowNameHandoff` on the
-target.
+target. Prefer the server handoff when possible — `window.name` remains readable
+across origins in the same tab.
 
 ## CSRF
 

package/docs/en/README.md

@@ -2,10 +2,12 @@
 
 JSkelet is a framework that "feels frameworkless", built for SEO- and
 speed-focused sites: it produces complete HTML on the server with Express 5 +
-EJS, adds interactivity with vanilla JS islands, compiles CSS into a single
-stylesheet with Tailwind v4, and instead of ISR uses an HTML TTL cache that
-lives in process memory with stale-while-revalidate. No React, no TypeScript;
-plain JavaScript and JSDoc.
+build-time `.jsk` (EJS is an optional legacy peer), adds interactivity with
+vanilla JS islands, compiles CSS into a single stylesheet with Tailwind v4, and
+instead of ISR uses an HTML TTL cache that lives in process memory with
+stale-while-revalidate. No React; the framework source is plain JavaScript with
+JSDoc. Apps may write client islands and entries in TypeScript, and the
+published package ships declaration files.
 
 This directory is the full reference for the framework. To read it in order,
 start from the beginning; if you are looking for a specific topic, go straight
@@ -22,7 +24,7 @@ change one, change the other.
 | [01-getting-started.md](./01-getting-started.md) | Installation, `jskelet init`, first route, first island, directory structure, CLI commands |
 | [02-architecture.md](./02-architecture.md) | Architectural decisions and their rationale: the island model, complete server HTML, cache strategy, middleware order |
 | [03-routing.md](./03-routing.md) | The route module contract, load order, the controller contract, `ctx`, `notFound`/`redirect`, config redirects/rewrites |
-| [04-rendering.md](./04-rendering.md) | EJS layout, pages, automatic component registration, `html`/`tags` helpers, metadata → `<head>`, hooks |
+| [04-rendering.md](./04-rendering.md) | `.jsk` layout/pages, automatic component registration, `html`/`tags`, metadata → `<head>`, hooks; EJS legacy |
 | [05-islands.md](./05-islands.md) | The `data-island` contract, hydration strategies, `client/entries/*`, `createStore`, DOM helpers, `startSafeImages` |
 | [06-caching.md](./06-caching.md) | `withHtmlCache`, `revalidate`, stale-while-revalidate, the cache key, `X-JSkelet-Cache`, in-request cache, degraded render, prewarm |
 | [07-configuration.md](./07-configuration.md) | Full `jskelet.config.mjs` reference, the `source` pattern syntax, environment variable table |