@plitzi/sdk-server 0.38.2 → 0.38.4

package/CHANGELOG.md

@@ -1,5 +1,330 @@
 # @plitzi/sdk-server
 
+## 0.38.4
+
+### Patch Changes
+
+- 6ae4161: ## `plitzi push`: a self-hosted project back on its space
+
+  `plitzi create --from` and `plitzi pull` took a space out as a project and kept it in step; nothing put the project's
+  own changes back but a command per part, and no command at all for its pages. `plitzi push` is the way back
+  (`docs/en/projects-from-spaces.md`):
+
+  - **What changed, or what is named.** `plitzi push` sends what changed since the project last had the space — at a
+    terminal, offered as a ticked list to choose from (`↑/↓`, space, Enter); `plitzi push space functions` sends only
+    those parts: `space`, `functions`, `runtime`, `plugins`.
+  - **In order:** each changed plugin packed and uploaded (`pack plugin` + `upload plugin`, `--cdn`/`--bucket`), the
+    functions, the runtime, then the space — `src/space.ts` authored, the actions `src/actions.ts` serves and the manifests
+    in `src/connectors/` — as the space's draft. Never a published environment.
+  - **Never over the builder's work unseen.** The export now carries which state the draft is in (`SpaceExport.draft`),
+    recorded in `.plitzi/space.json` by `create --from` and `pull`; a push names it, and a draft edited since is refused
+    until `--force`. A project that never had the space may take one nobody has worked on; one holding work takes
+    `--force`.
+  - **Then `pull` follows it.** `.plitzi/space.json` records what was sent — only that, so a builder's change to a part
+    not pushed is still the next pull's — and a project that started on its own works with `pull` from then on.
+  - `@plitzi/sdk-shared/source`: `SpaceImport` / `SpaceImportResult` (`SPACE_IMPORT_FORMAT`), the push's one shape for
+    both ends, beside `SpaceExport`, which gains `draft`.
+  - `functions push`, `runtime push` and `upload plugin` keep their behaviour; their cores are what `push` runs.
+
+  ## A project's folders: `tmp/` for what it writes, `.plitzi/` committed, `public/` said to be public
+  - **`tmp/` is what a project writes for itself.** `@plitzi/sdk-server` keeps the plugins it builds in `tmp/.sdk-plugins`
+    and resized pictures in `tmp/images` by default (were `.sdk-plugins` and `.plitzi/images`). A project the CLI writes
+    puts the port it took (`tmp/dev-server.json`), the space as last authored while developing (`tmp/space.json`) and
+    Playwright's output (`tmp/visual`) there too, and its `.gitignore` ignores `tmp` — one line for all of it.
+  - **`.plitzi/` is committed.** The scaffold ignored it whole, so a clone lost `space.json`, `functions.json` and
+    `scaffold.json` — what `pull`, `push`, `functions push` and `upgrade` stand on. Now it holds only what the CLI records.
+    `npx plitzi upgrade --write` brings an existing project's `.gitignore` up.
+  - **No `space/offline-data.json`.** `npm run author` checks the space and writes nothing; the server asks it for the
+    documents with `--out tmp/space.json` while developing. The space is `src/space.ts`, and nothing beside it says
+    otherwise.
+  - **`public/` is on the internet.** The generated `README.md` and `AGENTS.md`, the CLI and authoring skills, the MCP
+    guide, `@plitzi/sdk-server`'s README and the docs now say so where data goes: never a secret, a key or data only
+    some visitors may read — in `public/`, or in a space's documents, which reach every visitor too.
+
+  ## An agent leaves the project clean
+
+  `AGENTS.md` gains **Keep the project clean** — nothing unused left behind, scratch work in `tmp/`, one of everything,
+  files a reader can find, and `author`, `typecheck`, `lint`, `format` and `check` passing — and the authoring skill's
+  review checklist a **Nothing left behind** section.
+
+  ## The dev tools' X-ray is the outlines too
+
+  The QA tab had **Outlines** (every element's box, its type and id when pointed at) and **X-ray** (the same boxes,
+  fainter, with what is wired to each). They are one tool now: the X-ray draws every box with its type and id, and marks
+  the wiring picked — all of it, one kind, or **Boxes only**.
+
+  ## A new space that says where to go
+
+  The space a new account and `plitzi create` start from keeps its welcome, and gains the three ways to change it — the
+  builder, code (with the command to run) and an agent — before the guides, which are shorter. Header, navigation, main
+  and footer are landmarks; the grid behind the top fades out instead of ending at an edge; the footer's line spans the
+  content; the links say their words and icon themselves, with no suggestion left.
+
+  ## Server data reads the same everywhere
+  - **One shape for a provider with a `query`.** A `runtime: 'server'` provider that only reads a JSON file the server
+    serves answered the body itself, while the same provider in the browser publishes `{ status, data }` — so moving it
+    to the server broke every binding. `publicFileResolver` and the builder's mock now answer `{ status, data }` too:
+    `<source>.data.<field>` whichever runtime.
+  - **Server data is on unless a space turns it off.** The page render read a missing `rsc` as on and the connector
+    resolver as off, so a server provider in a space the builder or the MCP made (neither writes `rsc`) resolved to
+    nothing, silently. Both read it as on now; only `rsc: { enabled: false }` turns it off (and is warned with a server
+    element). `authorSpace` writes `enabled: true` for a space that has one.
+  - **Never inside a component.** The page server resolves a page's tree and its layouts only, so a server provider in a
+    component rendered nothing, silently. Refused now (`server-provider-in-component`), with the fix: the provider on
+    the page, the rows handed in as a prop.
+  - **Bindings held to the data.** `authorSpace` takes `data` — what a provider's `query` answers — and
+    `publicData(folder)` (`@plitzi/sdk-authoring/node`) reads it from `public/`. A binding onto a path the file does not
+    have is warned (`path-not-in-data`) with the keys it does have. Generated projects pass it.
+  - **`plitzi check` reads the data too.** A binding that reads a path its provider's answer lacks, a provider that
+    failed (once, not as every element it left empty) and the rows each list rendered (`dataIssues`). `--ssr` names what
+    the server's HTML lacks that the hydrated page has. The dev tools' badge and panel (`data-plitzi-devtools`) are hidden
+    while `check` and `shot` look.
+
+  ## Authoring, clearer where agents tripped
+  - **`controls` on a button** (`aria-controls`): named by the element's id; authoring gives that element the anchor and
+    refuses an id the space lacks (`controls-unknown`); a saved document naming no anchor is warned
+    (`controls-no-anchor`). The accordion recipe uses it.
+  - **`live` on a container** (`aria-live`, `polite` or `assertive`) for words that change while a visitor reads them.
+  - **`subType: 'p'`** for a paragraph made of parts; `span-holds-block` covers it.
+  - **`formControl` types `search`, `url` and `tel`.**
+  - **Images:** no `src` draws the SDK's own placeholder (the CDN one answered 404); `resize: false` keeps a picture as
+    written; an SVG is never resized — `/_plitzi/img` redirects to it (`307`) instead of refusing it.
+  - **Messages:** an id taken by another page or layout names it and the id to write; a hyphenated source in a template
+    (`list_study-plans`) is explained as valid; an unknown CSS property says to write it in `customCss`; an unknown
+    variant on `custom` says it is never a prop of the component it hosts.
+  - **`plitzi explain` knows the helpers** — `bindTemplate`, `visibleWhen`, `variantFrom`, `activeOn`, `activeWhen`,
+    `when`, `named`, `scope`, `source`, `twig` — and `motion`, from the presets the SDK plays (`MOTION_ENTERS`,
+    `MOTION_TRIGGERS`, `MOTION_LOOPS`, now exported). `--list helpers` lists them.
+  - **`plitzi shot`** writes to `tmp/shots/` by default, and a full page shows the arrivals tied to the scroll as they
+    end. `inspectPage` no longer reports an image a hidden ancestor hides.
+  - **Style inspector:** `container-type` in Size.
+  - **New recipes:** `server-data.ts`, `accordion.ts`.
+
+  ## Matching a page to another, measured
+  - **A whole page is the whole page.** The SDK scrolls a pane of its own, so `shot`'s full-page picture was one
+    screen; the pane is unrolled now (`unrollPage`) — the viewport untouched, so a `100vh` hero stays one screen.
+  - **`plitzi shot --compare` says why, not only how much.** Every lazy picture on both pages is loaded before they are
+    taken (`loadImages`), so a section no longer swings between 23 % and 40 % on how many covers had arrived. Each section
+    is compared where it is on the other page (`alignPictures` over row profiles): a page 400 px longer is said once, with
+    the section the drift starts at, instead of a footer with the same styles reading 100 %. And the texts both pages
+    have are paired (`pageTexts`, `compareTexts`), each with what it does differently there —
+    `h1 "Learn CSS" — font-size 68px → 60px · y +19px` — position less the drift of its section. `comparePictures` takes
+    its options as an object now (`{ regions, tolerance, align }`).
+  - **`--scheme` is the space's theme.** A space whose default is dark painted dark under `--scheme light`, and the file
+    said light. `check` and `shot` now set the `theme` cookie a visitor's toggle writes; left out, the space's default is
+    pictured and the file is named by the theme actually painted.
+
+  ## `motion: { on: 'view' }` arrives once
+
+  `view` was tied to the scroll both ways: cards faded out again as the reader scrolled back up. Now it plays once, the
+  first time the element comes into view, with its `duration`, and stays — `revealOnView` (`@plitzi/sdk-shared/schema/
+motionReveal`), one observer under the SDK's root, marks it `data-motion-seen`. The scroll-driven arrival is
+  `on: 'scroll'`. A page read without scripts shows them as they end (`@media (scripting: none)`); the builder's previews
+  and the MCP's local screenshots hold motion at its end. The builder's Motion tab has the three.
+
+  The builder's preview plays motion as the published page does. It held everything at its end, and nothing marked
+  the canvas `data-hydrated`, so neither the loops nor a space's own `[data-hydrated]` animations ever started there.
+  Now an arrival plays as it comes into view, and the loops and keyframes run; **▶** on the canvas being edited runs the
+  space's own `[data-hydrated]` loops too. The motion guide adds the rule this needs from a space: `[data-hydrated]` is for
+  loops; an entrance of its own that plays once (`transform`/`opacity` only) plays from the first paint with
+  `backwards`, as the presets do — gated on hydration it jumps when the page goes live, and a canvas that never goes
+  live holds it on its first frame.
+
+  ## Thirteen ways in, nine loops
+
+  `motion` grows from six arrivals and four loops to thirteen and nine, all still `opacity` and the transforms:
+
+  - **Bold arrivals:** `slide-up` (from well below), `zoom-in` (from 60%), `zoom-out` (settling from 125%), `tilt`
+    (rising as it turns straight), `spin-in` (half a turn as it grows).
+  - **Springy arrivals:** `pop` overshoots and settles; `bounce-in` falls into place and bounces.
+  - **Loops:** `bounce`, `wobble`, `orbit` (a slow circle round where it is), `heartbeat`, `drift`.
+
+  An arrival is now a list of frames (`MOTION_ENTER_FRAMES` in `@plitzi/sdk-shared/schema/motion`; `MOTION_ENTER_FROM`
+  is its first), and so is a loop (`MOTION_LOOP_FRAMES[name].frames`, replacing `transform`/`at`). Arrivals move the
+  individual `translate`, `scale` and `rotate`, so they still compose with an element's own `transform` and with a loop.
+  The builder's Motion tab previews every frame; authoring, the MCP, `explain motion` and GraphQL read the same lists.
+
+  An arrival from the side no longer scrolls the page sideways. `slide-left` starts 32px to the right of where it lands,
+  past a phone's 16px gutter, and until it had played the page could be dragged sideways. The SDK's root clips that way
+  now (`overflow-x: clip`, which keeps the window the scroller: sticky bars and scroll timelines are untouched), and the
+  builder's preview does the same. Content wider than the page is cut rather than scrolling the page — give it a box of
+  its own with `overflow-x: auto`.
+
+  **3D and the transform parts are style properties.** `transform-style`, `perspective-origin`, `backface-visibility`,
+  `translate`, `rotate` and `scale` join the vocabulary (they were refused as `css-property-unknown` and had to go in
+  `customCss`); `scale: 0.94` is a factor, not pixels.
+
+  **The builder's placeholder for an empty element is 24px** (was 50px), one size for every element that has one. It
+  is a minimum, so it also grew empty shapes with a size of their own — a dot, a planet — while editing; 24px is still
+  a box to see, pick and drop into.
+
+  The desktop app's window was blank: authoring, run in the renderer to build the rail, asked Vite's `process` shim for
+  a working directory it does not have. It reads one only where there is one now — and only when a class conflict is
+  reported, rather than for every element of every space it writes.
+
+  ## Authoring advice that knows where and when
+  - **`class-conflict` says where both declarations are:** `styles('md-menu-button') at src/components/dropdown.ts:12,
+used by button at …, and styles('md-menu-button') at src/site/layout.ts:8, used by …` — `styles()` records its line as
+    an element factory does.
+  - **`repeated-shape` leaves controls alone.** Siblings that read different sources or write different state keys — a
+    menu for the language, one for the level — are not offered as a list.
+  - **`quiet: ['repeated-shape']`** on an element says a suggestion was left on purpose, and it is not offered again.
+    Only suggestions' codes (`quiet-unknown`). It is saved on the element (`definition.quiet`), so the builder's problems
+    panel, the MCP's `upsertElement`/`patchElement` and a project pulled back with `plitzi pull` all leave it alone.
+
+  ## What the docs say is what the code does
+
+  A pass across authoring's own messages, the skills, the MCP guide, `docs/en`, the CLI's README and the website, so an
+  agent reading two of them is never told two things:
+
+  - **A binding's `source` is the bound value, and only that.** With no value yet it fell back to the attribute's
+    current one — `sourceTo` — so `{{ source|default('…') }}` never took its default and `{{ source ? … }}` read an
+    element's placeholder ("Text") as an answer. It is `undefined` until the source has a value now; `sourceTo` is still
+    the value before.
+  - **`explain` writes a step the way its builder is called:** `delay(ms)`, `openModal('modal-id', data?)`,
+    `scrollBy('row-id', { x: '80%' })` — not `delay(…)` above the document's param names, which read as `delay({ time })`.
+  - **A page field nobody takes is told what it was probably for** — `seo` → `seoTitle` and `seoDescription` — instead of a
+    hint about keeping state appended to every one.
+  - Docs set straight: an element's id is `data-plitzi-el` in the page (`data-id` is the builder's, with debugging on);
+    a visibility condition writes nothing while its source has no value and is a yes or a no once it has one; `mobile`
+    is up to and including 48rem; `loadStrategy` defaults by type (`lazy` for a modal); the accessibility codes listed
+    in full everywhere (`embed-without-title`, `dropdown-without-control`, `controls-no-anchor`); the generated
+    `AGENTS.md` says a repeated block is a component and rows of data a list, as the skill does; `plitzi runtime` is
+    documented in the CLI's README, its skill and the website, which no longer says state across requests needs a
+    server of your own.
+
+- Updated dependencies [6ae4161]
+  - @plitzi/sdk-shared@0.38.4
+  - @plitzi/plitzi-sdk@0.38.4
+
+## 0.38.3
+
+### Patch Changes
+
+- e047e1d: ## `plitzi upgrade`: a project brought up to its CLI
+
+  A project written by an older CLI had no way up but `plitzi create` in a scratch folder and a file-by-file comparison:
+  `skills update` brought the skills and nothing else, so the `check` and `shot` scripts they teach did not exist.
+  `plitzi upgrade` (also `update`) shows what this CLI writes today for what is the CLI's in the project, and `--write`
+  makes it. One part or several: `plitzi upgrade skills`, `plitzi upgrade files packages`.
+
+  - **`files`:** the CLI's machinery — `author.ts`, `main.ts`, the Playwright, TypeScript and lint configs, AGENTS.md. One
+    nobody changed since the CLI wrote it is replaced, a missing one added; one the project made its own is shown as a
+    diff and left, until `--take <file>` (or `all`). `plitzi create` now records what it wrote, by digest, in
+    `.plitzi/scaffold.json`; a project made before that sees every file that differs as its own.
+  - **`packages`:** `package.json` merged, never replaced — the scripts and dependencies it lacks added, `@plitzi/*`
+    raised to this version, then the install (`--no-install` to leave it). A script of the project's own stays.
+  - **`skills`:** `.claude/skills/plitzi-*` from the packages installed, each replaced whole, and the ones a newer CLI
+    writes added. `plitzi skills update` is `plitzi upgrade skills --write`.
+  - **`renames`:** a name a version renamed with no alias, at its file and line — `canTemplate` → `canSnippet`,
+    `authorTemplate` → `authorSnippet` and its kin (renamed only where imported from `@plitzi/sdk-authoring`) — renamed
+    with `--write`.
+
+  `npm run author` says when the skills or the CLI's files are older than the SDK installed, and `plitzi --version`
+  prints the CLI's.
+
+  ## Page checks that can be the definition of done
+
+  `inspectPage`, `plitzi check` and the scaffold's visual test failed pages that were whole, so an agent learnt to ignore
+  them:
+
+  - **A breakpoint hiding an element on purpose** — the desktop navigation on a phone, a bottom bar only a phone shows —
+    is no longer "not visible": an element whose `display` or `visibility` a breakpoint rule sets is checked at the width
+    it shows at.
+  - **A lazy image out of sight** waits whichever side it is out of: below the fold, as before, or beside the screen in a
+    carousel's track — cut off by any ancestor that clips, as the browser decides when to fetch it.
+  - **A plugin that draws nothing** says so: `drawsNothing: true` in its declaration (a clock that fires a flow), and its
+    handle is `boxless`, so no check waits for it on screen.
+
+  `plitzi check --json` and `PageReport` carry `issues` beside `problems`: each with its `code` (`element-hidden`,
+  `image-not-loaded`, `sideways-scroll`…), the `elementId` it is about and, in `check`, the `width`.
+
+  ## Authoring
+  - **A link's `content` names it.** `control-without-name` read only a link's `label`, so applying the
+    `content-attribute` suggestion as written turned every link into a warning.
+  - **`plitzi fix` writes `content-attribute`** where it has one reading: a button's or link's children that are only
+    `text(…)` and `fontAwesome({ icon })` become its own `content` and `icon` — the words kept as written, an import left
+    unused taken out. A child with an id, options or a class of the space's own stays, and is said. `npm run author`'s
+    `[fix]` line counts these too.
+  - **The recipes, the skill's examples and the catalog template** hold to the suggestions as well as the warnings, and
+    their tests say so: six recipes and the template wrote a link's or a button's words as a child.
+
+  ## Declared motion — in code, in the builder and over MCP
+
+  An element says how it arrives and whether it keeps moving with `motion`, and the SDK's stylesheet plays it — no
+  keyframes to write: `{ enter: 'fade-up', on: 'view' }` arrives as it scrolls into view, `{ enter: 'scale', stagger:
+60 }` brings its children one by one (a grid, a list's rows), `{ loop: 'float' }` keeps it moving. Enters: `fade`,
+  `fade-up`, `fade-down`, `slide-left`, `slide-right`, `scale`; loops: `float`, `pulse`, `spin`, `sway`; `duration`,
+  `delay`, `stagger` in ms. Opacity and the transforms only — an arrival on `translate`/`scale`, so it composes with an
+  element's own `transform` — a loop held until the page is live (`data-hydrated`), and none of it for a visitor who asked
+  for less motion. `view` follows the scroll where the browser has scroll timelines and plays on load where not.
+
+  - **Authoring:** `motion` on any factory; refused where it cannot play (`motion-invalid`, `motion-no-tag`), and carried
+    by `specFromSpace` and `compareSpaces`.
+  - **Builder:** a **Motion** tab in an element's tools: the presets as chips, a stage that plays the one pointed at (a
+    loop shown stronger than the page plays it, and saying so), when and how long, children one by one, and the choices
+    read back as a sentence — laid out side by side once the sidebar is wide enough. The canvas holds motion still while
+    editing; **▶** in the header (or **Play on the canvas** in the tab) plays it from the start, restarting what already
+    played, and an arrival tied to the scroll plays by the clock there, where it is usually in view already.
+  - **MCP:** `motion` on `upsertElement` and `patchElement`, checked the same way; the guide names the presets.
+  - **Schema:** `definition.motion` (`ElementMotion`, `@plitzi/sdk-shared/schema/motion` — the presets, `motionProblems`,
+    `motionAttributes`, `isMotionAnimation`, and each preset's frames, which the stylesheet is tested against), in both
+    init queries. **The platform's GraphQL schema has to declare `SpaceElementMotion`
+    before this version's builder or SDK queries it.**
+
+  ## Dev tools QA: x-ray and motion
+
+  The **QA** tab gains an **X-ray**: every element the document wires something to — bound to data, shown on a condition,
+  running a flow, moving, behind a flag — outlined in its colour and named on the page, read from the space's document by
+  the element's name; its legend counts each kind on the page and picks one to show alone. Beside **Pause**, **Slow**
+  plays every animation at a quarter of its speed and **Replay** plays the declared motion again from the start, without
+  reloading the page.
+
+  ## Plugins that draw
+
+  `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` (`@plitzi/plitzi-sdk`): a canvas sized to the device (at
+  most 2×), followed as it resizes, animating only while somebody can see it move — a live page, no reduced motion, the
+  tab in front, the canvas on screen — and one still frame otherwise (the builder included). `createShaderProgram`
+  compiles and links, and a shader that fails throws a `ShaderError` with the driver's log, printed as
+  `[plugin <type> "<id>"] fragment shader failed: …` instead of an empty canvas; `error` and `ready` say where it is.
+  `useReducedMotion` for the rest.
+
+  ## A space re-authored without a restart
+
+  A project's `npm run start:dev` restarts for its server code and its plugins only: a save to the space is re-authored
+  in a process of its own and every open page loads again (`server.reloadPages()` over an SSE endpoint, on with
+  `createServer({ devReload: true })` — never by `devMode` alone, since every open page holds a connection for it); an
+  edit authoring refuses is printed and the page keeps the last space that authored. A shutdown also ends WebSockets at
+  once (`1001`, going away) rather than waiting out the grace — the ten seconds a restart used to wait on an open page.
+
+  ## Checks and authoring, from the stripe.com experiment
+  - **A component's instance** is found by its own name: its root carries `data-plitzi-instance`, and the instance's
+    handle selects it — `inspectPage` no longer reports every named instance as missing.
+  - **Hidden at this width on purpose** — the burger on a desktop, the desktop menu on a phone — is listed apart
+    (`hiddenAtWidth`, and a dim line under `plitzi check`'s ✓) rather than as a problem.
+  - **An element whose every child is conditional** — four flyouts in one list, each opening on the state that names
+    it — is conditional too: at rest it shows nothing, and that is it working.
+  - **A carousel that scrolls by itself** (`overflow-x: auto`) is not the page scrolling sideways; the page's own pane
+    still is.
+  - **Templates:** `{{ state.faq ?? -1 }}` — a sign on the right of `??` — reads.
+  - **A plugin attribute named as an element field** (`variant`, `class`, `id`…) is warned about
+    (`plugin-attribute-reserved`): a factory never hands it to the plugin. A `variant` no class or type style declares is
+    `unknown-variant`.
+  - **Lists:** a list with `items` renders as the `<ul>` (or `<ol>`) its `subType` says — it was a `<div>` — with no
+    markers and the same spacing, so a page looks as it did; the builder offers the list type for it too. Its rows are
+    `<li>`s: `list-row-not-li` warns of one that is not — a plain container is made one by `fixSpace`, a link or a button
+    is wrapped — and the recipes, the catalog template and the docs write rows as `listItem`.
+  - **CSS:** `mask-size`, `mask-position`, `mask-repeat`, `mask-composite`, `-webkit-mask-image`,
+    `-webkit-background-clip`, `box-decoration-break` and `-webkit-box-decoration-break`.
+  - **`plitzi shot`:** `--clip <element>`, `--scroll-to <element>` and `--viewport`; `--frames` takes the same framing.
+  - **SVG from files:** `svgFile` and `svgFiles` (`@plitzi/sdk-authoring/node`) read a logo or a folder of them,
+    compacted (`compactSvg`, also on the main entry), instead of strings in the space's source.
+  - The plugin scaffolds say that an inline `style` on `RootElement` outranks the element's classes.
+
+- Updated dependencies [e047e1d]
+  - @plitzi/sdk-shared@0.38.3
+  - @plitzi/plitzi-sdk@0.38.3
+
 ## 0.38.2
 
 ### Patch Changes

package/README.md

@@ -158,7 +158,8 @@ serve it — worth running over anything that arrives as a file.
 A space on Plitzi comes out whole, as a project wired to this server: `npx @plitzi/cli create my-site --from <space>`
 writes its pages as authoring code, its actions as `defineAction` code, its functions, the source of its plugins and
 runtime, and its files into `public/` — a draft, or any published snapshot (`--environment`, `--revision`) — and
-`plitzi pull` keeps it in step. See `docs/en/projects-from-spaces.md` in the workspace.
+`plitzi pull` keeps it in step, and `plitzi push` puts what changed in it back on the space. See
+`docs/en/projects-from-spaces.md` in the workspace.
 
 ## Configuration
 
@@ -167,6 +168,7 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `httpVersion` | `1 \| 2 \| 3` | `2` with `tls`, else `1` | HTTP protocol version. Falls back to the nearest available lower version. |
 | `tls` | `{ key, cert, minVersion? }` | — | TLS key and certificate. Required for versions 2 and 3; optional for version 1. |
 | `devMode` | `boolean` | `false` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). Off, the process must run with `NODE_ENV=production` or React renders with its development build; the server says so once, at `error`. |
+| `devReload` | `boolean` | `false` | Every page this server renders listens for `server.reloadPages()` and loads again — for a project that re-authors its space on save (what `plitzi create` writes into `main.ts`). Not turned on by `devMode`: each open page holds a connection for it. |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
 | `cacheTtlMs` | `number` | `300000` | TTL in milliseconds for the SSR render cache. Set to `0` to disable. |
 | `flags` | `Record<string, boolean> \| ({ spaceId, environment }) => Record<string, boolean>` | — | This deployment's say over the spaces' feature flags: above what a space declares, below the SDK's `flags` prop and a tester's dev tools, and only for flags the space declares. A function answers per space. Server actions and RSC resolve with it too. See `docs/en/feature-flags.md` in the workspace. |
@@ -175,11 +177,11 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `signIn` | `SSRSignInConfig` | — | Sign visitors in by redirect through an OAuth 2.1 authorization server: `GET /auth/sign-in?return=/x` registers this host as a client, sends the browser out with PKCE (state in a `__Host-` cookie), and `/auth/sign-in/callback` redeems the code server to server and hands the token to `exchangeCredential`, which makes the session here. Needs the `exchangeCredential` adapter. |
 | `templateFn` | `SSRTemplateFn` | built-in EJS template | Custom render function. Receives all template params and returns an HTML string. |
 | `plugins` | `Record<string, PluginSource>` | — | Named plugin definitions. Compiled or copied on first use and cached for `pluginsTtlMs`. |
-| `pluginsCacheDir` | `string` | `.sdk-plugins` | Directory where compiled plugin files are stored. |
+| `pluginsCacheDir` | `string` | `tmp/.sdk-plugins` | Directory where compiled plugin files are stored — under `tmp/`, with everything else the server writes for itself. |
 | `pluginsTtlMs` | `number` | `604800000` | TTL in milliseconds for compiled plugins (default: 1 week). |
 | `autoLoadSchemaPlugins` | `boolean` | `true` | Auto-download and cache plugins declared in the schema's `offlineData.plugins` list. A type the deployment registers itself (`plugins`, named in `pluginNames`) is never looked for there: its own build is the one rendered. Set to `false` to manage plugin loading manually. |
 | `allowPrivatePluginHosts` | `boolean` | `false` | Read a schema plugin from a private address (`localhost`, this server's own network). A plugin's address is typed by whoever edits a space, so leave it off anywhere but a development machine whose bucket is local. |
-| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. |
+| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. **Everything in it is public:** served to anyone who asks, with no check. |
 | `static` | `Record<string, string>` | — | URL prefix → filesystem path mappings for static file serving. |
 | `images` | `{ domains, cacheDir? }` | — | Pictures from other sites resized at `/_plitzi/img`, for an `image` to offer as a `srcset` (see [Images](#images)). |
 | `ssrOnly` | `boolean` | `false` | Omit client-side JS from the rendered page. Useful for verifying SSR HTML without hydration. |
@@ -396,11 +398,13 @@ createServer({ images: { domains: ['images.example.com', '*.cdn.example.com'] },
 
 An `image` whose `src` is another site's then offers the browser a `srcset` of widths this server makes (320 to 1920
 px) at `/_plitzi/img?url=…&w=…`, in AVIF or WebP when the browser takes them. Everything is kept on disk (`cacheDir`,
-default `.plitzi/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
+default `tmp/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
 files keep answering while the original is asked for with its `ETag` / `Last-Modified` — unchanged, nothing is resized
 again; changed, its sizes are made anew. A picture that could not be fetched is not asked for again for five minutes.
 Only the listed hosts are fetched, every redirect is held to the same
-list and to the rule every outbound request follows (no private network), and SVG is refused. Resizing needs `sharp`
+list and to the rule every outbound request follows (no private network). An SVG is never resized nor served from
+this origin: the proxy answers it with a redirect to its own address (`307`), so the picture still shows. An `image`
+with `resize: false` keeps its `src` as written. Resizing needs `sharp`
 (an optional peer): without it pictures are passed through and kept, and the server says so once.
 
 ### Public directory
@@ -416,6 +420,10 @@ createServer({
 
 The lookup order for a request is: `publicDir` → `static` prefix routes → SSR renderer.
 
+**Everything in `publicDir` is on the internet.** A file there is served to anyone who asks for it, as it is — no
+session, no permission, no check. Never put a secret, a key, an `.env`, a private document, a database dump or data only
+some visitors may read in it: that is served by a server action whose `access` checks who is asking.
+
 `/.well-known/` paths follow the same lookup order: served from `publicDir` if a matching file exists, otherwise `404 Not Found`. They are never handled by the SSR renderer.
 
 ## Compression
@@ -517,7 +525,7 @@ const server = createServer({
     // From a source file — compiled to ESM with esbuild
     'my-chart': {
       js: '/abs/path/to/MyChart.tsx',
-      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to .sdk-plugins
+      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to tmp/.sdk-plugins
       version: '1.2.0'
     },
     // Pre-compiled local file — copied as-is (version defaults to '1.0.0')
@@ -670,7 +678,9 @@ The SSR server includes a lightweight RSC endpoint that delivers server-side dat
 
 ### Schema setup
 
-Enable RSC at the top level of your schema:
+Server data is on unless the schema turns it off with `"rsc": { "enabled": false }` — the page render and the
+default `getRscData` (`connectorRscData`) read a missing `rsc` alike. `authorSpace` writes it out for a space with a
+server provider:
 
 ```json
 {

package/dist/core/createServer.devReload.test.d.ts

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

package/dist/core/http/stages/devReload.d.ts

@@ -0,0 +1,18 @@
+import { Stage } from '../types';
+/** Where an open page listens for "the space changed: load again", in development. */
+export declare const DEV_RELOAD_PATH = "/__plitzi/reload";
+/**
+ * The page reloading itself when the space it shows changed — the edit loop of a project that authors its space in
+ * code, without restarting the server: `main.ts` re-authors in a process of its own and calls `reloadPages()`, and
+ * every page open on this server loads again.
+ *
+ * Only with `devReload` on: every open page keeps a connection for it, which a server that never calls `reloadPages`
+ * — a published one, or a platform's — would pay for and get nothing from. The template listens only then too.
+ */
+export declare const createDevReload: () => {
+    stage: Stage;
+    /** Every page open on this server loads again. */
+    reload: () => void;
+    /** The streams ended — the server is going away, and each page reconnects to whichever comes up next. */
+    close: () => void;
+};

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

@@ -0,0 +1,40 @@
+import { openEventStream } from "../sse.js";
+//#region src/core/http/stages/devReload.ts
+/** Where an open page listens for "the space changed: load again", in development. */
+var DEV_RELOAD_PATH = "/__plitzi/reload";
+/**
+* The page reloading itself when the space it shows changed — the edit loop of a project that authors its space in
+* code, without restarting the server: `main.ts` re-authors in a process of its own and calls `reloadPages()`, and
+* every page open on this server loads again.
+*
+* Only with `devReload` on: every open page keeps a connection for it, which a server that never calls `reloadPages`
+* — a published one, or a platform's — would pay for and get nothing from. The template listens only then too.
+*/
+var createDevReload = () => {
+	const listening = /* @__PURE__ */ new Set();
+	const stage = (ctx) => {
+		if (!ctx.config.devReload || ctx.req.path !== "/__plitzi/reload") return Promise.resolve(false);
+		const stream = openEventStream(ctx.rawRes, {
+			onAbort: () => listening.delete(stream),
+			retryMs: 1e3
+		});
+		listening.add(stream);
+		ctx.raw.once("close", () => {
+			listening.delete(stream);
+			stream.close();
+		});
+		return Promise.resolve(true);
+	};
+	return {
+		stage,
+		/** Every page open on this server loads again. */
+		reload: () => listening.forEach((stream) => stream.send("reload", {})),
+		/** The streams ended — the server is going away, and each page reconnects to whichever comes up next. */
+		close: () => {
+			listening.forEach((stream) => stream.close());
+			listening.clear();
+		}
+	};
+};
+//#endregion
+export { DEV_RELOAD_PATH, createDevReload };

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

@@ -15,7 +15,7 @@ var proxyFor = (images) => {
 		if (!transform) serverLog.warn("IMAGES", "sharp is not installed: pictures are passed through and kept, not resized (npm i sharp).");
 		return createImageProxy({
 			domains: images.domains,
-			cacheDir: path.resolve(images.cacheDir ?? ".plitzi/images"),
+			cacheDir: path.resolve(images.cacheDir ?? "tmp/images"),
 			fetch: globalThis.fetch,
 			transform
 		});

package/dist/core/server/baseServer.d.ts

@@ -18,5 +18,7 @@ export interface HttpServerParts {
     /** What the primary does once, before it starts the workers — work each of them would otherwise repeat, or race
      *  the others to do. */
     beforeFork?: () => Promise<void>;
+    /** The open pages told to load again (`SSRServer.reloadPages`) — a page server in `devMode`; nothing elsewhere. */
+    reloadPages?: () => void;
 }
 export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/core/server/baseServer.js

@@ -34,6 +34,7 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 	return {
 		cache: channel && parts.cache ? relayCache(parts.cache, `${channel}.cache`) : parts.cache,
 		plugins: channel && parts.forgetPlugins ? relayPlugins(parts.plugins, parts.forgetPlugins, `${channel}.plugins`, label) : parts.plugins,
+		reloadPages: parts.reloadPages ?? (() => void 0),
 		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") {

package/dist/core/server/drain.d.ts

@@ -10,8 +10,8 @@ export declare const SHUTDOWN_GRACE_MS = 10000;
  * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
  * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
  * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
- * the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
- * answered `graceMs`, and then cuts what remains.
+ * the idle ones, ends every event stream and WebSocket at once (neither has anything left to finish), gives what is
+ * still being answered `graceMs`, and then cuts what remains.
  */
 export declare const watchConnections: (server: PrimaryServer) => {
     drain: (label: string, graceMs?: number) => Promise<void>;

package/dist/core/server/drain.js

@@ -5,6 +5,13 @@ import { serverLog } from "../../helpers/serverLog.js";
 * called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
 */
 var SHUTDOWN_GRACE_MS = 1e4;
+/** A WebSocket close frame, as a server sends it (unmasked): status 1001, "going away". */
+var GOING_AWAY = Buffer.from([
+	136,
+	2,
+	3,
+	233
+]);
 /**
 * Whether a response is an event stream: said by its content type — or, since headers written with `writeHead(status,
 * headers)` are not kept where `getHeader` looks, by what it answers: a GET that asked for one, as an EventSource and
@@ -21,8 +28,8 @@ var isEventStream = (asking, answering) => {
 * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
 * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
 * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
-* the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
-* answered `graceMs`, and then cuts what remains.
+* the idle ones, ends every event stream and WebSocket at once (neither has anything left to finish), gives what is
+* still being answered `graceMs`, and then cuts what remains.
 */
 var watchConnections = (server) => {
 	const sockets = /* @__PURE__ */ new Set();
@@ -35,6 +42,13 @@ var watchConnections = (server) => {
 		sockets.add(socket);
 		socket.once("close", () => sockets.delete(socket));
 	});
+	const websockets = /* @__PURE__ */ new Set();
+	server.on("upgrade", (request, socket) => {
+		if ([request.headers.upgrade].flat().some((value) => value?.toLowerCase() === "websocket")) {
+			websockets.add(socket);
+			socket.once("close", () => websockets.delete(socket));
+		}
+	});
 	server.on("request", (request, response) => {
 		answering.set(response, request);
 		response.once("close", () => {
@@ -61,6 +75,7 @@ var watchConnections = (server) => {
 		answering.forEach((request, response) => {
 			if (isEventStream(request, response)) response.end(closeIdle);
 		});
+		websockets.forEach((socket) => socket.end(GOING_AWAY));
 	}) };
 };
 //#endregion

package/dist/core/server/pageServer.js

@@ -14,6 +14,7 @@ import { DRAFT_STORE_METHODS, createMemoryDraftStore } from "../../modules/ssr/p
 import { compileTemplate } from "../../modules/ssr/template.js";
 import { PluginManager } from "../../plugins/manager.js";
 import { makeHandler } from "../http/dispatcher.js";
+import { createDevReload } from "../http/stages/devReload.js";
 import { buildPagePipeline } from "../services/registry.js";
 //#region src/core/server/pageServer.ts
 /** The page-serving machinery: html/rsc caches, the render template and the plugin manager, driving the page
@@ -49,7 +50,8 @@ var createPageServer = (config, services, extensions) => {
 	};
 	const actions = actionsModuleFor(config);
 	const realtime = realtimeModuleFor(config);
-	const stages = buildPagePipeline(services, extensions);
+	const devReload = config.devReload ? createDevReload() : void 0;
+	const stages = [...devReload ? [devReload.stage] : [], ...buildPagePipeline(services, extensions)];
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
 			raw,
@@ -81,7 +83,11 @@ var createPageServer = (config, services, extensions) => {
 			pluginManager.forget(name, version);
 			invalidatePluginComponentCache();
 		},
-		onClosing: () => realtime?.close(),
+		onClosing: () => {
+			realtime?.close();
+			devReload?.close();
+		},
+		...devReload ? { reloadPages: devReload.reload } : {},
 		onDestroy: async () => {
 			await actions?.jobs?.stop();
 			destroyServerCaches(caches);