@plitzi/sdk-server 0.37.1 → 0.37.3

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

@@ -0,0 +1,119 @@
+# Testing what you authored
+
+## One call: `inspectPage`
+
+```ts
+import { authorSpace, inspectPage } from '@plitzi/sdk-authoring';
+
+const { handles } = authorSpace(space);
+await page.goto('/');
+expect((await inspectPage(page, handles)).problems).toEqual([]);
+```
+
+It checks the open page and returns EVERY problem at once, one sentence each, naming the element and the reason:
+
+- every element the page owes is present and visible — its own and those of the layouts around it
+  (`heading "hero-title" is on the page but not visible: display:none on "hero"`);
+- every image arrived — an image element that failed says so (`data-plitzi-failed`), though its fallback loads;
+- nothing scrolls sideways (`the page scrolls sideways by 37px — widest: "cards"`);
+- no text is drawn in the colour painted behind it.
+
+It retries for up to 5 s like an assertion does (`timeout`), so a provider still answering is not a failure. Options:
+`page` (id or slug; the home page by default), `elements: 'all'` to owe the unnamed elements too, `ignore: ['id']` for
+what a test knows is not there yet (a typo is refused), `skip: ['images']` for a check a page breaks on purpose.
+`inspectDocument(page)` runs the page checks alone, for a page whose space is not in hand.
+
+## Handles
+
+`authorSpace` returns `handles`: every element by id, with the selector that finds it in the rendered page
+(`[data-plitzi-el="<id>"]`). `handles.element(id)` throws on a name that does not exist, and `locate(page, handles)`
+turns an id into a Playwright locator. Pages are in `handles.pages` (each with its `path`, `elements` and `layout`); a
+layout's elements are in `handles.layouts` and render on every page that names the layout. `onScreen(handles, page)` is
+the list `inspectPage` holds a page to.
+
+Three flags say what a bare visit cannot promise, and `onScreen` leaves out:
+
+- `conditional` — on screen only under a condition of its own or of an ancestor;
+- `repeated` — inside a list row, so rendered once per row: several copies, or none while the list is empty. Address
+  one with `.first()` / `.nth(i)`, in a test that knows the data;
+- `boxless` — a provider with no tag, which renders its children and no element of its own.
+
+A `formControl`'s id names its wrapper: type into `locate('email').locator('input')`.
+
+Select by `data-plitzi-el`, never by a generated class name: authoring derives `<type>-<hash>` for an element's own
+rules, and that name changes when the rules do.
+
+## Pressing a shortcut
+
+`pressShortcut(page, 'mod+z')` presses a shortcut written the way `onKey` writes it, with the keys the PAGE listens
+for: `mod` is ⌘ where the page's user agent is a Mac and Ctrl anywhere else. A driver's own "Control or Meta" asks the
+machine running the suite instead, so a suite on a Mac driving an emulated desktop Chrome presses ⌘ at a page waiting
+for Ctrl — the flow never runs and nothing says why. Point at the page first (a click on it) so it has the keys.
+
+## Counting what an interaction renders
+
+`inspectRenders(page, act, { max })` runs `act` and answers every element that rendered, how often and what changed
+for it; over `max`, `problems` says so. It reads the SDK's render tracing, which is on only under `debugMode` — render
+the space with it (the e2e harness: `renderSpace(page, space, { debugMode: true })`). What to do with the answer is in
+[performance](performance.md).
+
+## Spaces written for a test
+
+Author them like any space — never as JSON: the validator is what tells a fixture that tests something from one that
+tests nothing.
+
+```ts
+import { authorSpace, heading, singlePageSpace, withElement } from '@plitzi/sdk-authoring';
+
+const space = singlePageSpace([heading('Hi', { id: 'title', subType: 'h1' })]);   // one page, nothing else
+const edited = withElement(space, 'title', { attributes: { content: 'Changed' } }); // same page, one thing different
+```
+
+A fixture that must break a check ON PURPOSE — the runtime's answer to a document no author would write is the
+subject — names the break: `authorSpace(spec, { allow: [{ code: 'template-unknown-name', element: 'feed', why: '…' }] })`.
+One code on one element; it comes back in `warnings` with the reason, and an entry that no longer matches is refused.
+
+## What to check
+
+- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (below 48rem); `colorScheme: 'dark'` as well
+  as light.
+- **No horizontal scroll on a phone.** A column child grows to its content unless its parent stretches it; a code
+  block or a wide table is what finds out.
+- **The loading frame, not only the finished one.** A screenshot after the page settles cannot see an element that
+  flashed and went. Watch from the first frame:
+
+```ts
+await page.addInitScript(ids => {
+  const painted: string[] = [];
+  (window as unknown as { __painted: string[] }).__painted = painted;
+  const watch = (): void => {
+    for (const id of ids) {
+      const element = document.querySelector(`[data-plitzi-el="${id}"]`);
+      if (element && element.getClientRects().length > 0 && !painted.includes(id)) {
+        painted.push(id);
+      }
+    }
+
+    requestAnimationFrame(watch);
+  };
+  requestAnimationFrame(watch);
+}, ['empty-state', 'first-steps']);
+
+await page.goto('/', { waitUntil: 'load' });
+// … wait for the data to be on screen …
+expect(await page.evaluate(() => (window as unknown as { __painted: string[] }).__painted)).toEqual([]);
+```
+
+- **Both sides of every condition.** An account that has done everything must not see "get started"; a new one must.
+  An empty list shows its empty state; a full one does not.
+- **Navigation lands on the new page's content.** After `waitForURL`, wait for an element of the NEW page before typing:
+  for a frame the previous page is still mounted, and a form field with the same name there takes the keystrokes.
+- **Console errors are failures.** Collect them and assert the list is empty.
+
+## Screenshots and scrolling
+
+The page scrolls the document in development exactly as in production while the dev-tools panel is folded away (the
+badge). With the panel OPEN, the page shares the window with it and scrolls inside its own pane — close the panel, or
+run with `debugMode: false`, before a `fullPage` screenshot or a scroll measurement. For a screenshot at a width and a
+theme: `page.setViewportSize({ width: 390, height: 844 })`, `page.emulateMedia({ colorScheme: 'dark' })`, and seed state
+with `render(…, { state })` or a flow the test drives.

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

@@ -0,0 +1,73 @@
+# How `authorSpace` checks — and the loop that wastes no attempts
+
+`authorSpace(space, options)` is the whole check. It either returns `{ schema, style, handles, warnings }` or throws, and
+knowing HOW it throws is what turns ten attempts into two.
+
+## Three stages, two ways of failing
+
+| Stage | What it checks | How it fails |
+| --- | --- | --- |
+| 1. Assembly | Each spec as it is turned into a document: fields that exist, CSS properties the editor can read, a class declared twice with different rules, fonts, selector names | **Throws at the FIRST problem**, naming where it was written (`Element "text" (price) at shop/home/0/2`) |
+| 2. Structure | The documents: parents, roots, pages, cycles, style targets | Collected, then thrown together |
+| 3. Linter | What the documents MEAN: every template, binding, flow step, trigger, callback, attribute and link, read the way the runtime reads them | **All errors at once**, one line each: `Invalid space (…):\n  - [code] message` |
+
+The linter only runs once stage 2 holds, so the pattern of a session is: a few single refusals (fix, re-run), then one
+list — **fix every line of the list in one pass** before running again. Each message says what to write instead; do
+exactly that (see [authoring-errors](authoring-errors.md) for every code).
+
+Warnings come back in `warnings` and never throw. Each one is written code that will not do what it says — zero is the
+bar.
+
+## The loop
+
+0. **Before writing an element you have not used, print what it takes.** One command answers attributes, values,
+   triggers, callbacks and slots, and saves a refusal per guess:
+
+   ```bash
+   node --input-type=module -e "import * as a from '@plitzi/sdk-authoring'; const t = 'dropdown'; console.log({ attributes: a.elementDefaultAttributes[t], values: a.elementAttributeValues[t], triggers: a.elementTriggers[t], callbacks: a.elementCallbacks[t], slots: a.elementSlots[t] })"
+   ```
+
+1. **Author once, print everything.** In a project `plitzi create` wrote, `npm run author`. Anywhere else, a file you run
+   with `node` (≥ 22.18 strips the types) — outside the project's source, never committed:
+
+   ```ts
+   import { authorSpace } from '@plitzi/sdk-authoring';
+
+   import { space } from './src/space.ts';
+
+   try {
+     const { schema, warnings } = authorSpace(space, { plugins: [] /* your declarations */ });
+     console.log(`${Object.keys(schema.flat).length} elements, ${warnings.length} warnings`);
+     warnings.forEach(warning => console.log(`[${warning.code}] ${warning.message}`));
+   } catch (error) {
+     console.log((error as Error).message);
+   }
+   ```
+
+2. **Fix, re-run, until it prints zero warnings.** Then typecheck the project.
+3. **Look at it** — in a browser, at desktop and phone width, in both themes (see [testing](testing.md)). Stage 3 is
+   thorough about MEANING and blind to what follows.
+
+## What it cannot see
+
+A space that authors cleanly can still render wrong. These are the places to look with your own eyes:
+
+- **The shape of data it does not have.** A binding to `feed.records` is checked to name a provider; whether the
+  action's output HAS `records`, or its rows a `magnitude`, is known only at run time. Render with real data.
+- **Layout and cascade.** Overflow, stacking, a type's default style under your class (a `button` or `text` default
+  applies beneath your rules), a `gap` holding a slot for a hidden element.
+- **A plugin's inside** — and, unless you hand its declaration over (`plugins: [declaration]`, see
+  [plugins](plugins.md)), its events, actions and attributes too.
+- **Anything positioned by a component.** A map marker, a dropdown popup, a tooltip: the component sets `position` on
+  its root. A class that sets `position` on it (a panel preset spread into it, say) takes that away, and it lands in
+  the page flow — offset, or holding its container open while hidden.
+- **What an ancestor's `backdrop-filter`, `filter` or `transform` does**: it becomes the containing block of every
+  `position: fixed` descendant and a stacking context of its own, so a popup inside it opens offset and paints UNDER
+  its siblings.
+
+## When a CSS property is refused
+
+The style vocabulary is the closed list the editor can read back. What is outside it — `zoom`, `mask`, a custom
+property (`--seismic-accent`), a pseudo-element, a keyframe — is not an error to work around: it goes in the space's
+`customCss`, addressed by the class name (`.panel`, and `.panel--open` for a variant `variantFrom` applies). Shorthands
+inside it ARE accepted and expanded: `inset`, `grid-area`, `outline`, `border`, `padding` all work in `css`.

package/dist/modules/actions/runtime/schedule.d.ts

@@ -1,35 +0,0 @@
-import { ActionsModule } from '../index';
-import { ActionLookups } from '../types';
-import { Environment } from '@plitzi/sdk-shared';
-export type ScheduleTick = {
-    spaceId: number;
-    environment?: Environment;
-    /** The minute being asked about. Passed in rather than read here so a tick is testable and a missed one can be
-     *  replayed deliberately — never guessed at. */
-    at?: Date;
-};
-export type ScheduleResult = {
-    ran: {
-        actionId: string;
-        runId: string;
-        status: string;
-    }[];
-    skipped: {
-        actionId: string;
-        reason: string;
-    }[];
-};
-export type ScheduleRunner = {
-    tick: (params: ScheduleTick) => Promise<ScheduleResult>;
-};
-/**
- * Runs the actions a space has scheduled for this minute.
- *
- * It owns no timer, on purpose. What ticks it is the deployment's: a leader-locked interval in one role, a k8s
- * CronJob hitting an endpoint, a queue consumer — all of which have to answer "which replica" and "what happens
- * on restart", and none of which the SDK can answer for a deployment it cannot see.
- *
- * Missed ticks are NOT replayed. A scheduler that catches up fires an hour of digests at once after an outage,
- * which is worse than the digest nobody got; the caller that wants a replay asks for that minute explicitly.
- */
-export declare const createScheduleRunner: (lookups: ActionLookups, module: ActionsModule) => ScheduleRunner;

package/dist/modules/actions/runtime/schedule.js

@@ -1,76 +0,0 @@
-import { ActionRunError } from "./errors.js";
-import { findTriggerNode, triggerParams } from "./triggers.js";
-import { cronMatches } from "@plitzi/sdk-shared/actions";
-//#region src/modules/actions/runtime/schedule.ts
-/**
-* Runs the actions a space has scheduled for this minute.
-*
-* It owns no timer, on purpose. What ticks it is the deployment's: a leader-locked interval in one role, a k8s
-* CronJob hitting an endpoint, a queue consumer — all of which have to answer "which replica" and "what happens
-* on restart", and none of which the SDK can answer for a deployment it cannot see.
-*
-* Missed ticks are NOT replayed. A scheduler that catches up fires an hour of digests at once after an outage,
-* which is worse than the digest nobody got; the caller that wants a replay asks for that minute explicitly.
-*/
-var createScheduleRunner = (lookups, module) => {
-	const tick = async ({ spaceId, environment = "main", at = /* @__PURE__ */ new Date() }) => {
-		const result = {
-			ran: [],
-			skipped: []
-		};
-		const entries = await lookups.listActions?.(spaceId) ?? [];
-		for (const entry of entries) {
-			const schedule = findTriggerNode(entry.document.nodes, "schedule");
-			const params = schedule ? triggerParams(schedule) : void 0;
-			const cron = params?.cron;
-			if (!schedule?.enabled || !cron) continue;
-			if (!cronMatches(cron, at, typeof params.timezone === "string" ? params.timezone : void 0)) continue;
-			let run;
-			try {
-				run = await module.guards.begin({
-					spaceId,
-					actionId: entry.id,
-					callerId: "schedule",
-					input: {},
-					idempotencyKey: `schedule:${at.toISOString().slice(0, 16)}`,
-					sharedKey: true,
-					ttlMs: module.limitsFor(entry.document).timeoutMs
-				});
-			} catch (error) {
-				result.skipped.push({
-					actionId: entry.id,
-					reason: error instanceof ActionRunError ? error.reason : "failed"
-				});
-				continue;
-			}
-			try {
-				const run_ = await module.runAction({
-					entry,
-					input: {},
-					spaceId,
-					environment,
-					trigger: "schedule",
-					callerId: "schedule",
-					runId: run.runId,
-					signal: run.controller.signal
-				});
-				result.ran.push({
-					actionId: entry.id,
-					runId: run_.runId,
-					status: run_.status
-				});
-			} catch (error) {
-				result.skipped.push({
-					actionId: entry.id,
-					reason: error instanceof ActionRunError ? error.reason : "failed"
-				});
-			} finally {
-				await module.guards.end(run);
-			}
-		}
-		return result;
-	};
-	return { tick };
-};
-//#endregion
-export { createScheduleRunner };