@plitzi/sdk-shared 0.38.13 → 0.38.15

package/CHANGELOG.md

@@ -1,5 +1,252 @@
 # @plitzi/sdk-shared
 
+## 0.38.15
+
+### Patch Changes
+
+- 6cdd5cf: ## Security
+
+  - **A write another site caused is refused, cookie or none** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): the page
+    server guarded nothing it answers past `/auth` — a server action (`/_action`), a realtime publish, a space's `/fn/`
+    route, its runtime's endpoints, the deployment's own `data` stages, the adapter-only `loginPath`, `logoutPath` and
+    `exchangePath`. A plain `text/plain` POST from any page open in the same browser ran them, with the visitor's session
+    cookie when there was one (`SameSite=None` off this machine) and, in a project nobody signs in to, as whoever holds
+    the server's own credentials. Every unsafe request a browser says another site caused (`Sec-Fetch-Site: cross-site`,
+    or a foreign `Origin`) is now refused `403 reason: 'foreign'`, saying how to allow it: `crossSiteWrites.origins`
+    (with `auth`, `identity.platformOrigins` too) and `crossSiteWrites.paths` for a form other sites post to by design.
+    `Authorization`, and callers that are not browsers — webhooks, scripts — pass as before. One rule for this and the
+    sign-in check (`crossSiteRequest`, `csrf.ts`). A self-hosted runtime's endpoints now sit where the platform forwards a
+    space's — after the auth chain and this guard (`data`, was `preAuth`).
+
+  ## Testing
+  - **`page check` and `page shot` anywhere the project is served** (`@plitzi/cli`): `--url <origin>` for a second server
+    of it, staging or a deploy, instead of `npm start`'s port; `page check --space <module>` holds the pages to that space
+    instead of the project's — an agent's page — authored with `authorIsolated`.
+  - **A route with a query is checked as its page** (`@plitzi/cli`): `page check "/?v=2"` matched the query as part of
+    the path, found no page, and checked the space's "not found" page in its place.
+
+  - **What an element that chooses its children draws is checked** (`@plitzi/sdk-authoring`, `@plitzi/cli`): with
+    `choosesChildren`, the page checks owed none of its children — and checked none of them either: a dashboard drawing
+    three panels reported `checked: 1`. Each child it may draw, and what is inside one under no condition of its own,
+    now carries `shownWith` (the child it comes with) on its handle: once that child is on screen it and everything
+    named in it are owed like the rest of the page, and `checked` counts them. `onScreenIfChosen(handles, page)` lists
+    them.
+  - **A page that met a server error is looked at once more** (`@plitzi/cli`): `page check` and `verify` failed a page
+    for a `500` from somebody else's service having a bad second (`/fn/<space>/weather`), and passed on the next run with
+    nothing changed. A page whose requests got a `5xx` is checked again once; its report is the second look, and says
+    what failed the first time (`retriedAfter`). A `4xx` fails the same way twice, and is never retried.
+
+  ## Plugins
+  - **`useNotify`** (`@plitzi/plitzi-sdk`): a plugin shows the page's notifications — `notify('Deleted 79 recordings', {
+appearance: 'danger' })` — the same toasts an `addNotification` step shows, in the space's theme and `notifications`
+    look, with no trigger, flow or `window` event of the space's to wire. The step's vocabulary (`NOTIFICATION_PLACEMENTS`,
+    `NOTIFICATION_APPEARANCES`, `NOTIFICATION_DEFAULTS`) is one list in `@plitzi/sdk-shared`, read by both.
+  - **`appearance: 'danger'` looks like one** (`@plitzi/plitzi-sdk`): it reached the toast library as a type it does not
+    know, so a danger notification showed neither the error icon nor the colour `notifications.danger` sets.
+    A value a notification does not take — from a flow, or a plugin in plain JavaScript — is set aside by name and said
+    in the console, rather than shown as the default in silence (`readNotificationOptions`, `@plitzi/sdk-shared`).
+  - **`useServerAction`** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-authoring`, `@plitzi/sdk-interactions`,
+    `@plitzi/sdk-server`): a plugin runs one of the space's server actions, awaited —
+    `useServerAction<typeof habitDone>('habits-done')({ id })` answers `{ ok, output }` or `{ ok: false, reason, error }`
+    — through the `runServerAction` step itself: the same access, refusals, session handling and dev-tools entry.
+    `defineAction` keeps the literal types of its `call` way in, so the input is typed by the fields it declares (the
+    required ones required); `taskAction` types both ends from the task's `run`, and `FunctionTask<T, R>` takes what
+    `run` answers. `CallInputOf` / `CallOutputOf` read them. One operation is one action, never a `case` in one route.
+    What a run answers is typed (`ServerActionStatus`): a status the server never uses reads as a run that did not
+    complete, never as one that did.
+    The key those types ride under (`CALL_TYPES`) is exported, by `@plitzi/sdk-shared` and `@plitzi/sdk-authoring` with
+    `TypedActionEntry`, `CallInputOf` and `CallOutputOf`: a package that emits declarations could not write the type of an
+    action it exports (`TS4023` on every `export const actions = [defineAction(…)]`).
+  - **A plugin is drawn on the server first** (docs): a preference per device belongs in kept state (`keepState`,
+    `paintedState`) as a bound prop, never read from `localStorage` while rendering — React discards the whole tree on the
+    mismatch, and only in the browser of whoever saved something. `@plitzi/plitzi-ui` is not the page's: a plugin
+    importing it bundles its own copy, with its own contexts and its own look. The authoring skill's `plugin-reach.md`
+    says what a plugin says and to whom: a notification, another element (an event and the space's flow), a server
+    action, shared state, other pages.
+
+  ## Realtime
+  - **A channel that retains** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`): declared
+    `retain: true` (with `publish: 'server'`, which authoring requires), the server keeps the latest message of each type
+    on a topic — said by `ctx.publish` or a flow's `realtime.publish` — and hands them to every page that joins, marked
+    `retained`. A page reads them as `<channel>.retained.<type>`, a plugin as `useChannel(topic).retained`, the newest of
+    a type holding whichever order they arrive in; `null` forgets a type. Kept in the store the actions' `kv` uses (beside
+    the grants, by compare-and-swap), so every replica hands out the same; a topic keeps at most 64 types and 512 KB, and
+    a publish past that is refused before anything is sent. State every screen shares is one publish and one binding —
+    no kv key, initial read or copy in `state` of the project's own. The fleet store `realtime.grants` is now
+    `realtime.kv`.
+  - **The MCP writes every field a channel takes** (`@plitzi/sdk-mcp`): `patchSettings`'s channel had no `grant` — which
+    the guide taught — nor `retain` or the limits, so an agent could not declare a private channel at all. All are there
+    now, and the guide says what `retain` is for and that `channel_<id>.retained` holds it.
+
+  ## Authoring
+  - **`plitzi explain` knows every `@plitzi` package installed** (`@plitzi/cli`): a name that was not
+    `@plitzi/sdk-authoring`'s (`createServer`, `createJsonAdapters`, `useChannel`) was answered as the project's own code,
+    to `grep` in `src/`. It is read from the published types of every one installed, through their re-exports and entry
+    points (`@plitzi/sdk-server/handlers`), and a name two packages export — `createServer` is sdk-server's and sdk-mcp's
+    — is answered with both.
+
+  - **A space module somebody else wrote, authored where it reaches nothing** (`@plitzi/sdk-authoring`):
+    `authorIsolated(file, { timeoutMs })` of `@plitzi/sdk-authoring/node` runs `authorSpace` on it in a process Node's
+    permission model holds to reading the module's folder and its packages — no file written, no process started, no
+    variable of the caller's environment — kills one that runs too long, and validates what it answers again, so a forged
+    answer gains nothing. A refusal comes back as `authorSpace` says it, with the problems as data.
+  - **Pages an agent writes, served** (`@plitzi/sdk-server`): `createAuthoringHost({ dir, frameAncestors })` serves each
+    space it is handed at an address of its own (`put(space, { id }) → /?__pt=<id>`) as a draft of its one space, kept in
+    `dir` across restarts; `drop(id)` forgets one, and anything else answers `404` saying where the pages are.
+  - **A space is chosen by host or credential** (`@plitzi/sdk-server`, docs): `getSpaceDeployment` is asked on every
+    request, and what a page fetches after it carries nothing of its address but the host — a space chosen by the page's
+    query or path lost everything it asked for, and `/_plitzi/space/<hash>.json` answered a bare `404`. The contract and
+    the README say so (the README offered "by path prefix"), and that `404` says why.
+
+  - **`plitzi explain on` says how to read what a trigger carries** (`@plitzi/sdk-authoring`): its doc sat above a
+    helper, so `explain` printed only the signature. It now leads with `[named('picked', on('onPick')), …('{{ picked.seat
+}}')]`, and the CLI skill's plugin section says the same.
+
+## 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.
+
 ## 0.38.13
 
 ### Patch Changes

package/dist/authoring/declare.d.ts

@@ -68,6 +68,13 @@ export interface ElementDeclarationData {
      * `plitzi page check`), which would otherwise wait for it to be on screen and report it hidden.
      */
     drawsNothing?: boolean;
+    /**
+     * Whether the element shows only some of the children put inside it, chosen as it runs — a dashboard showing the
+     * panels of the layout saved for this device, a wizard its current step. Read by the page checks, which then owe none
+     * of them on screen; the ones it draws are checked like the rest of the page — there, visible, and what is named
+     * inside them too.
+     */
+    choosesChildren?: boolean;
     /**
      * The attributes the page server evaluates against a context of its own, never where the element renders: a
      * provider's `notFound`, read against its answer; a page's title and description, read against its server providers.

package/dist/authoring/index.mjs

@@ -2,5 +2,5 @@ import { toBuilderParams as e, toInteractionCallback as t, toInteractionCallback
 import { definePlugin as r, elementDeclaration as i, valuesOf as a } from "./declare.mjs";
 import { BUILTIN_PARAM_TYPES as o, hiddenParams as s, invalidParams as c, missingRequiredParams as l, reconcileParams as u } from "./paramSpec.mjs";
 import { BUILTIN_ELEMENT_CALLBACKS as d, SCROLL_CALLBACKS as f, applyElementCallback as p, getElementCallback as m } from "./elementCallbacks.mjs";
-import { spaceCallbacks as h } from "./spaceCallbacks.mjs";
-export { d as BUILTIN_ELEMENT_CALLBACKS, o as BUILTIN_PARAM_TYPES, f as SCROLL_CALLBACKS, p as applyElementCallback, r as definePlugin, i as elementDeclaration, m as getElementCallback, s as hiddenParams, c as invalidParams, l as missingRequiredParams, u as reconcileParams, h as spaceCallbacks, e as toBuilderParams, t as toInteractionCallback, n as toInteractionCallbacks, a as valuesOf };
+import { NOTIFICATION_APPEARANCES as h, NOTIFICATION_DEFAULTS as g, NOTIFICATION_PLACEMENTS as _, readNotificationOptions as v, spaceCallbacks as y } from "./spaceCallbacks.mjs";
+export { d as BUILTIN_ELEMENT_CALLBACKS, o as BUILTIN_PARAM_TYPES, h as NOTIFICATION_APPEARANCES, g as NOTIFICATION_DEFAULTS, _ as NOTIFICATION_PLACEMENTS, f as SCROLL_CALLBACKS, p as applyElementCallback, r as definePlugin, i as elementDeclaration, m as getElementCallback, s as hiddenParams, c as invalidParams, l as missingRequiredParams, v as readNotificationOptions, u as reconcileParams, y as spaceCallbacks, e as toBuilderParams, t as toInteractionCallback, n as toInteractionCallbacks, a as valuesOf };

package/dist/authoring/spaceCallbacks.d.ts

@@ -1,4 +1,33 @@
 import { BuiltinGlobalCallback } from './builder';
+/** Where a notification may appear: the `addNotification` step's `placement`, and `useNotify`'s. */
+export declare const NOTIFICATION_PLACEMENTS: readonly ["top-right", "top-center", "top-left", "bottom-right", "bottom-center", "bottom-left"];
+export type NotificationPlacement = (typeof NOTIFICATION_PLACEMENTS)[number];
+/** How a notification looks: the `addNotification` step's `appearance`, and `useNotify`'s. */
+export declare const NOTIFICATION_APPEARANCES: readonly ["success", "danger", "warning", "info"];
+export type NotificationAppearance = (typeof NOTIFICATION_APPEARANCES)[number];
+/** What a notification takes besides its text — every one with the default the `addNotification` step has. */
+export type NotificationOptions = {
+    placement?: NotificationPlacement;
+    appearance?: NotificationAppearance;
+    autoDismiss?: boolean;
+    /** Milliseconds before it dismisses itself, with `autoDismiss`. */
+    autoDismissTimeout?: number;
+};
+/**
+ * What a notification was handed, kept to what it takes — a flow's values arrive as written, and a plugin may be plain
+ * JavaScript — with each field set aside named, so the caller says so rather than showing the default in silence.
+ */
+export declare const readNotificationOptions: (given: Readonly<Record<string, unknown>>) => {
+    options: NotificationOptions;
+    ignored: string[];
+};
+/** The defaults of a notification, the step's and the hook's alike. */
+export declare const NOTIFICATION_DEFAULTS: {
+    readonly placement: "top-right";
+    readonly appearance: "success";
+    readonly autoDismiss: true;
+    readonly autoDismissTimeout: 5000;
+};
 /**
  * The `space` source, which the SDK application registers rather than this package.
  *

package/dist/authoring/spaceCallbacks.mjs

@@ -1,5 +1,38 @@
 //#region src/authoring/spaceCallbacks.ts
-var e = { addNotification: {
+var e = [
+	"top-right",
+	"top-center",
+	"top-left",
+	"bottom-right",
+	"bottom-center",
+	"bottom-left"
+], t = [
+	"success",
+	"danger",
+	"warning",
+	"info"
+], n = (n) => {
+	let r = e.find((e) => e === n.placement), i = t.find((e) => e === n.appearance), { autoDismiss: a, autoDismissTimeout: o } = n, s = typeof o == "number" && Number.isFinite(o) && o > 0 ? o : void 0, c = {
+		placement: r !== void 0,
+		appearance: i !== void 0,
+		autoDismiss: typeof a == "boolean",
+		autoDismissTimeout: s !== void 0
+	};
+	return {
+		options: {
+			...r === void 0 ? {} : { placement: r },
+			...i === void 0 ? {} : { appearance: i },
+			...typeof a == "boolean" ? { autoDismiss: a } : {},
+			...s === void 0 ? {} : { autoDismissTimeout: s }
+		},
+		ignored: Object.entries(c).filter(([e, t]) => !t && n[e] !== void 0).map(([e]) => e)
+	};
+}, r = {
+	placement: "top-right",
+	appearance: "success",
+	autoDismiss: !0,
+	autoDismissTimeout: 5e3
+}, i = { addNotification: {
 	source: "space",
 	title: "Add Notification",
 	strictParams: !0,
@@ -12,40 +45,28 @@ var e = { addNotification: {
 		placement: {
 			type: "select",
 			description: "Where the toast appears on screen.",
-			default: "top-right",
-			options: [
-				"top-right",
-				"top-center",
-				"top-left",
-				"bottom-right",
-				"bottom-center",
-				"bottom-left"
-			]
+			default: r.placement,
+			options: [...e]
 		},
 		appearance: {
 			type: "select",
 			description: "Visual style of the notification: success, danger, warning or info.",
-			default: "success",
-			options: [
-				"success",
-				"danger",
-				"warning",
-				"info"
-			]
+			default: r.appearance,
+			options: [...t]
 		},
 		autoDismiss: {
 			type: "boolean",
 			description: "Whether the notification dismisses itself after a timeout.",
-			default: !0,
+			default: r.autoDismiss,
 			canBind: !1
 		},
 		autoDismissTimeout: {
 			type: "number",
 			description: "Milliseconds before auto-dismiss. Only applies when autoDismiss is true.",
-			default: 5e3,
+			default: r.autoDismissTimeout,
 			when: (e) => e.autoDismiss === !0
 		}
 	}
 } };
 //#endregion
-export { e as spaceCallbacks };
+export { t as NOTIFICATION_APPEARANCES, r as NOTIFICATION_DEFAULTS, e as NOTIFICATION_PLACEMENTS, n as readNotificationOptions, i as spaceCallbacks };

package/dist/helpers/clipboard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The clipboard's `writeText`, bound — or `undefined` where the browser offers none. Typed as always there, it is not:
+ * a page not served over https has none (a phone opening a development server by its network address), nor has the
+ * server. A copy button that called it straight threw on such a page.
+ */
+export declare const clipboardWriter: () => ((text: string) => Promise<void>) | undefined;
+/** Copies `text`: whether it reached the clipboard — not where there is none, nor when the browser refuses it. */
+export declare const copyText: (text: string) => Promise<boolean>;
+/** What a copy button says when it could not copy, for its `title`. */
+export declare const NOT_COPIED_REASON = "This page cannot reach the clipboard: it is not served over https, or the browser refused.";

package/dist/helpers/clipboard.mjs

@@ -0,0 +1,17 @@
+//#region src/helpers/clipboard.ts
+var e = () => {
+	let e = typeof navigator > "u" ? void 0 : Reflect.get(navigator, "clipboard"), t = typeof e == "object" && e ? Reflect.get(e, "writeText") : void 0;
+	if (typeof t == "function") return async (n) => {
+		await Reflect.apply(t, e, [n]);
+	};
+}, t = async (t) => {
+	let n = e();
+	if (!n) return !1;
+	try {
+		return await n(t), !0;
+	} catch {
+		return !1;
+	}
+}, n = "This page cannot reach the clipboard: it is not served over https, or the browser refused.";
+//#endregion
+export { n as NOT_COPIED_REASON, e as clipboardWriter, t as copyText };

package/dist/helpers/enclosingSpace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * True under a space: what a space drawn inside it — the `plitziSdk` element, a plugin rendering a space of its own —
+ * reads to know the document is not its own. The space itself keeps the answer in `render.enclosed`, where everything
+ * in it reads it; this context is only how it learns it.
+ *
+ * Shared, because the space around may be another copy of the runtime: a plugin imports the SDK through the page's
+ * import map.
+ */
+export declare const EnclosingSpaceContext: import('react').Context<boolean>;

package/dist/helpers/enclosingSpace.mjs

@@ -0,0 +1,5 @@
+import { sharedContext as e } from "./sharedContext.mjs";
+//#region src/helpers/enclosingSpace.ts
+var t = e("EnclosingSpaceContext", !1);
+//#endregion
+export { t as EnclosingSpaceContext };

package/dist/helpers/spaceRoot.d.ts

@@ -0,0 +1,4 @@
+/** The class on a space's root element, where what floats above its page — a dropdown's open menu — is drawn. */
+export declare const SPACE_ROOT_CLASS = "plitzi-sdk";
+/** The root of the space `node` is drawn in: the nearest one, for a space drawn inside another. */
+export declare const spaceRootOf: (node: Element | null | undefined) => HTMLElement | null;

package/dist/helpers/spaceRoot.mjs

@@ -0,0 +1,4 @@
+//#region src/helpers/spaceRoot.ts
+var e = "plitzi-sdk", t = (e) => e?.closest(".plitzi-sdk") ?? null;
+//#endregion
+export { e as SPACE_ROOT_CLASS, t as spaceRootOf };

package/dist/project/network.d.ts

@@ -0,0 +1,12 @@
+import { NetworkInterfaceInfo } from 'node:os';
+/**
+ * This machine as another device on its network reaches it — a phone on the same Wi-Fi opening the project's server —
+ * said once for the server, which prints where to open it, and the CLI, which makes a certificate naming it.
+ */
+/** Its IPv4 addresses on the network (`os.networkInterfaces()`): what a phone opens it by today. */
+export declare const networkAddresses: (interfaces: NodeJS.Dict<NetworkInterfaceInfo[]>) => string[];
+/**
+ * The name mDNS gives it (`os.hostname()` → `studio.local`), which outlives the address the router hands it: a
+ * certificate made for it still serves after the address changes.
+ */
+export declare const localNetworkName: (machine: string) => string;

package/dist/project/network.mjs

@@ -0,0 +1,4 @@
+//#region src/project/network.ts
+var e = (e) => Object.values(e).flat().flatMap((e) => e && e.family === "IPv4" && !e.internal ? [e.address] : []), t = (e) => `${(e.split(".").at(0) ?? "").toLowerCase()}.local`;
+//#endregion
+export { t as localNetworkName, e as networkAddresses };

package/dist/realtime/topics.mjs

@@ -14,9 +14,9 @@ var t = /^[A-Za-z0-9:_.-]{1,128}$/, n = "[A-Za-z0-9_.-]{1,64}", r = (e) => t.tes
 ]), c = (t, n) => {
 	let r = [];
 	if (o.test(t) || r.push("a pattern is letters, digits and `:_.-`, with `{name}` for the part a page fills in — `board:{id}`"), !e(n)) return [...r, "a channel is an object: `{ access: { mode: \"public\" } }`"];
-	let { access: i, publish: a, presence: c, grant: l, maxMessageBytes: u, messagesPerSecond: d } = n, f = e(i) ? i.mode : void 0;
-	typeof f != "string" || !s.has(f) ? r.push("`access` is { mode: \"public\" }, { mode: \"session\" } or { mode: \"role\", permissions: […] }") : f === "role" && !(e(i) && Array.isArray(i.permissions) && i.permissions.every((e) => typeof e == "string")) && r.push("`access: { mode: \"role\" }` names the permissions it needs: `permissions: [\"boardEdit\"]`"), a !== void 0 && a !== "clients" && a !== "server" && r.push("`publish` is \"clients\" (pages send) or \"server\" (only a flow's realtime.publish)"), c !== void 0 && typeof c != "boolean" && r.push("`presence` is true or false"), l !== void 0 && typeof l != "boolean" && r.push("`grant` is true (a page needs a grant from `realtime.grant` to open a topic) or false");
-	for (let [e, t] of [["maxMessageBytes", u], ["messagesPerSecond", d]]) t !== void 0 && (typeof t != "number" || !Number.isInteger(t) || t <= 0) && r.push(`\`${e}\` is a whole number above zero`);
+	let { access: i, publish: a, presence: c, grant: l, retain: u, maxMessageBytes: d, messagesPerSecond: f } = n, p = e(i) ? i.mode : void 0;
+	typeof p != "string" || !s.has(p) ? r.push("`access` is { mode: \"public\" }, { mode: \"session\" } or { mode: \"role\", permissions: […] }") : p === "role" && !(e(i) && Array.isArray(i.permissions) && i.permissions.every((e) => typeof e == "string")) && r.push("`access: { mode: \"role\" }` names the permissions it needs: `permissions: [\"boardEdit\"]`"), a !== void 0 && a !== "clients" && a !== "server" && r.push("`publish` is \"clients\" (pages send) or \"server\" (only a flow's realtime.publish)"), c !== void 0 && typeof c != "boolean" && r.push("`presence` is true or false"), l !== void 0 && typeof l != "boolean" && r.push("`grant` is true (a page needs a grant from `realtime.grant` to open a topic) or false"), u !== void 0 && typeof u != "boolean" ? r.push("`retain` is true (the server keeps the latest message of each type for pages that join) or false") : u === !0 && a !== "server" && r.push("`retain: true` keeps what the server says, so only the server may speak: add `publish: \"server\"` — a page changes it through an action");
+	for (let [e, t] of [["maxMessageBytes", d], ["messagesPerSecond", f]]) t !== void 0 && (typeof t != "number" || !Number.isInteger(t) || t <= 0) && r.push(`\`${e}\` is a whole number above zero`);
 	return r;
 }, l = (e) => ({
 	maxMessageBytes: e.maxMessageBytes ?? 4096,