@plitzi/sdk-server 0.38.9 → 0.38.11

package/CHANGELOG.md

@@ -1,5 +1,268 @@
 # @plitzi/sdk-server
 
+## 0.38.11
+
+### Patch Changes
+
+- cadf70a: - **`server.cache.invalidate` drops what a page is rendered from** (`@plitzi/sdk-server`): the pages, the RSC answers
+  and the schema data they are rendered from go together. It dropped the pages alone, and the next request rendered
+  the same page again from the schema still cached under the same key — a publish that invalidated the space changed
+  nothing until the schema's TTL ran out. `clear()` and `size` cover the three. A filter on `hostname` drops the schema
+  data too, which belongs to no one host. `server.cache` is `null` only when nothing is cached (`cacheTtlMs: 0` and
+  `rsc.cacheTtlMs: 0`).
+
+  ## Style inspector
+  - **Finds a property** (`@plitzi/sdk-style`): a search above the categories narrows them to the ones that edit what was
+    typed — a CSS name in any order of its words (`border radius` finds the four corners), a category's title, or a
+    common word for it (`bg`, `rounded`) — opens them, and shows the advanced rows when the match lives there. Escape
+    clears it. The categories' properties live in one list (`categoryKeys.ts`) that the dots, the advanced hint and the
+    search all read.
+  - **Rows that fit**: a section with more than two controls puts its label above them and lays them out in as many
+    columns as the panel is wide, instead of one row where every label was cut (`Appearan…`, `Cell Spaci…`, the five
+    scroll-snap controls). A row's label column is 80px.
+  - **Where a value comes from, said quietly**: the label's tint keeps its four meanings — set here, from a token, bound
+    to data, inherited — without the solid blocks of colour; hovering says which (an inherited one names its selector and
+    breakpoint) and that a click resets it, the click shows it by striking the label through. The footer's info icon
+    holds the legend, and its arrow folds every category.
+  - **What is being edited**: an "Editing … › Hover" line under the pickers whenever the rules being written are not the
+    selector's plain ones, with a button back to them. Ancestor, pseudo-element and condition fold behind a toggle —
+    never while one is in use.
+  - The class being edited is the panel's one strong mark (violet), the element's type defaults a softer one; the tools'
+    tabs fit the panel and are reachable from the keyboard.
+
+  - **Lists edited in a popover, all alike**: box and text shadows, transforms, transitions and filters share one row
+    (the CSS it writes, a swatch, a remove button) and one popover (a title, a close button, Escape, the focus moved
+    into it). What none of them could read is now kept and edited as text instead of being replaced with a default — a
+    token for the whole value, `drop-shadow(…)`, `url(#…)`.
+  - **Values read the way CSS writes them**: a shadow with two, three or four lengths and its color on either end;
+    `rgba(…)` inside text shadows and filters no longer split; negative shadow offsets accepted; a transition with any
+    of its parts left out; brightness, contrast and saturation past 1. Transition presets are written as CSS — the
+    preset names (`easeInQuad`) made the browser drop the whole declaration — the curve can be dragged into one of your
+    own, and the preview stops with the editor. `font-color` (not CSS) became `color`.
+  - **Background layers keep what they hold**: a repeating gradient (now a switch), a radial gradient's explicit size, a
+    token or `image-set()` as a layer (a "Custom (CSS)" layer), a one-value position read as CSS reads it (`20%` is
+    `20% center`), lists shorter than the layers repeated as CSS repeats them, an unset repeat read as tiling, two-position
+    stops, negative angles — every one of them was rewritten on the next edit of any layer. Defaults are no longer
+    written back, and "Token values" no longer bakes resolved tokens into the layers.
+  - **A layer's editor in two halves** — what it draws, then where it goes (size, position, tile, attachment, clip,
+    which now offers `text`). The gradient's stops sit on one bar, each a handle that drags or moves with the arrow keys;
+    the stop's color and position below it. Previews and swatches resolve the space's tokens.
+  - Spacing tells margin (dashed, outside) from padding; Border's sides are labelled and readable in the dark theme; a
+    class's menu says what each action does to whom; the Style Manager opens at a size that holds both columns.
+
+  ## Builder
+  - **Shortcuts**: `?` shows every shortcut the builder answers to — the same list the "Nothing selected" card teaches
+    from — and ⌘\ / Ctrl+\ hides both side panels for the canvas alone and brings back the ones that were open. Both
+    work with the canvas focused.
+  - **Panels keep their width**: each side panel opens at the width it was left at; the right one starts at 380px.
+  - **Text no smaller than 11px** across the builder's panels (it went down to 10px in fifty places).
+
+  ## Realtime
+  - **A page hears what it sent when it asks to** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`):
+    `publishOn('room', 'react', data, { echo: true })`, `useChannel().publish(type, data, { echo: true })` and the
+    channel's `publish` callback (`echo`) hand the message back to the page that sent it too, once the server took it —
+    stamped like everyone's, with `echo: true`, its `from` the channel's `me`. Without it a page still never hears its
+    own messages, and the docs said "every page on its topic hears it": they now say every OTHER page. Presence never
+    echoes.
+  - **A topic is opened only once it names one** (`@plitzi/sdk-elements`): `useChannel` — and so the `channel` element —
+    opens a topic only when a channel of the space covers it, by the same `matchChannel` the server decides by. A topic
+    written from data that has not arrived (`room:` while its provider loads, or its template still as text) asked the
+    server for both, was refused with a 403 and a console error on every load, and is now waited for.
+  - **Pages that watch** (`@plitzi/sdk-server`, `@plitzi/cli`): a connection whose page carries the `plitzi-observer`
+    cookie hears its topics and says nothing on them — no `$join`, no presence, its publishes taken and dropped.
+    `page check`, `page shot` and `verify` load pages that way, so checking a live site is no longer a visitor walking
+    into a room (`X walked in`, a member more in every picture). `--presence` takes part as a visitor does.
+
+  ## Authoring
+  - **`template-in-value`** (refused): a `{{ }}` inside an attribute that is an object or a list — a provider's
+    `input`, a list's `items`, a plugin's settings — is never evaluated: only an attribute that is text is interpolated,
+    and the page server reads attributes as saved. A provider's `input` also replaced the route param of the same name
+    the action was already given, so `input: { room: '{{ navigation.routeParams.room }}' }` reached the task as `""` and
+    the page answered 404; its refusal says the action is handed the page's route and query params already. Anything
+    else is a binding on the attribute. `mockData`, a sample, is not held to it.
+  - **Rules on top of a class need no `id`** (`class: [card, { gap: '6px' }]`): they are named after the id the element
+    is given, written or not. `modifier-without-id` is gone; a one-off tweak no longer needs a name nothing reads.
+  - **Typed list rows have `inTemplate`**, as untyped ones do, and `bindTemplate`, `visibleWhen`, `hiddenWhen` and
+    `variantFrom` take a typed source's path as well as a name: turning a list typed broke every template of its rows.
+  - **`when({ field, operator: 'empty' })`** takes no `value` (nor `notEmpty`), as flows.md recommends; it did not
+    type-check.
+  - **Data-driven colours**: a style binding on a custom property (`{ to: '--who', category: 'style' }`) is written as
+    named — it was camel-cased into `who` — so a class reads `var(--who, var(--muted))`. A style binding's value carrying
+    `;` or braces is not written: the page server writes inline styles as text, and such a value added declarations of
+    its own. `binding-target-unknown` on `style` or a CSS property says to bind it in the `style` category.
+  - `unknown-attribute` for `decorative` on an `svg` or a `fontAwesome` says what it means: without a `label` it is
+    already hidden from screen readers.
+
+  - **A folder nobody declared says where to declare it**: `folder-undeclared` (a page, a layout, a folder's parent)
+    ends with `pageFolders: [{ id, name }]` on the space, and with the line of the `pageFamily` that wrote the page. A
+    folder starts its pages' addresses (`/docs/quickstart`), so a misspelt one is never declared on the author's behalf.
+    The skill's `pageFamily` example declares its folder.
+  - **A tag is an element**: a `subType` this element has not but another has — `container({ subType: 'ol' })` — names
+    that element (`list({ subType: 'ol' })`) instead of the value two letters away (`dl`). Read off the elements'
+    declarations, for every element and tag.
+  - **A `pageFamily`'s body is written once**: `repeated-shape` and `repeated-on-pages` no longer count the same part of
+    each page of one family as copies — they were offering a component for exactly what the docs recommend. Copies within
+    one page, or across pages written one by one, are still offered.
+  - **Colour emoji are not text to `page check`**: a character painted in its own colours (🎲, `❤️`, a keycap, a ZWJ
+    sequence) is left out of the contrast measure, which compared `color` with the tile behind it and failed `verify`
+    in the theme whose text colour was close to the tile. A symbol drawn as text (✓, ★) is still measured.
+
+  - **`declared-callback-target`** (refused): a value beside `on` in `declaredCallback(…, { on, date })` — written as
+    `openModal`'s target reads — was read nowhere, and the step ran without it. Refused, with the `params` it goes in
+    (`{ on: 'calendar', params: { date } }`) and whether it is one of the callback's declared params.
+  - The skill's list rows show the typed form beside the untyped one: with `items` typed by a sample, `r.item` is a path
+    (`from: r.item.title`), not text to put in a template string.
+  - **`slot-not-class`** (refused): rules written in place in a slot — `slots: { error: [fieldError, { color }] }`, past
+    the type in JavaScript or a spec rebuilt from JSON — were taken for a declaration with no rules, and `authorSpace`
+    failed later with `Cannot read properties of undefined (reading 'desktop')`, naming nothing. Refused where the slot
+    is written, naming the slot and the element, with the `styles()` declaration to hand instead.
+
+  ## CLI
+  - **`page shot --click` (and `--clip`, `--wait-for`, `--scroll-to`, `--steps`) takes any selector**: a value that is
+    not an element's name (letters, digits, `-`, `_`) is a selector, CSS or Playwright's own (`button:has-text("Orbit")`).
+    It was wrapped as a name, and an invalid selector ended the command with Playwright's stack trace; it is now refused
+    with the reason.
+
+  - **`plitzi functions add <package>`**: a package the functions use comes with them, as a function carries its
+    dependencies. Installed in the project, it is bundled (web APIs only, minified, its licence kept) into
+    `src/functions/vendor/<package>.js`, with a `.d.ts` re-exporting the installed package's types, imported as
+    `./vendor/<package>.js` and pushed, built and run with the rest — nothing is resolved anywhere else, so the builder,
+    the sandbox and the push are unchanged. A package that reaches Node (`fs`, `node:*`) is refused, naming what it
+    reached; one past the functions' 1 MB is too; one that reads `process`/`Buffer` is warned about. The build's refusal
+    of a package import now names the command.
+  - **`page shot` targets**: a bare word is an element's name, or — no element named so — a tag (`textarea`); resolved on
+    the loaded page for `--click`, `--clip`, `--scroll-to`, `--wait-for` and `--steps`. In `--steps`, `type` takes a
+    quoted element with spaces (`type ".panel textarea" hola`) — it was cut at its first space and typed the rest — and
+    fails when the click leaves no field focused, rather than sending the keys to the page's shortcuts.
+
+  ## Server
+  - **`server.listen()` resolves once the port answers** (`@plitzi/sdk-server`) — in a fleet, once the first worker
+    does. `serveProject` writes `tmp/dev-server.json` and says `pages on …` after it, not on the line after `listen`:
+    for about 0.4 s a tool trusting the line (CI, Playwright's `webServer`, `page check`) was refused. A port it cannot
+    take still ends the process, or goes to `onListenError`, and the promise is then never resolved.
+  - **Runs set for later** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`, `@plitzi/sdk-authoring`, `@plitzi/plitzi-builder`):
+    a turn that runs out, a bot's move, a hold that lapses — one run starting one of the space's actions in N seconds,
+    whether or not a page is still open. The action says it may be with a **`later` trigger** (no access rule: the run
+    that set it was let in); a flow sets it with `flow.later { action, in, input, key }`, a function with
+    `ctx.later({ … })`, and `flow.cancelLater` / `ctx.cancelLater(key)` drops it. A `key` names it: set again under the
+    same key, the one still waiting is replaced — the newer of two set at once, on every replica — and a running one is
+    left. It is a job of the queue schedules use: due by the store's clock (0 s to 30 days, about a second late at most),
+    once across replicas, retried, shown in Automations → Queue. Refused before anything is queued, with why: no `later`
+    trigger, one switched off, a time out of range, a key that is not one, a server with no jobs. A plugin's functions
+    set none. `ActionJobQueue` gains `cancelPending({ spaceId, key, olderThan? })` and jobs a `key`: the memory, Mongo
+    and MySQL queues implement it, and the shared contract tests it. **MySQL**: `action_jobs` gains `job_key` (and the
+    `action_jobs_key` index), added on first use; with `createTables: false`, run that statement of
+    `mysqlJobSchemaUpgrades()`. A queue of a deployment's own implements `cancelPending` (`09-schedules` shows one).
+  - **A project's `kv` file has one holder** (`@plitzi/sdk-server`): `createFileKv` takes `<file>.lock` with its pid;
+    a second process — another `npm start`, a `--watch` left running — is refused, naming the first (`the server of
+"orbita", on port 8080`) instead of both writing their whole map over each other's changes, and a lock whose process
+    is gone is taken over. `close()` writes what is pending and lets go. A server with `workers` opens the file once, in
+    the primary, and its workers reach it through the fleet (`fleetKv`): each used to open a copy of its own.
+  - **A self-hosted project's credentials** (`@plitzi/sdk-server`, `@plitzi/cli`): `serveProject` answers
+    `getCredential` from `PLITZI_CREDENTIALS` in `.env` — one JSON object, credential id → its keys — so
+    `ctx.fetch({ credential })`, a connector and an `http.request` step work on the project's own server, not only in
+    `functions dev`. The same variable for both (it was `PLITZI_FUNCTIONS_CREDENTIALS`, read by the CLI alone); a value
+    that is not that object is refused with how to write it, instead of every credential going missing.
+  - **`HOST` beyond loopback says where to open it**: with `HOST=0.0.0.0`, `serveProject` prints the machine's network
+    addresses — what a tablet on the same Wi-Fi opens — and that anyone on that network can. `.env.example` names `HOST`
+    and `PLITZI_CREDENTIALS`.
+
+  ## SDK
+  - **`useElementSize(ref)`** (`@plitzi/plitzi-sdk`): the size a plugin's own box is drawn at, followed as it changes —
+    what `useDisplayMode()` cannot say: a tablet held upright is `mobile` by the window and still a week wide by the
+    plugin's box. `undefined` until measured, so the server's page and the hydrated one agree. The breakpoints are
+    unchanged.
+  - The functions docs say how a task's `params` types (how the builder edits them: `codemirror-json`) and an action's
+    `input` types (what the value is: `json`) correspond.
+
+- Updated dependencies [cadf70a]
+  - @plitzi/plitzi-sdk@0.38.11
+  - @plitzi/sdk-shared@0.38.11
+
+## 0.38.10
+
+### Patch Changes
+
+- 200da2f: - **`focus-on-field-box`** (`@plitzi/sdk-authoring`): a warning for a `focus` or `focus-visible` state on a text
+  field's or a select's `input` slot. That slot is the box the field is drawn in, a `<div>` that never takes focus, so
+  the rule was never seen and a keyboard user tabbing to the field found no ring. The fix it names: `'focus-within'` on
+  the same class, or the state on the `field` slot.
+  - **`modalContainer` says how it is laid out** (`@plitzi/sdk-elements`): its description now names its slots and how
+    they sit — the dim layer and the dialog side by side, not one inside the other; the dialog centred by `top`/`left`
+    50% and a `translate`. A space styled the dim layer as a flex container to place the dialog, which moved nothing.
+  - **A field shows where the keyboard is** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`): a text field's or a select's
+    box is ringed (`2px solid currentColor`) while the field inside has keyboard focus, and a textarea while it has. No
+    text field or select showed any focus at all: the box had `outline: none`, and the field inherited it. One class of
+    specificity, so whatever a space writes about the outline wins; never in the builder's canvas, where the selection is
+    the ring. The field no longer inherits the box's outline — the box draws it.
+  - **The dim layer of a modal and a dialog is `rgb(0 0 0 / 50%)`** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`), not
+    black at `opacity: 0.5`: the default looks the same, and a colour a space gives the layer is drawn as it is — it was
+    halved. A space that set its own colour sees it darker: the one it wrote.
+  - **`required-message-unused`** (`@plitzi/sdk-authoring`): a warning for a `requiredMessage` on a field nothing requires —
+    since 0.38.9 a field is optional unless `required: true`, so the message is never shown and an empty answer is sent.
+    The formControl's description, the cheat sheet and the forms recipe say the default.
+  - **A page's title can say its record** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`,
+    `@plitzi/sdk-authoring`): `seoTitle` and `seoDescription` may be templates over the page's `runtime: 'server'`
+    providers (its layouts' too) and `navigation` — `'{{ apiContainer_post.title }} — Blog'`. The server evaluates them
+    as it writes the head, from the answers it already has; the browser evaluates the same over `rsc.data`, so the tab
+    follows a navigation from record to record. One that reads anything else — a browser provider, `state` — is refused
+    (`page-template`): it was written into the head as it was, braces included. A declaration's `serverTemplates` names
+    the attributes the page server evaluates against a context of its own (a page's title and description, a provider's
+    `notFound`): the element runtime leaves them as written — interpolated where the page renders, a `|default(…)`
+    resolved to its fallback before the head could read the providers — and the authoring lint reads the same list.
+  - **A page says when its address shows nothing** (`@plitzi/sdk-server`, `@plitzi/sdk-authoring`): `notFound` on the
+    page, one expression over the same answers its title reads — `"{{ not (apiContainer_feed.topics|find('slug',
+navigation.routeParams.slug)) }}"` — sends it with status 404, rendered as written. A provider's own `notFound` reads
+    only its answer, and one in a layout is every page's: a record read from the layout had no way to say it was not
+    there, and the page answered 200.
+  - **The Export keeps the flows of a plugin hosted by `custom`** (`@plitzi/sdk-authoring`): `specFromSpace` judged such
+    an element by `custom`'s own triggers and callbacks, and dropped a flow on the component's event (`onChange` on an
+    editor) as one "a custom never fires" — the space read back was not the space written.
+  - **`page check` reads every word on the page, in the colour the browser paints it** (`@plitzi/sdk-authoring`): what a
+    plugin draws inside an element of the space is measured too, named by the element and a selector; the measure is
+    WCAG's contrast (under 2:1 is unreadable), not "nearly the same colour"; and a colour the browser answers as
+    `oklch()`, `oklab()` or `color(srgb …)` — every token and every `color-mix()` — is read as that, where it was read as
+    `rgb()` numbers and came out near black. A plugin's dark-on-dark status line passed as "nothing wrong".
+  - **`verify` checks every theme the space can be painted in** (`@plitzi/cli`): light and dark, unless the space says
+    light only — "48 checks at 1440 and 390 px, light and dark". A page unreadable in the dark theme passed in the light
+    one; a failure names the theme it was found in.
+  - **`plitzi upgrade` says where fields became optional** (`@plitzi/cli`): for a project last upgraded before 0.38.9,
+    each `formControl(…)` with no `required`, at its file and line — said, never written. And a `.gitkeep` is asked for
+    only in a folder with nothing else in it: `upgrade` wrote one beside code, and `doctor` called it missing once deleted
+    as AGENTS.md asks ("nothing unused") — the three now say the same.
+  - **`devMode` and `devReload` are the project's** (`@plitzi/sdk-server`): `src/config/serverOptions.ts` may set them,
+    over `NODE_ENV`, which they still follow when left out. A deployment started without `NODE_ENV` (a container's `CMD`)
+    says `devMode: false`, and a public action answers with its output alone.
+  - **`page shot --from load`** (`@plitzi/cli`): `--frames` start as soon as the page's HTML is in, not once it settles —
+    an entrance that plays while the page loads had ended before the first picture.
+  - **`heavy-animation` says where each animation is** (`@plitzi/sdk-authoring`): the class and its variant, state or
+    slot — or the `customCss` rule — and writes the fix against that selector. It said "in `customCss`" for an animation
+    declared on a class's variant, and offered `.glow`, a class no space has.
+  - **`page shot --steps`** (`@plitzi/cli`): an interaction played step by step — `click`, `type`, `press`, `wait`,
+    `wait-for`, `shot [label]`, `frames <n> [ms]`, separated by `;` or written in a file (`@file`) — each picture labelled
+    with its step and the time since the first, and said when nothing changed since the one before. A queue filling, a
+    restart, an opening frame by frame took a Playwright script of the project's own. Targets take Playwright's selectors
+    too (`text=Saved`).
+  - **A space's task may take a `number` param** (`@plitzi/sdk-server`): saved functions refused it ("a type the builder
+    cannot draw") while a project's server ran it, so code that worked self-hosted failed on the platform — and the
+    builder draws one, a callback's. A step's params now arrive as the types the task declares, on every server: a
+    `number` written as text is the number, a `boolean` written `'true'` is `true`, as the browser reads a callback's.
+  - **`page shot --as <username>`** (`@plitzi/cli`): signs in first, as `page check --as` does, the password from
+    `PLITZI_CHECK_PASSWORD` in `.env`. A page for signed-in visitors was pictured as the sign-in page it sent the browser
+    to, without a word; `page shot` now says when the page sent it elsewhere, and that the picture is of that page.
+  - **A capture is of the page at rest** (`@plitzi/sdk-mcp`): the local screenshot client takes every picture with
+    `prefers-reduced-motion: reduce`, as the browser pod now does — the declared motion and a space's own keyframes that
+    honour the query are shown finished. A splash still covering its page, or an arrival caught halfway, was what a
+    thumbnail or a `plitzi_look` showed of a page that animates as it loads.
+  - **The server renders in the visitor's theme, not only the class** (`@plitzi/sdk-shared`): `ThemeProvider` set the
+    starting theme from a layout effect, which never runs on a server, so a page was drawn from the theme store's own
+    start — `{{ theme.resolved }}` was `light` under a `<html class="dark">`, and whatever named the scheme (a picture's
+    address, a `when` rule) was swapped for the other one as the page hydrated. The theme a host supplies (the cookie) is
+    now the server's snapshot of the store, and the hydration's; the shared store is never written on the server.
+- Updated dependencies [200da2f]
+  - @plitzi/plitzi-sdk@0.38.10
+  - @plitzi/sdk-shared@0.38.10
+
 ## 0.38.9
 
 ### Patch Changes

package/README.md

@@ -610,7 +610,7 @@ Responses include an `X-Cache: HIT` or `X-Cache: MISS` header for observability.
 
 ### Cache manager
 
-`server.cache` exposes programmatic cache control, useful when content changes and you need to invalidate entries without restarting the server.
+`server.cache` exposes programmatic cache control, useful when content changes and you need to invalidate entries without restarting the server. It reaches every cache a render is kept in — the pages, the RSC answers and the schema data they are rendered from — so a page invalidated is rendered again from the space as it is now, never from the copy it was cached with.
 
 ```ts
 const server = createServer({ cacheTtlMs: 300_000, adapters });
@@ -631,7 +631,7 @@ server.cache?.clear();
 console.log(server.cache?.size);
 ```
 
-`server.cache` is `null` when caching is disabled (`cacheTtlMs: 0`).
+`server.cache` is `null` when nothing is cached (`cacheTtlMs: 0` and `rsc.cacheTtlMs: 0`). `size` counts the entries of all three caches.
 
 #### `CacheFilter`
 
@@ -641,7 +641,7 @@ console.log(server.cache?.size);
 | `environment` | `string` | Match entries for this environment. |
 | `hostname` | `string` | Match entries for this hostname. |
 
-All fields are optional and combined with AND logic. Calling `invalidate()` with no filter (or an empty object) clears the entire cache.
+All fields are optional and combined with AND logic. Calling `invalidate()` with no filter (or an empty object) clears the entire cache. The schema data belongs to no one host, so a filter on `hostname` drops it too — the host's pages are rendered from it — and it is read again on the next miss.
 
 ## Plugins
 

package/dist/auth.js

@@ -1,8 +1,8 @@
+import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
 import { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, parseSessionHint, readFlowCookie, readRefreshToken, readSessionHint, readSessionToken, sessionCookieParams, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
 import { createCsrf, csrfFailureMessage } from "./core/auth/csrf.js";
 import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
 import { isDocumentNavigation, renewForNavigation } from "./core/auth/renewal.js";
-import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
 import { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from "./core/auth/domains.js";
 import { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from "./core/auth/authorize.js";
 import { generateToken, hashPassword, verifyPassword } from "./core/auth/passwords.js";

package/dist/core/auth/createAuth.js

@@ -1,7 +1,7 @@
+import { createCarriers, presentedOrigin } from "./credentials.js";
 import { createSessionCookies, sessionCookieParams } from "./session.js";
 import { createCsrf } from "./csrf.js";
 import { applySessionOutcome, authPolicyRules, authRoutes } from "./routes.js";
-import { createCarriers, presentedOrigin } from "./credentials.js";
 import { createAuthorizer } from "./authorize.js";
 import { createTokens } from "./tokens.js";
 import { createAuthApi } from "./api.js";

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

@@ -1,7 +1,7 @@
+import { readCookies } from "../../auth/credentials.js";
 import { requestOrigin } from "../../requestParser.js";
 import { safeRedirectTarget } from "../navigation.js";
 import { appendCookies, writeSessionCookies } from "../../auth/session.js";
-import { readCookies } from "../../auth/credentials.js";
 import { createHash, randomBytes } from "node:crypto";
 //#region src/core/http/stages/signInRoute.ts
 /**

package/dist/core/server/baseServer.js

@@ -40,18 +40,19 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 		}) },
 		listen(port, host = "0.0.0.0") {
 			if (plan.requested !== void 0 && role !== "worker") serverLog.warn(label, `${plan.requested} workers asked for, ${plan.count} cores to run them on: starting ${plan.count}`);
-			if (role === "primary") {
+			if (role === "primary") return new Promise((resolve) => {
 				(parts.beforeFork?.() ?? Promise.resolve()).catch((error) => serverLog.error(label, "preparing for the workers failed", error)).then(async () => {
 					const { startFleet } = await import("./fleet/supervisor.js");
 					if (closed) return;
 					fleet = startFleet(plan.count, label);
 					serverLog.info(label, `${plan.count} workers on ${host}:${port}`);
+					await fleet.listening;
+					resolve();
 				}).catch((error) => {
 					serverLog.error(label, "the workers could not start", error);
 					process.exitCode = 1;
 				});
-				return;
-			}
+			});
 			const handler = makeHandlerForPort(port);
 			({primary, h3} = buildTransport(config, handler, port, label));
 			connections = watchConnections(primary);
@@ -68,9 +69,13 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 				process.exitCode = 1;
 				process.exit(1);
 			});
-			primary.listen(port, host, () => {
-				serverLog.info(label, `${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
-				parts.onListen?.();
+			const bound = primary;
+			return new Promise((resolve) => {
+				bound.listen(port, host, () => {
+					serverLog.info(label, `${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
+					parts.onListen?.();
+					resolve();
+				});
 			});
 		},
 		async close() {

package/dist/core/server/fleet/stores.d.ts

@@ -1,5 +1,12 @@
 import { HostedStore } from './channel';
 import { FleetStoreName } from './link';
+import { ActionKvAdapter } from '../../../modules/actions/types';
+/**
+ * A `kv` the deployment makes — a file — opened by ONE process of a fleet and reached by the rest: made in the primary
+ * (or the single process there is), and in a worker the primary's, over the channel. Made in every worker instead,
+ * each would hold its own copy of the file and write it over the others'.
+ */
+export declare const fleetKv: (make: () => ActionKvAdapter) => ActionKvAdapter;
 /**
  * What the primary keeps for its workers: the same in-memory defaults a single server makes for itself, made here
  * once — when a worker first asks — so the fleet has one of each rather than one per worker.

package/dist/core/server/fleet/stores.js

@@ -1,19 +1,33 @@
 import { JOB_QUEUE_METHODS, createMemoryJobQueue } from "../../../modules/actions/jobs/memoryQueue.js";
 import { hostable } from "./channel.js";
+import { fleetStore } from "./link.js";
 import { KV_METHODS, createMemoryKv } from "../../../modules/actions/runtime/memoryKv.js";
 import { DRAFT_STORE_METHODS, createMemoryDraftStore } from "../../../modules/ssr/preview.js";
 import { RATE_LIMIT_METHODS, createMemoryRateLimit } from "../../auth/throttle.js";
 //#region src/core/server/fleet/stores.ts
+/** The `kv` a deployment keeps somewhere of its own — a file, a database — when the primary is the one that opened it. */
+var deploymentKv;
+/**
+* A `kv` the deployment makes — a file — opened by ONE process of a fleet and reached by the rest: made in the primary
+* (or the single process there is), and in a worker the primary's, over the channel. Made in every worker instead,
+* each would hold its own copy of the file and write it over the others'.
+*/
+var fleetKv = (make) => {
+	const remote = fleetStore("actions.kv", KV_METHODS);
+	if (remote) return remote;
+	deploymentKv = make();
+	return deploymentKv;
+};
 /**
 * What the primary keeps for its workers: the same in-memory defaults a single server makes for itself, made here
 * once — when a worker first asks — so the fleet has one of each rather than one per worker.
 */
 var FLEET_STORES = {
-	"actions.kv": hostable(createMemoryKv, KV_METHODS),
+	"actions.kv": hostable(() => deploymentKv ?? createMemoryKv(), KV_METHODS),
 	"realtime.grants": hostable(createMemoryKv, KV_METHODS),
 	"actions.jobs": hostable(() => createMemoryJobQueue(), JOB_QUEUE_METHODS),
 	"ssr.drafts": hostable(createMemoryDraftStore, DRAFT_STORE_METHODS),
 	"auth.rateLimit": hostable(() => ({ check: createMemoryRateLimit() }), RATE_LIMIT_METHODS)
 };
 //#endregion
-export { FLEET_STORES };
+export { FLEET_STORES, fleetKv };

package/dist/core/server/fleet/supervisor.d.ts

@@ -1,4 +1,6 @@
 export type Fleet = {
+    /** Resolved once a worker takes connections: the port answers from then on. */
+    listening: Promise<void>;
     stop: () => Promise<void>;
 };
 /**

package/dist/core/server/fleet/supervisor.js

@@ -37,7 +37,10 @@ var startFleet = (count, label, exit = (code) => process.exit(code)) => {
 		if (shared.count !== count) throw new Error(`[${label}] this process already runs ${shared.count} workers; every server in it must ask for the same number`);
 		shared.servers += 1;
 		const state = shared;
-		return { stop: () => leave(state) };
+		return {
+			listening: state.listening,
+			stop: () => leave(state)
+		};
 	}
 	const workers = /* @__PURE__ */ new Set();
 	const restarts = /* @__PURE__ */ new Set();
@@ -45,6 +48,10 @@ var startFleet = (count, label, exit = (code) => process.exit(code)) => {
 	let deaths = [];
 	let served = false;
 	let stopping = false;
+	let listened = () => void 0;
+	const listening = new Promise((resolve) => {
+		listened = resolve;
+	});
 	const stopAll = () => {
 		restarts.forEach((timer) => clearTimeout(timer));
 		restarts.clear();
@@ -62,6 +69,7 @@ var startFleet = (count, label, exit = (code) => process.exit(code)) => {
 		workers.add(worker);
 		worker.once("listening", () => {
 			served = true;
+			listened();
 		});
 		worker.once("exit", (code, signal) => {
 			workers.delete(worker);
@@ -89,13 +97,17 @@ var startFleet = (count, label, exit = (code) => process.exit(code)) => {
 	const state = {
 		count,
 		servers: 1,
+		listening,
 		stop: async () => {
 			stopping = true;
 			await stopAll();
 		}
 	};
 	shared = state;
-	return { stop: () => leave(state) };
+	return {
+		listening,
+		stop: () => leave(state)
+	};
 };
 /** The workers stop when the last server of this process that started them closes. */
 var leave = async (state) => {

package/dist/core/server/pageServer.js

@@ -37,7 +37,7 @@ var createPageServer = (config, services, extensions) => {
 	reportReactBuild(config.devMode);
 	if (config.preview?.enabled && !config.draftStore) config.draftStore = fleetStore("ssr.drafts", DRAFT_STORE_METHODS) ?? createMemoryDraftStore();
 	const caches = createServerCaches(htmlTtlMs, config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc);
-	const cache = caches.html ? buildCacheManager(caches.html) : null;
+	const cache = caches.html || caches.rsc ? buildCacheManager(caches) : null;
 	const renderFn = config.templateFn ?? compileTemplate();
 	const pluginManager = new PluginManager(normalizePlugins(config.plugins ?? {}), config.pluginsCacheDir, config.pluginsTtlMs, config.devMode);
 	const plugins = {

package/dist/functions-api.d.ts

@@ -94,6 +94,15 @@ export declare type FunctionContext = {
     grant: (topic: string, ttlSeconds?: number) => Promise<string>;
     /** Takes a grant back — or every grant for the topic, naming none. */
     revoke: (topic: string, grant?: string) => Promise<void>;
+    /**
+     * Starts one of the space's actions — one with a `later` trigger — in so many seconds, on the server, whether or not a
+     * page is still open: a turn that runs out, a bot's move, a hold that lapses. A `key` names it: set again under the
+     * same key, the one still waiting is replaced. Answers the job and when it is due (epoch ms, by the queue's clock).
+     * `ctx.later({ action: 'game.timeout', in: 45, input: { room }, key: 'turn:' + room })`.
+     */
+    later: (request: LaterRequest) => Promise<LaterAnswer>;
+    /** Drops what waits under `key` — the timer of a game that ended — and answers how many. */
+    cancelLater: (key: string) => Promise<number>;
     /**
      * One file of the space's data — a project's `src/data/<file>` — parsed, as of the version the run belongs to: what
      * a page must not carry, read here and answered only as far as it is shown. Read-only. `ctx.data('products.json')`.
@@ -293,6 +302,26 @@ declare type KvListRange = {
     order?: 'asc' | 'desc';
 };
 
+/** The job it became, and when it is due — epoch ms, by the queue's clock. */
+declare type LaterAnswer = {
+    id: string;
+    at: number;
+};
+
+/** What a run asks to start later: one of the space's actions, in so many seconds, with its input — and a name. */
+declare type LaterRequest = {
+    /** The action, by its identifier. It says it may be started this way with a `later` trigger. */
+    action: string;
+    /** Seconds from now, by the queue's clock — whole or not, from 0 to a month. */
+    in: number;
+    input?: Record<string, unknown>;
+    /**
+     * What it is known by in this space: setting another under the same key replaces the one still waiting — a turn's
+     * timer moved on by a move — and `cancelLater(key)` drops it. The one already running is left be.
+     */
+    key?: string;
+};
+
 /** Where a limit stands after counting one more: whether that one was within it, and how many are left. */
 declare type RateCount = {
     allowed: boolean;

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

@@ -1,3 +1,10 @@
-import { TtlCache } from './TtlCache';
+import { ServerCaches } from './serverCaches';
 import { CacheManager } from '@plitzi/sdk-shared';
-export declare const buildCacheManager: <T>(store: TtlCache<T>) => CacheManager;
+/**
+ * `server.cache` over every cache a render is kept in: the pages, the RSC answers, and the space as read for both.
+ *
+ * All three, because they hold one change between them. Dropping the pages alone left the space they were rendered
+ * from, and the next request rendered the page that had just been dropped from it — an invalidation that cleared
+ * every page and changed none of them.
+ */
+export declare const buildCacheManager: ({ html, rsc, offlineData }: ServerCaches) => CacheManager;

package/dist/helpers/cache/cacheManager.js

@@ -1,26 +1,50 @@
-import { readHtmlCacheKey } from "./keys.js";
+import { readHtmlCacheKey, readOfflineDataCacheKey, readRscCacheKey } from "./keys.js";
 //#region src/helpers/cache/cacheManager.ts
-var buildCacheManager = (store) => ({
-	invalidate(filter) {
-		if (!filter || Object.keys(filter).length === 0) {
-			const count = store.size;
-			store.clear();
-			return count;
+/**
+* Whether an entry is one the filter names. An entry that is not any one host's (the space as read for a render) is
+* named by a filter on a host too: the page that host serves is rendered from it, and dropping the page while keeping
+* it would render the same page again.
+*/
+var matches = (facts, filter) => (filter.spaceId === void 0 || facts.spaceId === String(filter.spaceId)) && (filter.environment === void 0 || facts.environment === filter.environment) && (filter.hostname === void 0 || facts.hostname === void 0 || facts.hostname === filter.hostname);
+var clearCounted = (store) => {
+	const count = store.size;
+	store.clear();
+	return count;
+};
+/**
+* `server.cache` over every cache a render is kept in: the pages, the RSC answers, and the space as read for both.
+*
+* All three, because they hold one change between them. Dropping the pages alone left the space they were rendered
+* from, and the next request rendered the page that had just been dropped from it — an invalidation that cleared
+* every page and changed none of them.
+*/
+var buildCacheManager = ({ html, rsc, offlineData }) => {
+	const caches = [
+		...html ? [{
+			store: html,
+			read: readHtmlCacheKey
+		}] : [],
+		...rsc ? [{
+			store: rsc,
+			read: readRscCacheKey
+		}] : [],
+		...offlineData ? [{
+			store: offlineData,
+			read: readOfflineDataCacheKey
+		}] : []
+	];
+	return {
+		invalidate(filter) {
+			if (!filter || Object.keys(filter).length === 0) return caches.reduce((count, { store }) => count + clearCounted(store), 0);
+			return caches.reduce((count, { store, read }) => count + store.invalidateWhere((key) => matches(read(key), filter)), 0);
+		},
+		clear() {
+			caches.forEach(({ store }) => store.clear());
+		},
+		get size() {
+			return caches.reduce((count, { store }) => count + store.size, 0);
 		}
-		return store.invalidateWhere((key) => {
-			const { spaceId: keySpaceId, environment: keyEnvironment, hostname: keyHostname } = readHtmlCacheKey(key);
-			if (filter.spaceId !== void 0 && keySpaceId !== String(filter.spaceId)) return false;
-			if (filter.environment !== void 0 && keyEnvironment !== filter.environment) return false;
-			if (filter.hostname !== void 0 && keyHostname !== filter.hostname) return false;
-			return true;
-		});
-	},
-	clear() {
-		store.clear();
-	},
-	get size() {
-		return store.size;
-	}
-});
+	};
+};
 //#endregion
 export { buildCacheManager };