@plitzi/sdk-server 0.38.12 → 0.38.14

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # @plitzi/sdk-server
 
+## 0.38.14
+
+### Patch Changes
+
+- 493955a: ## SDK
+
+  - **An embedded space leaves the page's theme alone** (`@plitzi/plitzi-sdk`, `@plitzi/plitzi-builder`): plitzi-ui's
+    `Provider` stamps `dark` on `<html>` by default — and, being `light`, takes it off — so every space mounted with
+    `themeScope: 'container'` turned the page around it light, and nothing put it back. The SDK and the builder now leave
+    the class to their own theme provider (`applyColorModeClass={false}`).
+  - **A space inside a space** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-shared`): one drawn inside another — the `plitziSdk`
+    element, a plugin rendering one, the builder's canvas — knows it (`render.enclosed`). It is `container` unless it
+    says otherwise, wears its theme on its own root and starts from the page's when its own is `system`, keeps its
+    stylesheet to its own root (`@scope` — its `:root` palette and `.dark` rules repainted the outer page, its
+    `.plitzi-sdk` rule restyled the outer root), writes no `<title>` (`ownsHead`) and no `theme` cookie.
+  - **The `plitziSdk` element draws** (`@plitzi/plitzi-sdk`): it rendered in `widget` mode with no page to show, so it
+    drew nothing. A widget with no `currentPageId` now shows the page its home address would. And it takes a space's
+    documents as well as a key: `offlineData`, bound whole (an `apiContainer`'s answer, a runtime's route, what
+    `plitzi_render` returns) or as `offlineData.schema` and `offlineData.style` from two elements — waiting, without an
+    error, for the half that has not answered; one that cannot be drawn is said why, in the console and on the canvas.
+  - **`<PlitziSdk>` inside a plugin draws** (`@plitzi/plitzi-sdk`): it mounted a router of its own inside the page's, and
+    React Router refused it — `routing: 'memory'` or not. A space inside another is a widget: `raw` becomes `widget`
+    there, one page and no router (a frame of its own, `iframe` or `shadow`, is left as asked).
+  - **A space inside another is as tall as what it holds** (`@plitzi/plitzi-sdk`): its root was `min-h-screen`, as a
+    space that IS the page is, so a card of three lines drawn in a panel took the window's height.
+  - **`<PlitziSdk.Plugin component>` takes a component with its own props** (`@plitzi/plitzi-sdk`), as `render()`'s
+    plugins do: typed `ComponentPluginFC`, it refused any component that read its attributes.
+  - **An edited page keeps its address in step** (`@plitzi/plitzi-sdk`): the routes are built from the pages' own
+    elements, and those were read again only when the list of pages changed — an edit to one page (its slug, its flag)
+    leaves that list the same, and the routes kept its old address until something else rebuilt them.
+  - **Packages declare only what they use** (`@plitzi/sdk-dev-tools`, `@plitzi/sdk-shared`): `@plitzi/sdk-plugins`, which
+    the dev tools no longer import, and `terser`, which no build here runs, are no longer dependencies.
+  - **An edited page keeps its route up to date** (`@plitzi/plitzi-sdk`): the routes are built from the pages' own
+    elements, which were read again only when the list of pages changed — an edit to one page (its slug, its flag) left
+    the list the same and the route at the old address. They follow every edit to a page now, and stay the same object
+    while no page changes.
+  - **`@plitzi/sdk-dev-tools` no longer depends on `@plitzi/sdk-plugins`**, which nothing in it imports.
+  - **A dropdown's menu opens inside a card that lifts or clips** (`@plitzi/sdk-elements`, `@plitzi/sdk-shared`): drawn
+    inside the dropdown, an ancestor with a `transform` — a card lifting on hover — made itself the containing block of
+    the menu's `position: fixed`, and one with `overflow: hidden` cut it off: the menu opened and nobody saw it. The open
+    menu and its backdrop are drawn at the space's root (`spaceRootOf`, `@plitzi/sdk-shared/helpers/spaceRoot`); a
+    style written for the popup by an ancestor's selector no longer reaches it — its own classes do.
+  - **A copy button says when it could not copy** (`@plitzi/sdk-elements`, `@plitzi/sdk-shared`,
+    `@plitzi/sdk-interactions`, `@plitzi/sdk-variables`, `@plitzi/sdk-dev-tools`): a page not served over https has no
+    clipboard — a phone opening a development server by its address — and a code block's "Copy" threw there. It reads
+    "Not copied", and says why. `clipboardWriter` and `copyText` (`@plitzi/sdk-shared/helpers/clipboard`) are the one
+    check, the `copyToClipboard` step's too.
+
+  ## Authoring
+  - **`plitziSdk` is authored like any element** (`@plitzi/sdk-authoring`, `@plitzi/sdk-elements`): its declaration moved
+    to `@plitzi/sdk-elements` beside the others, so it has a factory — `plitziSdk({ id, bind: { offlineData: 'view.data'
+} })` —, its attributes typed, and `plitzi explain` knows it.
+  - **A binding may write part of an attribute** (`@plitzi/sdk-authoring`): `offlineData.schema` writes into
+    `offlineData`, as the runtime always did; authoring refused it as an attribute nothing reads.
+  - **`choosesChildren`** (`@plitzi/sdk-shared`, `@plitzi/sdk-authoring`): a plugin that shows only some of the elements
+    put inside it — a dashboard's panels, a wizard's step — says so in its declaration, and the page checks owe none of
+    them on screen; what it draws is still read by the checks of the whole page (images, sideways scroll, legibility).
+    `verify` was red on every such page.
+
+  - **A page says how the document scrolls** (`@plitzi/sdk-elements`, `@plitzi/sdk-authoring`, `@plitzi/sdk-mcp`):
+    `documentScroll: 'locked'` holds the document still while the page is open — a dashboard or a board used with a
+    finger, where the whole page was dragged and bounced back though nothing in it scrolls — and `'noBounce'` keeps the
+    scroll without the rubber band or pull-to-refresh. The page draws the rule itself, so it is in the server's HTML and
+    leaves with the page; never inside a widget, a space drawn in another, or the builder's canvas. A Settings select,
+    `PageSpec.documentScroll`, `upsertPage`'s `documentScroll` (`null` undoes it) and the page read; an unknown value is
+    refused (`attribute-value`). `upsertPage` is now held to the lint of the page it writes, as element writes are.
+
+  ## MCP
+  - **`@plitzi/sdk-mcp/render`** (`@plitzi/sdk-mcp`): `plitzi_render`'s widget render on its own — no MCP server, no SSR,
+    no OAuth — for a project whose own agent draws in its own pages: `render`, `renderWidgetShape` to declare it as a
+    tool, `renderGuideText` for the agent. `base`, the style of the project's space, brings its tokens, classes and fonts
+    to the widget.
+
+  ## Server
+  - **`publicUrl` says where people reach the server** (`@plitzi/sdk-server`): it was `http://127.0.0.1:<port>` whatever
+    the server was. It is `https` once `serverOptions.tls` gives it a certificate, and this machine's network address
+    with `HOST` open to the network (what a tablet opens, what an OAuth provider sends it back to); `PUBLIC_URL` still
+    wins. The network addresses it prints say `https` too.
+  - **A server serving TLS reaches itself** (`@plitzi/sdk-server`): with a local certificate (mkcert) Node trusts nothing
+    the browsers were told to, so a runtime calling its own MCP failed. Its requests to its own address now connect to its
+    listener and are taken when it presents exactly its certificate (`reachOwnServer`, exported from `/runtime`).
+  - **A runtime reads compressed answers again** (`@plitzi/sdk-server`): the dispatcher `reachOwnServer` (and the
+    platform's `reachSpaceInside`) installs reached every other host with an undici connector that offers HTTP/2, and an
+    answer that came back over h2 reached Node's `fetch` without its `content-encoding` — every API that compresses read
+    as Brotli bytes. Other hosts are reached over HTTP/1.1 now, as Node's own `fetch` reaches them.
+  - **A project's server serves HTTPS from `.env`** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): `TLS_CERT` and
+    `TLS_KEY`, the certificate's and the key's paths — what `plitzi cert` writes — with no code of the project's;
+    `serverOptions.tls` still wins. A network address the certificate does not name is said at boot, the machine's
+    `.local` name is printed among the addresses when it is named, and a server on loopback alone says how to open it to
+    the network.
+  - **A session survives a phone on the Wi-Fi** (`@plitzi/sdk-server`): a private network address (`192.168.…`, `10.…`,
+    Tailscale's `100.64/10`, IPv6 unique- and link-local) and a machine's mDNS name (`studio.local`) get the local
+    cookie profile — `SameSite=Lax`, no `Secure`, no `Domain`. They got `SameSite=None; Secure`, which a browser drops
+    over http: nobody could sign in from a tablet. A deployment's own `.local` sub-domains (`app.example.local`) keep the
+    strict profile.
+  - **Hiding the dev tools on a server over HTTPS hydrates** (`@plitzi/sdk-server`): a server with a certificate speaks
+    HTTP/2, which sends no `Host` — only `:authority` — and the cookies named for the origin's port (the dev tools'
+    `plitzi_debug_<port>`, forced flags, painted state) were looked for without it. Shift+F12 hid the dev tools in the
+    browser, the server rendered them back, and the page failed to hydrate. Every one is read off `requestAuthority`.
+  - **A rebuild of plugins says it finished** (`@plitzi/sdk-server`): bundles removed under a running server (`tmp/`
+    deleted) were each a warning, "rebuilding…", and their "ready" at a level a project's terminal does not show. It is
+    one episode now: said when noticed, and again when the last is built — how many, how long, which failed.
+  - **`tmp/dev-server.json` records the scheme** (`@plitzi/sdk-server`): `url` is `https` with a certificate, and the
+    file adds the network addresses and the `publicUrl`.
+  - **`public/` is asked about every time** (`@plitzi/sdk-server`): it was cached for an hour — a `.js` or `.css` in it
+    for a year, `immutable` — so a file a project rewrites while it runs arrived stale. It is `no-cache` now, answered
+    `304` by its `ETag` while unchanged; `immutable` stays for what is versioned (the SDK, the plugins).
+
+  ## CLI
+  - **`check`, `shot`, `verify` and `visual` find a server on HTTPS** (`@plitzi/cli`): they rebuilt
+    `http://127.0.0.1:<port>`, so a project serving a certificate had no page checked. They read the URL `npm start`
+    recorded, and take a local certificate on this machine only. A project's `playwright.config.ts` comes from
+    `plitzi upgrade`.
+  - **`verify` runs the project's tests** (`@plitzi/cli`): a step `test`, after the lint, when `package.json` has a
+    `test` script.
+  - **`tsconfig.json` is the project's** (`@plitzi/cli`): the compiler options moved to `plitzi/tsconfig.base.json`, which
+    the CLI keeps up and `tsconfig.json` extends — so a folder of the project's own (`scripts/`, `tools/`) goes in its
+    `include` without changing a file of the CLI's. `plitzi doctor --fix` makes an older `tsconfig.json` extend it,
+    keeping only the options the project changed.
+  - **`doctor --fix` and `upgrade` write as the project's Prettier does** (`@plitzi/cli`): a repaired `tsconfig.json` or
+    `package.json` left `verify`'s format step red.
+  - **`upgrade` renames `usePlitziServiceContext`** (`@plitzi/cli`): with `PlitziServiceProvider` and
+    `PlitziServiceContextValue`, renamed in 0.38.12 with no alias — import, use and the module path that named it.
+  - **`skills update` compares every file** (`@plitzi/cli`): only `SKILL.md` was, so a change in a reference alone was
+    "up to date".
+  - **`NOTES.md`, the project's notes for agents** (`@plitzi/cli`): `AGENTS.md` and `CLAUDE.md` are the CLI's and
+    `upgrade` replaces them, so what a project's own sessions had to know had nowhere to live. `CLAUDE.md` imports
+    `NOTES.md`, `AGENTS.md` sends every agent to it, and nothing the CLI does touches it; `doctor --fix` writes one for
+    a project that has none.
+
+  - **`start:dev-inspect`** (`@plitzi/cli`): a server project's `start:dev` with Node's inspector open on
+    127.0.0.1:9229, so a debugger (VS Code, `chrome://inspect`) attaches to the server, and again after each restart.
+    `plitzi upgrade` adds it; `plitzi runtime add` has it restart on the runtime too.
+  - **`plitzi cert`** (`@plitzi/cli`): HTTPS while developing, for a phone or a tablet on the Wi-Fi — over http its
+    browser gives a page no microphone, camera or clipboard. A certificate from mkcert's local authority for this machine,
+    its network addresses and its `.local` name, in `tmp/tls/`, named in `.env`; what to install on the phone, said.
+  - **A browser project opens to the network** (`@plitzi/cli`): its `vite.config.ts` reads `HOST`, `TLS_CERT` and
+    `TLS_KEY` from `.env`, as a server project does, and writes `tmp/dev-server.json` — the port Vite took and the scheme
+    — so `page check`, `page shot` and `visual` find it on another port or over HTTPS. `plitzi upgrade` brings it.
+
+  ## Docs
+  - **Two plugins share through `state`** (`@plitzi/sdk-authoring` skill): each plugin is a bundle of its own, so a module
+    both import is two copies, and what one keeps there the other never sees.
+  - **`verify --help`** names the project's tests among its steps.
+
+- Updated dependencies [493955a]
+  - @plitzi/plitzi-sdk@0.38.14
+  - @plitzi/sdk-shared@0.38.14
+
+## 0.38.13
+
+### Patch Changes
+
+- v0.38.13
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.38.13
+  - @plitzi/sdk-shared@0.38.13
+
 ## 0.38.12
 
 ### Patch Changes

package/README.md

@@ -210,7 +210,18 @@ a plugin with no `declaration.ts`, no `.env.example` — is printed while develo
 What it wires from the project:
 
 - **The port.** `PORT`, or 8080 — while developing, the next free one from there (`freePort`). `HOST`, loopback by
-  default (`0.0.0.0` in a container). `PUBLIC_URL` is where people reach it, behind a proxy.
+  default (`0.0.0.0` in a container, or for a phone on the Wi-Fi — it prints every address to open, and while it
+  listens on loopback alone, how to open it).
+- **HTTPS.** `TLS_CERT` and `TLS_KEY` in `.env`, the paths of a PEM certificate and its key — what `plitzi cert` makes
+  for this machine and its network addresses — unless `serverOptions.tls` gives one itself. Over plain http a phone's
+  browser gives a page no microphone, camera or clipboard. A network address the certificate does not name (the
+  router handed the machine a new one) is said at boot; this machine's mDNS name (`studio.local`), when the
+  certificate names it, is printed among the addresses, and outlives them.
+- **Where people reach it** — the runtime's `publicUrl`: `PUBLIC_URL` behind a proxy; with `HOST` open to the network,
+  this machine's address there (what a tablet on the Wi-Fi opens, and an OAuth provider sends it back to); this
+  machine's loopback otherwise — `https` whenever it serves a certificate. Serving TLS itself, its
+  own requests to that address (a runtime calling its own MCP) connect to its listener here and take its certificate —
+  exactly that one — however local it is (`reachOwnServer`).
 - **Its plugins.** Every folder of `src/plugins` under its name in camelCase, built from its `index.ts` (or
   `index.tsx`, `pluginEntry`) and rendered
   on the server (`action: 'compile'`), with its server half (`functions/`); every plugin of `vendor/plugins`, run as it
@@ -221,7 +232,8 @@ What it wires from the project:
 - **Its files.** `public/` served as it is, `src/data/` read and never served (`dataDir`), the `kv` in `state/kv.json`
   (`createFileKv`), `PLITZI_SIGNING_SECRET` what `ctx.sign` signs with.
 - **Where it is.** `/health` answers with the space's permanent URL (or the cloud `name`), and `tmp/dev-server.json`
-  records the name, the port and the URL for `plitzi page check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
+  records the name, the port, the URL this machine reaches it at (`https` with a certificate), its network addresses
+  and its `publicUrl` — for `plitzi page check`, `shot`, `verify` and `visual`. A signal closes it (`closeOnSignals`).
 
 While developing — `NODE_ENV` other than `production` — `devMode` and `devReload` are on, and:
 
@@ -496,7 +508,7 @@ createServer({
 });
 ```
 
-Static responses include `ETag`, `Last-Modified`, and `Cache-Control` headers. Subsequent requests with `If-None-Match` receive `304 Not Modified` when the file has not changed. JS, CSS, and font files are served with `Cache-Control: immutable`; all other assets use a 1-hour max-age.
+Static responses include `ETag`, `Last-Modified`, and `Cache-Control` headers. Subsequent requests with `If-None-Match` receive `304 Not Modified` when the file has not changed. Under a versioned URL — the SDK bundle, the plugins, `static` mounts, fonts — JS, CSS and font files are served `immutable` and everything else with a 1-hour max-age. `publicDir` is the project's files by name, which it may rewrite while it runs: `no-cache`, asked about every time and answered `304` while unchanged.
 
 ### Images
 
@@ -1162,7 +1174,7 @@ and every refusal names a machine-readable `reason`, so a client can tell "renew
 
 | Config | Effect |
 |---|---|
-| `cookie` | Name, domain, `SameSite`, `Secure`, the refresh path, the hint suffix. Defaults derive from the request host |
+| `cookie` | Name, domain, `SameSite`, `Secure`, the refresh path, the hint suffix. Defaults derive from the request host: this machine — loopback, a `.localhost` name, a private network address, its mDNS name (`studio.local`), as a phone on the Wi-Fi opens it over http — gets `SameSite=Lax` with no `Secure` and no `Domain`; any other host `SameSite=None; Secure`, shared across its sub-domains |
 | `api.password` | What a password has to be. `minLength` defaults to 8 (NIST SP 800-63B's floor); `validate` is where a breach-list lookup or a strength estimator goes. Applied wherever one is set — signing up, resetting, changing |
 | `api.rateLimit` | May this attempt proceed? **Defaults to an in-memory sliding window**, so no deployment is unthrottled by omission; supply one to put a single counter behind a whole fleet. Called before the password is checked, so a throttled attempt costs no hash |
 | `api.adminPermission` | The global capability the `/auth/admin/*` routes require. Default `userManage` |
@@ -1181,7 +1193,7 @@ write, `04-mysql` over one you do not.
 
 ### Cross-site request forgery
 
-**On by default.** The session cookie defaults to `SameSite=None` off localhost — a space is embedded in an iframe
+**On by default.** The session cookie defaults to `SameSite=None` off this machine and its network — a space is embedded in an iframe
 on somebody else's domain — so the browser attaches it to requests another site caused. That is the attack, and
 `Lax` is what would otherwise prevent it.
 

package/dist/core/auth/session.d.ts

@@ -22,6 +22,13 @@ export type SessionCookieParams = {
  * refuse one on a single-label host) and lax SameSite, because Secure + SameSite=None over plain http is dropped.
  */
 export declare const isLocalHost: (hostname: string) => boolean;
+/**
+ * Whether the host is this machine as another device on its network reaches it: a private address, or the name
+ * mDNS gives it (`studio.local` — one label before `.local`, so a deployment's own `app.example.local` sub-domains,
+ * which share cookies across siblings over https, are not taken for one). Such a server is opened over plain http
+ * from a tablet, and gets the local cookie profile: a Secure cookie written over http is dropped.
+ */
+export declare const isPrivateNetworkHost: (hostname: string) => boolean;
 /**
  * The last two labels of the host, so a session established on one sub-domain is carried by its siblings — an app
  * and the API it talks to are rarely the same host. Local and IP hosts get no domain at all: browsers refuse a
@@ -31,8 +38,9 @@ export declare const registrableDomain: (hostname: string) => string | undefined
 /**
  * Everything about how a session cookie is written, derived from the request host unless the deployment says
  * otherwise. The defaults are the ones a server on a real domain needs: a cookie shared across sub-domains, and
- * SameSite=None + Secure so it survives the app and the API being different hosts. A local server gets the
- * opposite, because Secure + SameSite=None over plain http is dropped by every browser.
+ * SameSite=None + Secure so it survives the app and the API being different hosts. A local server — this machine, or
+ * this machine as its network reaches it — gets the opposite, because Secure + SameSite=None over plain http is
+ * dropped by every browser.
  */
 export declare const sessionCookieParams: (hostname: string, config?: SSRAuthCookie) => SessionCookieParams;
 /** The readable companion cookie's name — the one a page is told to look for (`server.auth.sessionHintCookie`). */

package/dist/core/auth/session.js

@@ -1,4 +1,4 @@
-import { isIP } from "node:net";
+import { BlockList, isIP } from "node:net";
 //#region src/core/auth/session.ts
 var LOCAL_HOSTS = [
 	"localhost",
@@ -10,6 +10,30 @@ var LOCAL_HOSTS = [
 * refuse one on a single-label host) and lax SameSite, because Secure + SameSite=None over plain http is dropped.
 */
 var isLocalHost = (hostname) => LOCAL_HOSTS.includes(hostname) || hostname.endsWith(".localhost");
+/**
+* The addresses a home or office network hands out — RFC 1918, link-local, the shared range a mesh VPN (Tailscale)
+* gives each device, IPv6 unique- and link-local — which a phone on the same Wi-Fi opens a development server on.
+*/
+var PRIVATE_NETWORK = new BlockList();
+PRIVATE_NETWORK.addSubnet("10.0.0.0", 8);
+PRIVATE_NETWORK.addSubnet("172.16.0.0", 12);
+PRIVATE_NETWORK.addSubnet("192.168.0.0", 16);
+PRIVATE_NETWORK.addSubnet("169.254.0.0", 16);
+PRIVATE_NETWORK.addSubnet("100.64.0.0", 10);
+PRIVATE_NETWORK.addSubnet("fc00::", 7, "ipv6");
+PRIVATE_NETWORK.addSubnet("fe80::", 10, "ipv6");
+/**
+* Whether the host is this machine as another device on its network reaches it: a private address, or the name
+* mDNS gives it (`studio.local` — one label before `.local`, so a deployment's own `app.example.local` sub-domains,
+* which share cookies across siblings over https, are not taken for one). Such a server is opened over plain http
+* from a tablet, and gets the local cookie profile: a Secure cookie written over http is dropped.
+*/
+var isPrivateNetworkHost = (hostname) => {
+	const address = hostname.replace(/^\[(.*)\]$/, "$1");
+	const family = isIP(address);
+	if (family === 0) return /^[^.]+\.local$/.test(hostname);
+	return PRIVATE_NETWORK.check(address, family === 4 ? "ipv4" : "ipv6");
+};
 var isIpAddress = (hostname) => isIP(hostname) !== 0;
 /**
 * The last two labels of the host, so a session established on one sub-domain is carried by its siblings — an app
@@ -17,7 +41,7 @@ var isIpAddress = (hostname) => isIP(hostname) !== 0;
 * Domain on a single-label host, and one written for an address would never be sent back to it.
 */
 var registrableDomain = (hostname) => {
-	if (isLocalHost(hostname) || isIpAddress(hostname)) return;
+	if (isLocalHost(hostname) || isIpAddress(hostname) || isPrivateNetworkHost(hostname)) return;
 	const match = /([^.]+\.[^.]+)$/.exec(hostname);
 	return match ? `.${match[1]}` : void 0;
 };
@@ -28,11 +52,12 @@ var resolve = (value, hostname, fallback) => {
 /**
 * Everything about how a session cookie is written, derived from the request host unless the deployment says
 * otherwise. The defaults are the ones a server on a real domain needs: a cookie shared across sub-domains, and
-* SameSite=None + Secure so it survives the app and the API being different hosts. A local server gets the
-* opposite, because Secure + SameSite=None over plain http is dropped by every browser.
+* SameSite=None + Secure so it survives the app and the API being different hosts. A local server — this machine, or
+* this machine as its network reaches it — gets the opposite, because Secure + SameSite=None over plain http is
+* dropped by every browser.
 */
 var sessionCookieParams = (hostname, config = {}) => {
-	const local = isLocalHost(hostname);
+	const local = isLocalHost(hostname) || isPrivateNetworkHost(hostname);
 	return {
 		name: resolve(config.name, hostname, "plitzi_session"),
 		domain: resolve(config.domain, hostname, registrableDomain(hostname)),
@@ -209,4 +234,4 @@ var createSessionCookies = (config) => ({
 	}
 });
 //#endregion
-export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, parseSessionHint, readFlowCookie, readRefreshToken, readRenewalGuard, readSessionHint, readSessionToken, registrableDomain, sessionCookieParams, sessionHintCookieName, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeRenewalGuard, writeSessionCookies };
+export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, isPrivateNetworkHost, parseSessionHint, readFlowCookie, readRefreshToken, readRenewalGuard, readSessionHint, readSessionToken, registrableDomain, sessionCookieParams, sessionHintCookieName, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeRenewalGuard, writeSessionCookies };

package/dist/core/http/stages/sessionRenewal.js

@@ -1,3 +1,4 @@
+import { requestAuthority } from "../../requestParser.js";
 import { readRenewalGuard, readSessionHint, readSessionToken, writeRenewalGuard } from "../../auth/session.js";
 import { isDocumentNavigation, renewForNavigation } from "../../auth/renewal.js";
 //#region src/core/http/stages/sessionRenewal.ts
@@ -9,7 +10,7 @@ var nowInSeconds = () => Math.floor(Date.now() / 1e3);
 * read off the authority rather than taken whole, so a forged `Host` cannot put anything but digits after the name.
 */
 var pageUrl = (req) => {
-	const authority = req.headers[":authority"] ?? req.headers.host ?? "";
+	const authority = requestAuthority(req);
 	const port = /:(\d{1,5})$/u.exec(authority)?.[1];
 	return `${req.protocol}://${req.hostname}${port ? `:${port}` : ""}${req.path}${req.search}`;
 };

package/dist/core/http/stages/signInRoute.js

@@ -1,5 +1,5 @@
-import { readCookies } from "../../auth/credentials.js";
 import { requestOrigin } from "../../requestParser.js";
+import { readCookies } from "../../auth/credentials.js";
 import { safeRedirectTarget } from "../navigation.js";
 import { appendCookies, writeSessionCookies } from "../../auth/session.js";
 import { createHash, randomBytes } from "node:crypto";

package/dist/core/http/stages/static.js

@@ -1,7 +1,7 @@
 import { resolveSdkAssetsDir } from "../../sdkAssets.js";
 import { serveStatic } from "../../staticFiles.js";
 //#region src/core/http/stages/static.ts
-var publicDirStage = (ctx) => ctx.config.publicDir ? serveStatic(ctx.req, ctx.res, ctx.config.publicDir) : false;
+var publicDirStage = (ctx) => ctx.config.publicDir ? serveStatic(ctx.req, ctx.res, ctx.config.publicDir, "revalidate") : false;
 var wellKnownStage = (ctx) => {
 	if (!ctx.req.path.startsWith("/.well-known/")) return false;
 	ctx.res.setStatus(404);

package/dist/core/mimeTypes.d.ts

@@ -1,4 +1,13 @@
 export declare const MIME_TYPES: Record<string, string>;
 export declare const IMMUTABLE_EXTS: Set<string>;
 export declare const getMimeType: (filePath: string) => string;
-export declare const getCacheControl: (filePath: string) => string;
+/**
+ * How long a browser may keep a file without asking again.
+ *
+ * `versioned` is for a directory whose URLs change with their content — the SDK bundle and the plugins, addressed
+ * with `?v=` — where a script or a stylesheet never changes under its URL and is kept for a year. `revalidate` is for
+ * files a project keeps by name and may rewrite while it runs (`public/`): kept, but asked about every time, which
+ * the `ETag` answers with an empty `304` when nothing changed.
+ */
+export type StaticCachePolicy = 'versioned' | 'revalidate';
+export declare const getCacheControl: (filePath: string, policy?: StaticCachePolicy) => string;

package/dist/core/mimeTypes.js

@@ -33,7 +33,8 @@ var IMMUTABLE_EXTS = /* @__PURE__ */ new Set([
 var getMimeType = (filePath) => {
 	return MIME_TYPES[filePath.slice(filePath.lastIndexOf(".")).toLowerCase()] ?? "application/octet-stream";
 };
-var getCacheControl = (filePath) => {
+var getCacheControl = (filePath, policy = "versioned") => {
+	if (policy === "revalidate") return "no-cache";
 	const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
 	return IMMUTABLE_EXTS.has(ext) ? "public, max-age=31536000, immutable" : "public, max-age=3600";
 };

package/dist/core/oauth/authorize.js

@@ -1,3 +1,4 @@
+import { requestAuthority } from "../requestParser.js";
 import { renderConsentPage } from "./consentPage.js";
 import { dropPending, getClient, getPending, putCode, putPending } from "./records.js";
 import { issueContextFor } from "./issueContext.js";
@@ -49,7 +50,7 @@ var renderConsent = (res, view) => {
 * the server is mounted under a prefix, which resolving `/authorize` against it would drop. The same joining the
 * discovery document publishes the endpoint by.
 */
-var authorizeEndpoint = (config, req) => new URL(`${(config.issuer ?? `https://${req.headers.host ?? ""}`).replace(/\/+$/u, "")}${AUTHORIZE_PATH}`);
+var authorizeEndpoint = (config, req) => new URL(`${(config.issuer ?? `https://${requestAuthority(req)}`).replace(/\/+$/u, "")}${AUTHORIZE_PATH}`);
 /** The same endpoint, as the path the grant screen's form posts to — this server's own origin, whatever it is. */
 var authorizeAction = (config) => config.issuer ? `${new URL(config.issuer).pathname.replace(/\/+$/u, "")}${AUTHORIZE_PATH}` : AUTHORIZE_PATH;
 var authorizeUrl = (config, req, params) => {

package/dist/core/requestParser.d.ts

@@ -1,6 +1,12 @@
 import { SSRRequest } from '@plitzi/sdk-shared';
 import { IncomingMessage } from 'node:http';
 export declare const parseRequest: (raw: IncomingMessage) => SSRRequest;
+/**
+ * The host the request was addressed to, port included (`localhost:8080`): HTTP/2's `:authority` — an HTTP/2
+ * request has no `Host` header at all — else `Host`. What names this origin's cookies (`debugCookieName` and the
+ * rest carry the port), so a server reached over HTTP/2 must read it here, never `req.headers.host`.
+ */
+export declare const requestAuthority: (req: Pick<SSRRequest, "headers">) => string;
 /** The public origin the request was addressed to (proxy-aware via x-forwarded-proto, port included), or an empty
  *  string when the request carries no usable authority. */
 export declare const requestOrigin: (req: SSRRequest) => string;

package/dist/core/requestParser.js

@@ -34,10 +34,16 @@ var parseRequest = (raw) => {
 	};
 };
 var AUTHORITY_RE = /^[a-zA-Z0-9.-]{1,253}(?::\d{1,5})?$/u;
+/**
+* The host the request was addressed to, port included (`localhost:8080`): HTTP/2's `:authority` — an HTTP/2
+* request has no `Host` header at all — else `Host`. What names this origin's cookies (`debugCookieName` and the
+* rest carry the port), so a server reached over HTTP/2 must read it here, never `req.headers.host`.
+*/
+var requestAuthority = (req) => req.headers[":authority"] ?? req.headers["host"] ?? "";
 /** The public origin the request was addressed to (proxy-aware via x-forwarded-proto, port included), or an empty
 *  string when the request carries no usable authority. */
 var requestOrigin = (req) => {
-	const authority = req.headers[":authority"] ?? req.headers["host"] ?? "";
+	const authority = requestAuthority(req);
 	return AUTHORITY_RE.test(authority) ? `${req.protocol}://${authority}` : "";
 };
 var headerValue = (value) => (Array.isArray(value) ? value[0] : value)?.trim() ?? "";
@@ -70,4 +76,4 @@ var readRawBytes = (raw) => new Promise((resolve, reject) => {
 });
 var readRawBody = async (raw) => (await readRawBytes(raw)).toString("utf8");
 //#endregion
-export { clientIp, forwardedIp, parseRequest, readRawBody, readRawBytes, requestOrigin };
+export { clientIp, forwardedIp, parseRequest, readRawBody, readRawBytes, requestAuthority, requestOrigin };

package/dist/core/requestParser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/services/action.js

@@ -1,9 +1,9 @@
 import { connectorLookupsOf } from "../configSeam.js";
+import { clientIp, readRawBody } from "../requestParser.js";
 import { handleActionCall } from "../../modules/actions/transport/callHandler.js";
 import { handleActionCatalog } from "../../modules/actions/transport/catalogHandler.js";
 import { handleActionWebhook } from "../../modules/actions/transport/webhookHandler.js";
 import { handleActionCancel } from "../../modules/actions/transport/cancelHandler.js";
-import { clientIp, readRawBody } from "../requestParser.js";
 import { handleAction } from "../../modules/actions/connectorWrite.js";
 //#region src/core/services/action.ts
 var LINEAGE_HEADER = "x-plitzi-action-lineage";

package/dist/core/services/realtime.js

@@ -1,5 +1,5 @@
-import { handleRealtimePublish, handleRealtimeSubscribe } from "../../modules/realtime/handlers.js";
 import { readRawBody } from "../requestParser.js";
+import { handleRealtimePublish, handleRealtimeSubscribe } from "../../modules/realtime/handlers.js";
 import { handleRealtimeSocket } from "../../modules/realtime/socket.js";
 //#region src/core/services/realtime.ts
 /**

package/dist/core/staticFiles.d.ts

@@ -1,2 +1,3 @@
+import { StaticCachePolicy } from './mimeTypes';
 import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
-export declare const serveStatic: (req: SSRRequest, res: SSRResponseHelpers, rootDir: string) => boolean;
+export declare const serveStatic: (req: SSRRequest, res: SSRResponseHelpers, rootDir: string, cache?: StaticCachePolicy) => boolean;

package/dist/core/staticFiles.js

@@ -6,11 +6,11 @@ import fs from "node:fs";
 var compressedFiles = new CompressedFileCache(16777216);
 var isText = (mimeType) => /^text\/|javascript|json|xml|svg/.test(mimeType);
 var buildEtag = (stat) => `"${stat.mtimeMs.toString(36)}-${stat.size.toString(36)}"`;
-var serveFile = (req, res, filePath, stat) => {
+var serveFile = (req, res, filePath, stat, cache) => {
 	const etag = buildEtag(stat);
 	const ifNoneMatch = req.headers["if-none-match"];
 	res.setHeader("ETag", etag);
-	res.setHeader("Cache-Control", getCacheControl(filePath));
+	res.setHeader("Cache-Control", getCacheControl(filePath, cache));
 	res.setHeader("Last-Modified", stat.mtime.toUTCString());
 	if (ifNoneMatch === etag) {
 		res.setStatus(304);
@@ -27,7 +27,7 @@ var serveFile = (req, res, filePath, stat) => {
 	res.send(fs.readFileSync(filePath));
 	return true;
 };
-var serveStatic = (req, res, rootDir) => {
+var serveStatic = (req, res, rootDir, cache = "versioned") => {
 	const relative = req.path.replace(/^\/+/, "");
 	const filePath = path.resolve(rootDir, relative);
 	const resolvedRoot = path.resolve(rootDir);
@@ -41,9 +41,9 @@ var serveStatic = (req, res, rootDir) => {
 	if (stat.isDirectory()) {
 		const indexPath = path.join(filePath, "index.html");
 		if (!fs.existsSync(indexPath)) return false;
-		return serveFile(req, res, indexPath, fs.statSync(indexPath));
+		return serveFile(req, res, indexPath, fs.statSync(indexPath), cache);
 	}
-	return serveFile(req, res, filePath, stat);
+	return serveFile(req, res, filePath, stat, cache);
 };
 //#endregion
 export { serveStatic };

package/dist/helpers/cache/keys.d.ts

@@ -39,6 +39,7 @@ export declare const buildHtmlCacheKey: (accessToken: string | undefined, spaceI
     headers: {
         cookie?: string;
         host?: string;
+        ":authority"?: string;
     };
 }) => string;
 /**

package/dist/helpers/cache/keys.js

@@ -1,3 +1,4 @@
+import { requestAuthority } from "../../core/requestParser.js";
 import { ssrPaintedCookieName } from "../paintedCookie.js";
 import { readCookie } from "../readCookie.js";
 import { flagsCookieName } from "@plitzi/sdk-shared/flags";
@@ -54,9 +55,9 @@ var buildHtmlCacheKey = (accessToken = "anonymous", spaceId, environment, revisi
 		revision: String(revision),
 		flags: flagsVersionOf(req),
 		theme: themeFromCookies(req.headers.cookie) ?? "",
-		painted: readCookie(req.headers.cookie, ssrPaintedCookieName(req.headers.host)) ?? "",
-		debugHidden: readCookie(req.headers.cookie, debugCookieName(req.headers.host)) === "false" ? "debug-off" : "",
-		forcedFlags: readCookie(req.headers.cookie, flagsCookieName(req.headers.host)) ?? "",
+		painted: readCookie(req.headers.cookie, ssrPaintedCookieName(requestAuthority(req))) ?? "",
+		debugHidden: readCookie(req.headers.cookie, debugCookieName(requestAuthority(req))) === "false" ? "debug-off" : "",
+		forcedFlags: readCookie(req.headers.cookie, flagsCookieName(requestAuthority(req))) ?? "",
 		hostname: req.hostname,
 		path: req.path,
 		search: req.search

package/dist/helpers/flagOverrides.d.ts

@@ -13,6 +13,7 @@ export declare const forcedFlagsFor: (req: {
     headers: {
         cookie?: string;
         host?: string;
+        ":authority"?: string;
     };
 }, authorized: boolean | (() => Promise<boolean>)) => Promise<Record<string, boolean> | undefined>;
 /** Both layers this server answers for, for one request. */
@@ -20,6 +21,7 @@ export declare const requestFlagOverrides: (config: Pick<SSRServerConfig, "flags
     headers: {
         cookie?: string;
         host?: string;
+        ":authority"?: string;
     };
 }, space: {
     spaceId: number;

package/dist/helpers/flagOverrides.js

@@ -1,3 +1,4 @@
+import { requestAuthority } from "../core/requestParser.js";
 import { forcedFlagsFromCookies } from "@plitzi/sdk-shared/flags";
 //#region src/helpers/flagOverrides.ts
 /** The deployment's own layer for one space: `config.flags`, asked per space when it is a function. */
@@ -8,7 +9,7 @@ var serverFlagsFor = (config, space) => typeof config.flags === "function" ? con
 * mean reading the space.
 */
 var forcedFlagsFor = async (req, authorized) => {
-	const forced = forcedFlagsFromCookies(req.headers.cookie, req.headers.host);
+	const forced = forcedFlagsFromCookies(req.headers.cookie, requestAuthority(req));
 	if (Object.keys(forced).length === 0) return;
 	return (typeof authorized === "boolean" ? authorized : await authorized()) ? forced : void 0;
 };

package/dist/modules/project/serveProject.d.ts

@@ -49,7 +49,7 @@ export type ServeProjectOptions = ServeProjectBase & ({
 /** The project's server, running. */
 export type ServedProject = {
     server: SSRServer;
-    /** Where it listens, as `tmp/dev-server.json` records it: `http://127.0.0.1:<port>`. */
+    /** Where this machine reaches it, as `tmp/dev-server.json` records it: `http://127.0.0.1:<port>`, `https` with a certificate. */
     url: string;
     /** Stops watching, closes the server and the runtime — what a signal does, for a caller that stops it itself. */
     close: () => Promise<void>;
@@ -62,7 +62,8 @@ export type ServedProject = {
  * space authored. A refusal of any of the three is printed as it is — the message is the whole report, every problem
  * and its fix, and a stack would only point inside the SDK — and the process exits with 1. What it serves:
  *
- * - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default;
+ * - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default; HTTPS
+ *   with `TLS_CERT` and `TLS_KEY` (`plitzi cert`), unless the project's options give `tls` themselves;
  * - its plugins: every folder of `src/plugins` built from its source and server-rendered, every one of `vendor/plugins`
  *   as it was built, each with its server half;
  * - its code: `src/functions/`, and the space's runtime (`src/runtime/` — compiled under `dist/` when the server runs

package/dist/modules/project/serveProject.js

@@ -1,23 +1,27 @@
 import { consoleLogger } from "../../helpers/serverLog.js";
 import { isFleetWorker } from "../../core/server/fleet/role.js";
 import { loadFunctions } from "../functions/load.js";
-import { createServer } from "../../core/createServer.js";
+import { createServer as createServer$1 } from "../../core/createServer.js";
 import { closeOnSignals } from "../../core/server/closeOnSignals.js";
 import { freePort } from "../../core/freePort.js";
 import { createCloudAdapters } from "../../adapters/cloudAdapters.js";
 import { createJsonAdapters } from "../../adapters/jsonAdapters.js";
 import { createFileKv } from "../actions/runtime/fileKv.js";
 import { credentialsFromEnv } from "../actions/runtime/credentials.js";
+import { reachOwnServer } from "../runtime/inside.js";
 import { loadRuntime, loadRuntimeModule } from "../runtime/bundle.js";
 import { serveRuntime } from "../runtime/stages.js";
 import { projectPlugins, watchProjectPlugins } from "./plugins.js";
 import { createSpaceFailure } from "./spaceFailure.js";
 import { watchSpace } from "./watchSpace.js";
 import { fleetKv } from "../../core/server/fleet/stores.js";
-import { networkInterfaces } from "node:os";
+import { X509Certificate } from "node:crypto";
+import { hostname, networkInterfaces } from "node:os";
+import { isIP } from "node:net";
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { assertProjectLayout, layoutFindingText } from "@plitzi/sdk-shared/project/layout";
+import { localNetworkName, networkAddresses } from "@plitzi/sdk-shared/project/network";
 import { DATA_DIR, DEV_SERVER_FILE, FUNCTIONS_DIR, KV_FILE, PROJECT_TMP, PUBLIC_DIR, RUNTIME_BUNDLE, RUNTIME_ENTRY } from "@plitzi/sdk-shared/project/paths";
 import { projectModule, projectRoot } from "@plitzi/sdk-shared/project/root";
 import { EMPTY_SCHEMA } from "@plitzi/sdk-shared/schema/schemaConstants";
@@ -68,10 +72,53 @@ var LOOPBACK = /* @__PURE__ */ new Set([
 	"::1",
 	"localhost"
 ]);
+var ANY_ADDRESS = /* @__PURE__ */ new Set(["0.0.0.0", "::"]);
+/** An address as a URL writes it: an IPv6 one in brackets. */
+var urlHost = (address) => address.includes(":") ? `[${address}]` : address;
+/** Where this machine reaches a server listening on `host`: its loopback, unless it listens on one address only. */
+var localAddress = (host) => host === "::1" ? host : LOOPBACK.has(host) || ANY_ADDRESS.has(host) ? "127.0.0.1" : host;
 /** Where another device reaches a server listening on `host`: this machine's own network addresses, when it is open. */
-var networkUrls = (host, port) => {
+var addressesFor = (host) => {
 	if (LOOPBACK.has(host)) return [];
-	return (host === "0.0.0.0" || host === "::" ? Object.values(networkInterfaces()).flat().flatMap((entry) => entry && entry.family === "IPv4" && !entry.internal ? [entry.address] : []) : [host]).map((address) => `http://${address}:${String(port)}/`);
+	return ANY_ADDRESS.has(host) ? networkAddresses(networkInterfaces()) : [host];
+};
+/**
+* HTTPS with no code of the project's: `TLS_CERT` and `TLS_KEY` in `.env`, the PEM certificate and its key — what
+* `plitzi cert` makes, for a tablet on the Wi-Fi, whose browser gives a page served over http no microphone, camera,
+* clipboard or service worker. Relative to the project's root.
+*/
+var tlsFromEnv = (root) => {
+	const { TLS_CERT: cert, TLS_KEY: key } = process.env;
+	if (!cert && !key) return;
+	if (!cert || !key) throw new Error("Set both TLS_CERT and TLS_KEY in .env — the certificate and its key — or neither.");
+	const read = (name, file) => {
+		try {
+			return readFileSync(path.resolve(root, file));
+		} catch {
+			throw new Error(`${name} in .env is "${file}", which cannot be read — \`plitzi cert\` makes the pair.`);
+		}
+	};
+	return {
+		cert: read("TLS_CERT", cert),
+		key: read("TLS_KEY", key)
+	};
+};
+/**
+* What another device opens this server by, its certificate considered: every network address, and this machine's
+* mDNS name when the certificate names it. The addresses the certificate does not name are said apart — a device that
+* opens one is refused the page, which happens when the router hands this machine a new address.
+*/
+var reachedBy = (addresses, tls) => {
+	if (!tls || addresses.length === 0) return {
+		names: addresses,
+		unnamed: []
+	};
+	const certificate = new X509Certificate(tls.cert);
+	const name = localNetworkName(hostname());
+	return {
+		names: [...addresses, ...certificate.checkHost(name) ? [name] : []],
+		unnamed: addresses.filter((address) => (isIP(address) ? certificate.checkIP(address) : certificate.checkHost(address)) === void 0)
+	};
 };
 var actionLookups = (actions, connectors, credentials) => ({
 	getAction: (_spaceId, actionId) => Promise.resolve(actions.find((entry) => entry.id === actionId)),
@@ -118,8 +165,24 @@ var startProject = async (options) => {
 	if (developing) for (const warning of layout) console.warn(`[layout] ${layoutFindingText(warning)}`);
 	const host = process.env.HOST ?? "127.0.0.1";
 	const port = process.env.PORT ? Number(process.env.PORT) : developing ? await freePort(8080, host) : 8080;
-	/** Where people reach this server: `PUBLIC_URL` behind a proxy, its own address otherwise. */
-	const publicUrl = (process.env.PUBLIC_URL ?? `http://127.0.0.1:${String(port)}`).replace(/\/+$/, "");
+	const tls = serverOptions.tls ?? tlsFromEnv(root);
+	const scheme = tls ? "https" : "http";
+	const localUrl = `${scheme}://${urlHost(localAddress(host))}:${String(port)}`;
+	const reached = reachedBy(addressesFor(host), tls);
+	const network = reached.names.map((address) => `${scheme}://${urlHost(address)}:${String(port)}`);
+	/**
+	* Where people reach this server: `PUBLIC_URL` behind a proxy; open to the network, the address another device uses
+	* — what an OAuth provider sends a tablet back to; this machine's otherwise.
+	*/
+	const publicUrl = (process.env.PUBLIC_URL ?? network.at(0) ?? localUrl).replace(/\/+$/, "");
+	if (tls && process.env.PUBLIC_URL === void 0) await reachOwnServer({
+		publicUrl,
+		listener: {
+			host: localAddress(host),
+			port
+		},
+		cert: tls.cert
+	});
 	const { space, failure, name } = await spaceToServe(options, developing, root);
 	const plugins = await projectPlugins(root);
 	const held = options.space ? { ...space ? { documents: {
@@ -159,10 +222,11 @@ var startProject = async (options) => {
 		});
 		return keptKv;
 	});
-	const server = createServer({
+	const server = createServer$1({
 		logLevel: process.argv.includes("--verbose") ? "info" : "warn",
 		logger: consoleLogger,
 		...serverOptions,
+		...tls ? { tls } : {},
 		port,
 		devMode: serverOptions.devMode ?? developing,
 		devReload: serverOptions.devReload ?? serverOptions.devMode ?? developing,
@@ -183,17 +247,19 @@ var startProject = async (options) => {
 		}
 	}, { preAuth: [spaceFailure.stage, ...runtime ? [runtime.stage] : []] });
 	await server.listen(port, host);
-	const url = `http://127.0.0.1:${String(port)}`;
 	if (speaks) {
 		mkdirSync(path.join(root, PROJECT_TMP), { recursive: true });
 		writeFileSync(path.join(root, DEV_SERVER_FILE), `${JSON.stringify({
 			name,
 			port,
-			url
+			url: localUrl,
+			network,
+			publicUrl
 		}, null, 2)}\n`);
-		console.log(`pages on ${url}/`);
-		const network = networkUrls(host, port);
-		if (network.length > 0) console.log(`also on ${network.join(", ")} — anyone on this network can open it (HOST=${host})`);
+		console.log(`pages on ${localUrl}/`);
+		if (network.length > 0) console.log(`also on ${network.map((address) => `${address}/`).join(", ")} — anyone on this network can open it (HOST=${host})`);
+		else if (developing && LOOPBACK.has(host)) console.log("only this machine opens it: HOST=0.0.0.0 in .env opens it to your network (a phone on the Wi-Fi)");
+		if (reached.unnamed.length > 0) console.warn(`[tls] the certificate does not name ${reached.unnamed.join(", ")}: a device that opens it there is refused — \`plitzi cert\` makes one for this machine as it is now`);
 	}
 	const watching = developing ? [...held ? [watchSpace(root, (authored) => {
 		held.documents = authored;
@@ -209,7 +275,7 @@ var startProject = async (options) => {
 	const stopListening = closeOnSignals({ close });
 	return {
 		server,
-		url,
+		url: localUrl,
 		close: async () => {
 			stopListening();
 			await close();
@@ -224,7 +290,8 @@ var startProject = async (options) => {
 * space authored. A refusal of any of the three is printed as it is — the message is the whole report, every problem
 * and its fix, and a stack would only point inside the SDK — and the process exits with 1. What it serves:
 *
-* - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default;
+* - the port: `PORT`, or 8080 — the next free one from there while developing; `HOST`, loopback by default; HTTPS
+*   with `TLS_CERT` and `TLS_KEY` (`plitzi cert`), unless the project's options give `tls` themselves;
 * - its plugins: every folder of `src/plugins` built from its source and server-rendered, every one of `vendor/plugins`
 *   as it was built, each with its server half;
 * - its code: `src/functions/`, and the space's runtime (`src/runtime/` — compiled under `dist/` when the server runs

package/dist/modules/realtime/socket.js

@@ -1,6 +1,6 @@
+import { requestOrigin } from "../../core/requestParser.js";
 import { warnRealtime } from "./failure.js";
 import { admit, answer, connectionFor, publishFrom } from "./handlers.js";
-import { requestOrigin } from "../../core/requestParser.js";
 import { frameText } from "../../helpers/wsFrame.js";
 //#region src/modules/realtime/socket.ts
 /** The largest frame a page may send: well above the largest message a channel may declare, and bounded. */

package/dist/modules/rsc/handler.js

@@ -1,4 +1,5 @@
 import { serverLog } from "../../helpers/serverLog.js";
+import { requestAuthority } from "../../core/requestParser.js";
 import { requestFlagOverrides } from "../../helpers/flagOverrides.js";
 import { resolveDebugAuthorization } from "../../helpers/debugAuthorization.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
@@ -114,7 +115,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache, signal) => {
 	* A tester forcing flags from the dev tools sees data for features nobody else has on — and must never be handed a
 	* slice resolved without them. Their refreshes go around the cache both ways, like a draft's.
 	*/
-	const forcingFlags = Object.keys(forcedFlagsFromCookies(req.headers.cookie, req.headers.host)).length > 0;
+	const forcingFlags = Object.keys(forcedFlagsFromCookies(req.headers.cookie, requestAuthority(req))).length > 0;
 	const uncached = previewing || forcingFlags;
 	const ttlMs = config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc;
 	const isAuthenticated = !!req.ctx.user;

package/dist/modules/runtime/elsewhere.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/runtime/inside.d.ts

@@ -13,3 +13,24 @@ export declare const reachSpaceInside: ({ publicUrl, insideUrl }: {
     publicUrl: string;
     insideUrl: string;
 }) => Promise<void>;
+export type OwnServer = {
+    /** Where people reach this server — the address its code writes and fetches. */
+    publicUrl: string;
+    /** Where this machine reaches it: the address and port it listens on. */
+    listener: {
+        host: string;
+        port: number;
+    };
+    /** The certificate it serves, PEM: the one a connection to it has to present to be taken as this server. */
+    cert: string | Buffer;
+};
+/**
+ * A self-hosted server serving TLS itself, reached from its own process — the runtime calling its own MCP, a function
+ * calling a route of its own space: every request to its public address connects to its listener on this machine.
+ *
+ * Its certificate is usually a local one (mkcert, for a tablet on the Wi-Fi), which the browsers on that network were
+ * told to trust and Node was not, so these requests failed whatever the address said. They are taken when the peer
+ * presents exactly this server's certificate — its fingerprint, not a chain — and refused otherwise; nothing else the
+ * process reaches is verified any less.
+ */
+export declare const reachOwnServer: ({ publicUrl, listener, cert }: OwnServer) => Promise<void>;

package/dist/modules/runtime/inside.js

@@ -1,4 +1,6 @@
+import { X509Certificate } from "node:crypto";
 import net from "node:net";
+import tls from "node:tls";
 //#region src/modules/runtime/inside.ts
 /** Headers as a dispatch carries them — a record, name/value pairs flattened into one list, or pairs — plus one more. */
 var withHeader = (headers, name, value) => {
@@ -12,6 +14,12 @@ var withHeader = (headers, name, value) => {
 	};
 };
 /**
+* How every OTHER host is reached once one of these dispatchers is the process's: as Node's own `fetch` reaches it,
+* over HTTP/1.1. An undici connector offers HTTP/2 by default, and an answer that came back over h2 reached Node's
+* `fetch` without its `content-encoding` — so nothing decoded it, and every API that compresses read as Brotli bytes.
+*/
+var elsewhere = (undici) => undici.buildConnector({ allowH2: false });
+/**
 * The space's own public address, reached from inside the network this runtime runs in: every request this process
 * makes to the space's host — `fetch` and `WebSocket` alike, which share Node's dispatcher — connects to `insideUrl`
 * instead, over plain HTTP, the space's host and the public protocol kept (`X-Forwarded-Proto`). It is the path a
@@ -26,10 +34,11 @@ var reachSpaceInside = async ({ publicUrl, insideUrl }) => {
 	const outside = new URL(publicUrl);
 	const inside = new URL(insideUrl);
 	if (inside.protocol !== "http:") throw new Error(`A space is reached from inside over plain HTTP, not ${inside.protocol} (${insideUrl})`);
-	const { Agent, buildConnector, setGlobalDispatcher } = await import("undici");
+	const undici = await import("undici");
+	const { Agent, setGlobalDispatcher } = undici;
 	const port = Number(inside.port || 80);
 	const protocol = outside.protocol.replace(":", "");
-	const connect = buildConnector({});
+	const connect = elsewhere(undici);
 	setGlobalDispatcher(new Agent({ connect: (options, callback) => {
 		if (options.hostname !== outside.hostname) {
 			connect(options, callback);
@@ -43,5 +52,44 @@ var reachSpaceInside = async ({ publicUrl, insideUrl }) => {
 		headers: withHeader(options.headers, "x-forwarded-proto", protocol)
 	} : options, handler)));
 };
+/**
+* A self-hosted server serving TLS itself, reached from its own process — the runtime calling its own MCP, a function
+* calling a route of its own space: every request to its public address connects to its listener on this machine.
+*
+* Its certificate is usually a local one (mkcert, for a tablet on the Wi-Fi), which the browsers on that network were
+* told to trust and Node was not, so these requests failed whatever the address said. They are taken when the peer
+* presents exactly this server's certificate — its fingerprint, not a chain — and refused otherwise; nothing else the
+* process reaches is verified any less.
+*/
+var reachOwnServer = async ({ publicUrl, listener, cert }) => {
+	const outside = new URL(publicUrl);
+	const outsidePort = outside.port || (outside.protocol === "https:" ? "443" : "80");
+	const own = new X509Certificate(cert).fingerprint256;
+	const undici = await import("undici");
+	const { Agent, setGlobalDispatcher } = undici;
+	const connect = elsewhere(undici);
+	setGlobalDispatcher(new Agent({ connect: (options, callback) => {
+		if (options.hostname !== outside.hostname || (options.port || outsidePort) !== outsidePort) {
+			connect(options, callback);
+			return;
+		}
+		const socket = tls.connect({
+			host: listener.host,
+			port: listener.port,
+			...net.isIP(outside.hostname) ? {} : { servername: outside.hostname },
+			ALPNProtocols: ["http/1.1"],
+			rejectUnauthorized: false
+		});
+		socket.once("secureConnect", () => {
+			if (socket.getPeerX509Certificate()?.fingerprint256 !== own) {
+				socket.destroy();
+				callback(/* @__PURE__ */ new Error(`${outside.host} answered with a certificate that is not this server's`), null);
+				return;
+			}
+			callback(null, socket);
+		});
+		socket.once("error", (error) => callback(error, null));
+	} }));
+};
 //#endregion
-export { reachSpaceInside };
+export { reachOwnServer, reachSpaceInside };

package/dist/modules/runtime/ownServer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/ssr/prepareRender.js

@@ -1,3 +1,4 @@
+import { requestAuthority } from "../../core/requestParser.js";
 import { requestFlagOverrides } from "../../helpers/flagOverrides.js";
 import { authorizesDebugging } from "../../helpers/debugAuthorization.js";
 import { SPACE_TOKEN_PARAM } from "../../core/auth/credentials.js";
@@ -119,7 +120,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* so does the space itself (`settings.debugMode`) — an owner inspecting their own published site. The space is read
 	* from what this server loaded, never from the request, so a visitor has no say in it.
 	*/
-	const debugRendered = resolveDebugMode(debugAuthorized, readCookie(req.headers.cookie, debugCookieName(req.headers.host)));
+	const debugRendered = resolveDebugMode(debugAuthorized, readCookie(req.headers.cookie, debugCookieName(requestAuthority(req))));
 	/**
 	* The runs this render's server elements started, handed to a page that may debug them — and to no other.
 	*
@@ -159,7 +160,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 	* travels as the SDK's `state`, the starting `runtime.state`, in the render and in the payload alike, or the client
 	* would hydrate other markup. Only the keys the space declares, and only with `keepState` on.
 	*/
-	const paintedState = schema?.settings.keepState ? paintedStateFor(req.headers.cookie, ssrPaintedCookieName(req.headers.host), paintedKeys(schema.settings)) : void 0;
+	const paintedState = schema?.settings.keepState ? paintedStateFor(req.headers.cookie, ssrPaintedCookieName(requestAuthority(req)), paintedKeys(schema.settings)) : void 0;
 	/**
 	* The two layers of the space's flags this server answers for. Its own (`config.flags`), asked per space when it
 	* serves several; and the ones a tester forced from the dev tools, read from their cookie — only for a page allowed

package/dist/plugins/manager.d.ts

@@ -12,6 +12,8 @@ export declare class PluginManager {
     private readonly devMode;
     /** Who is told what each built plugin was built from — a dev server's watcher (`watchPluginSources`). */
     private readonly sourceListeners;
+    /** The bundles being built again because they vanished from disk under this server — see `restore`. */
+    private restoring?;
     constructor(plugins: Record<string, PluginSource>, cacheDir?: string, ttlMs?: number, devMode?: boolean);
     /**
      * Tells `listener` the files every built plugin was built from — those built so far, at once, and each one built or
@@ -108,6 +110,13 @@ export declare class PluginManager {
      */
     prepareAll(): Promise<void>;
     prepare(name: string): Promise<PluginEntry | null>;
+    /**
+     * Bundles that vanished from disk under a running server are built again as one episode: said once when the first
+     * is noticed and once when the last is built — how many, how long, which failed — at the level it was noticed at.
+     * Said per plugin, it was a warning for each and a "ready" for each at a level a project's terminal does not show,
+     * so the rebuild never said it had finished.
+     */
+    private restore;
     private build;
     getEntries(names: string[]): Promise<PluginEntry[]>;
     getComponents(): Record<string, unknown>;

package/dist/plugins/manager.js

@@ -11,6 +11,8 @@ import path from "node:path";
 var META_FILE = "meta.json";
 var DEFAULT_TTL_MS = 6048e5;
 var DEFAULT_CACHE_DIR = "tmp/.sdk-plugins";
+/** How long a rebuild of vanished bundles waits, once none is pending, for another of the same render to be noticed. */
+var RESTORE_SETTLE_MS = 100;
 /** One hash over every input's path and content — a file gone counts as changed, like a file edited. */
 var digestOf = async (files) => {
 	const hash = createHash("sha256");
@@ -49,6 +51,8 @@ var PluginManager = class {
 	devMode = false;
 	/** Who is told what each built plugin was built from — a dev server's watcher (`watchPluginSources`). */
 	sourceListeners = /* @__PURE__ */ new Set();
+	/** The bundles being built again because they vanished from disk under this server — see `restore`. */
+	restoring;
 	constructor(plugins, cacheDir, ttlMs, devMode = false) {
 		assertPluginSources(plugins);
 		this.plugins = plugins;
@@ -262,6 +266,7 @@ var PluginManager = class {
 		if (isComponentSource(source) && !source.js) return this.toEntry(key, false, void 0, source.props);
 		if (!isComponentSource(source) && source.action === "cdn") return this.toRemoteEntry(key, source);
 		const cached = this.mem.get(key);
+		let missing = false;
 		if (cached && !this.isExpired(cached.compiledAt)) {
 			if (await this.fileExists(path.join(this.pluginDir(key), "index.js"))) {
 				/**
@@ -278,8 +283,9 @@ var PluginManager = class {
 					force: true
 				});
 			} else {
-				serverLog.warn("SSR", `Plugin "${key}" cache invalidated: output file missing, rebuilding…`);
+				serverLog.info("SSR", `Plugin "${key}" output missing, rebuilding…`);
 				this.mem.delete(key);
+				missing = true;
 			}
 		}
 		const meta = await this.readMeta(key);
@@ -315,8 +321,44 @@ var PluginManager = class {
 		}
 		const promise = this.build(key, source).finally(() => this.inflight.delete(key));
 		this.inflight.set(key, promise);
+		if (missing) this.restore(key, promise);
 		return promise;
 	}
+	/**
+	* Bundles that vanished from disk under a running server are built again as one episode: said once when the first
+	* is noticed and once when the last is built — how many, how long, which failed — at the level it was noticed at.
+	* Said per plugin, it was a warning for each and a "ready" for each at a level a project's terminal does not show,
+	* so the rebuild never said it had finished.
+	*/
+	restore(key, build) {
+		if (!this.restoring) {
+			this.restoring = {
+				started: Date.now(),
+				pending: /* @__PURE__ */ new Set(),
+				rebuilt: 0,
+				failed: []
+			};
+			const where = path.relative(process.cwd(), this.outputDir) || this.outputDir;
+			serverLog.warn("SSR", `Plugin bundles missing from ${where}: building them again…`);
+		}
+		const episode = this.restoring;
+		clearTimeout(episode.closing);
+		episode.pending.add(key);
+		build.then((entry) => {
+			episode.pending.delete(key);
+			if (entry) episode.rebuilt += 1;
+			else episode.failed.push(key);
+			if (episode.pending.size > 0) return;
+			episode.closing = setTimeout(() => {
+				if (this.restoring !== episode || episode.pending.size > 0) return;
+				this.restoring = void 0;
+				const seconds = ((Date.now() - episode.started) / 1e3).toFixed(1);
+				const failed = episode.failed.length > 0 ? ` — ${String(episode.failed.length)} failed (${episode.failed.join(", ")}), said above` : "";
+				serverLog.warn("SSR", `Plugin bundles built again: ${String(episode.rebuilt)} in ${seconds}s${failed}`);
+			}, RESTORE_SETTLE_MS);
+			episode.closing.unref();
+		});
+	}
 	async build(name, source) {
 		const dir = this.pluginDir(name);
 		await fs.mkdir(dir, { recursive: true });

package/dist/runtime.d.ts

@@ -9,7 +9,8 @@ export type { SpaceRuntime, SpaceRuntimeContext, SpaceRuntimeEndpoint, SpaceRunt
 export { RUNTIME_DESCRIBE_PATH, startSpaceRuntime } from './modules/runtime/host';
 export type { SpaceRuntimeDescription, SpaceRuntimeHost, SpaceRuntimeHostOptions } from './modules/runtime/host';
 export { inspectRuntime, loadRuntime, loadRuntimeModule, MAX_RUNTIME_BUNDLE_BYTES, packRuntime, runtimeBundleId } from './modules/runtime/bundle';
-export { reachSpaceInside } from './modules/runtime/inside';
+export { reachOwnServer, reachSpaceInside } from './modules/runtime/inside';
+export type { OwnServer } from './modules/runtime/inside';
 export { createRuntimeRunner } from './modules/runtime/runner';
 export { createRuntimeProxyStage, runtimeEndpointsStage, serveRuntime } from './modules/runtime/stages';
 export type { RuntimeProxyConfig, RuntimeTarget, ServedRuntime } from './modules/runtime/stages';

package/dist/runtime.js

@@ -1,7 +1,7 @@
 import { defineRuntime, endpointFor, endpointProblem } from "./modules/runtime/contract.js";
-import { reachSpaceInside } from "./modules/runtime/inside.js";
+import { reachOwnServer, reachSpaceInside } from "./modules/runtime/inside.js";
 import { createRuntimeRunner } from "./modules/runtime/runner.js";
 import { RUNTIME_DESCRIBE_PATH, startSpaceRuntime } from "./modules/runtime/host.js";
 import { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, runtimeBundleId } from "./modules/runtime/bundle.js";
 import { createRuntimeProxyStage, runtimeEndpointsStage, serveRuntime } from "./modules/runtime/stages.js";
-export { MAX_RUNTIME_BUNDLE_BYTES, RUNTIME_DESCRIBE_PATH, createRuntimeProxyStage, createRuntimeRunner, defineRuntime, endpointFor, endpointProblem, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, reachSpaceInside, runtimeBundleId, runtimeEndpointsStage, serveRuntime, startSpaceRuntime };
+export { MAX_RUNTIME_BUNDLE_BYTES, RUNTIME_DESCRIBE_PATH, createRuntimeProxyStage, createRuntimeRunner, defineRuntime, endpointFor, endpointProblem, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, reachOwnServer, reachSpaceInside, runtimeBundleId, runtimeEndpointsStage, serveRuntime, startSpaceRuntime };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.12",
+  "version": "0.38.14",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.12",
-    "@plitzi/sdk-shared": "0.38.12",
+    "@plitzi/plitzi-sdk": "0.38.14",
+    "@plitzi/sdk-shared": "0.38.14",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/reference/layouts.md

@@ -145,6 +145,16 @@ Every page is now its content and nothing else, and every page is guaranteed the
   by name — `"{{ not (apiContainer_feed.products|find('slug', navigation.routeParams.slug)) }}"`. The page renders as
   written: show its "not found" part with `visible`.
 
+## A screen that fills the window
+
+A dashboard or a board — one screen whose panels scroll on their own — says so on its page: `documentScroll:
+'locked'` holds the document still, so a finger dragged on a tablet no longer pulls the whole page and bounces it
+back. Give the shell the window's height (`height: '100dvh'`) and `overflow: 'auto'` to each part that scrolls; what
+does not fit is cut off, with nothing a visitor can scroll to reach it. `'noBounce'` keeps a page scrolling without
+the rubber band or pull-to-refresh. Either is written onto the document only while that page is on it, and only when
+the document is the space's own — never the site a widget sits on, nor a space drawn inside another. Not an
+`html, body` rule in `customCss`, which holds every page and the site the space is a widget on.
+
 ## Styles follow the same rule
 
 - A role used on several pages is ONE class (`panelCard`, `pageTitle`), declared in the module that owns the area and

package/skills/plitzi-authoring/reference/plugins.md

@@ -64,19 +64,19 @@ const NebulaRun = ({ shipColor = 'amber', best = 0, className }: NebulaRunProps)
 ## Writing to the space
 
 A plugin that produces something the page shows — a score, a selection — writes it to `runtime.state`, where every
-binding reads it:
+binding reads it — and where two plugins share it, each being a bundle of its own (a module both import is two):
 
 ```ts
 import { getStateManager } from '@plitzi/plitzi-sdk';
 
 const state = getStateManager();
 state.setStateByKey('arcadeBest', Math.max(score, Number(state.state.arcadeBest ?? 0)));
-const stop = state.subscribe(next => save(next));      // called after every change; call `stop()` to leave
+const stop = state.subscribe(next => save(next));      // after every change; `stop()` to leave
 ```
 
 `state` is the current value, `setState` replaces it (or takes an updater), `setStateByKey` writes one key,
-`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once. With the space's `keepState`
-on ([kept state](kept-state.md)), what a plugin writes there — its layout, a choice — is back after a reload too.
+`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once. With `keepState` on
+([kept state](kept-state.md)), what a plugin writes there is back after a reload.
 
 ## Laying out the space's elements