@zerotal/arch 1.13.5 → 1.14.0

package/docs/changelog.md

@@ -27,6 +27,53 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
 
+## 1.14.0 — 2026-09-01
+
+Rendering and the SSR endpoint become separate decisions. Small in practice — most apps
+change nothing — but it is a change to what a config flag does, so it takes a minor and
+says so.
+
+### Changed — BREAKING
+
+- **`inertia.ssr: true` no longer registers `POST /__ssr`.**
+
+  ```ts
+  // config/inertia.ts
+  export default InertiaConfig({
+    ssr: true, // server-render every first page load. Renders nothing else.
+    ssrEndpoint: true, // expose POST /__ssr, for a renderer outside this process
+  });
+  ```
+
+  **If you set `ssr: true` for server rendering, you need no change.** You keep exactly
+  that and stop exposing a route you were not using. Add `ssrEndpoint: true` only when
+  something outside the web process calls `/__ssr` — a separate renderer, a second host.
+
+  The endpoint exists because upstream Inertia runs on hosts with no JavaScript runtime:
+  PHP cannot import a `.tsx`, so it posts `{ component, props, url }` to a Node process and
+  gets `{ body, head }` back. That hop is forced by the host language, not chosen. Bun _is_
+  a JavaScript runtime, so [1.13.5](#1135--2026-09-01) made `ssr` import the component and
+  render it inline — no serialisation, no second process, no network.
+
+  So the endpoint solves a problem this framework does not have, and it stays only for the
+  case that is still real: deliberately moving render CPU off the web process. That is a
+  deployment choice, and it now has to be made rather than inherited.
+
+  Turning rendering on should not open a route that renders arbitrary components from POST
+  input, however well guarded. One switch, one thing — the same reasoning that separated
+  `secureHeaders: false` from the site gate in 1.13.3.
+
+### A note on what this costs
+
+Worth stating plainly, because it is easy to expect the opposite: **turning `ssr` on adds
+CPU to the web process.** Before 1.13.5 the flag rendered nothing, so there was no round
+trip to remove — a page load did no rendering at all. Now it renders every first load.
+
+The comparison where in-process rendering _is_ cheaper is against the way other frameworks
+do SSR: no HTTP hop, no JSON round trip of the whole page object, no second process to run
+and supervise. Against the framework's own previous behaviour, it is new work in exchange
+for HTML a crawler and a link preview can read.
+
 ## 1.13.5 — 2026-09-01
 
 **`inertia.ssr: true` server-renders now.** One config line, every page, no controller

package/docs/inertia/ssr.md

@@ -56,15 +56,30 @@ server renderer for the framework your app uses.
 client-rendered document is served instead, because taking a route down because an
 _optimisation_ failed would make `ssr: true` a liability rather than an improvement.
 
-## What `POST /__ssr` is for
+## What `POST /__ssr` is for, and why you probably do not want it
 
-`ssr: true` also registers it. It accepts `{ component, props, url }` and returns
-`{ body, head }` — the same contract as the Inertia Node SSR server — and it exists for
-an **external** caller: a separate renderer process, or a deployment that renders
-somewhere other than the web process.
+Set `ssrEndpoint: true` and the app exposes `POST /__ssr`, which accepts
+`{ component, props, url }` and returns `{ body, head }`.
 
-You do not need it for the switch above, which renders in-process. It is throttled and
-loopback-gated; see `ssrSecret` for reaching it from another host.
+That is the contract upstream Inertia uses, and it exists there for a reason that does not
+apply here: **PHP and Ruby have no JavaScript runtime**, so the web framework cannot import
+a `.tsx` and must hand rendering to a separate Node process. The HTTP hop is forced by the
+host language.
+
+Bun _is_ a JavaScript runtime. `ssr: true` imports the component and renders it inline, in
+the same process, with no serialisation and no network. So the endpoint solves a problem
+this framework does not have.
+
+What it is still good for is the one case that remains real: **deliberately moving render
+CPU off the web process**, onto another process or another host, on an app where rendering
+competes with request handling. Then the hop is the point rather than the cost.
+
+It is throttled, answers a 404 to anything that is not loopback, and takes `ssrSecret` for
+a renderer on another host.
+
+> **`ssr: true` does not register it, since 1.14.0.** It used to, which meant turning
+> rendering on opened a route the app never asked for. See
+> [the upgrade note](/docs/upgrade#1-13-to-1-14).
 
 ## Streaming SSR — a different question
 

package/docs/support-policy.md

@@ -75,12 +75,13 @@ dependency order, from CI. Never mix versions across packages.
   tilde if you would rather cross a minor deliberately.
 - **A break is never silent.** Every one is called out in the release notes as
   **BREAKING**, with the reason and the migration steps, and the version gets its
-  own section in the Upgrade Guide. Seven have shipped so far — the
+  own section in the Upgrade Guide. Eight have shipped so far — the
   `ComponentWith` / `BaseModelWith` removal in 1.3.0, Flow's `socket:` listener
   prefix in 1.7.2, the removal of Flow's `this.title(…)` in 1.7.3, SQLite
   foreign-key enforcement in 1.11.0, `countTokens` returning `number | null` in
   1.11.2, the refusal to write a boolean into a text column in 1.12.0, and the removal of
-  Flow's `Component.client(…)` alongside two retired aliases in 1.13.0.
+  Flow's `Component.client(…)` alongside two retired aliases in 1.13.0, and
+  `inertia.ssr` no longer registering `POST /__ssr` in 1.14.0.
 - **One of those five is in the wrong place, and it stays on the record.** 1.11.2
   is a patch, and by the rule above a patch cannot carry a break. It did: the
   `countTokens` signature changed in the same release that promoted `@zerotal/ai`

package/docs/upgrade.md

@@ -296,6 +296,34 @@ doing something quiet.
    If it really is a new migration, give it a name that does not collide once the
    leading digits are removed.
 
+## 1.13 to 1.14
+
+One breaking change, and it is small in practice.
+
+**`inertia.ssr: true` no longer registers `POST /__ssr`.** Rendering and the endpoint are
+separate decisions now:
+
+```ts fragment
+// config/inertia.ts — before
+export default InertiaConfig({ ssr: true }); // rendered, and opened the route
+
+// after
+export default InertiaConfig({ ssr: true }); // renders, and opens nothing
+export default InertiaConfig({ ssrEndpoint: true }); // opens the route, for an
+// external renderer
+```
+
+**Most apps need no change.** If you set `ssr: true` for server rendering — which is what
+the option is for — you keep exactly that, and you stop exposing a route you were not
+using. The endpoint had no in-process caller before 1.13.5, so an app that set the flag was
+getting the route and nothing else.
+
+**Add `ssrEndpoint: true` only if something outside the web process calls `/__ssr`** — a
+separate renderer, a second host. If you are not running one, you were not using it.
+
+Why split them: turning rendering on should not open a route that renders arbitrary
+components from POST input, however well guarded. One switch, one thing.
+
 ## 1.12 to 1.13
 
 Three retirements in one crossing, deliberately together: each is a small migration, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.13.5",
+  "version": "1.14.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.13.5"
+    "@zerotal/core": "1.14.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.13.5"
+    "@zerotal/orm": "1.14.0"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [