@plitzi/plitzi-builder 0.38.2 → 0.38.3

package/CHANGELOG.md

@@ -1,5 +1,144 @@
 # @plitzi/plitzi-builder
 
+## 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-auth@0.38.3
+  - @plitzi/sdk-authoring@0.38.3
+  - @plitzi/sdk-dev-tools@0.38.3
+  - @plitzi/sdk-elements@0.38.3
+  - @plitzi/sdk-event-bridge@0.38.3
+  - @plitzi/sdk-interactions@0.38.3
+  - @plitzi/sdk-navigation@0.38.3
+  - @plitzi/sdk-plugins@0.38.3
+  - @plitzi/sdk-schema@0.38.3
+  - @plitzi/sdk-shared@0.38.3
+  - @plitzi/sdk-style@0.38.3
+  - @plitzi/sdk-variables@0.38.3
+  - @plitzi/plitzi-sdk@0.38.3
+
 ## 0.38.2
 
 ### Patch Changes

package/dist/modules/App/AppContext.d.ts

@@ -9,6 +9,16 @@ export type AppContextValue = {
     /** The layout grid over the canvas: the columns a page is laid out on, to line an element up by eye. */
     displayGrid: boolean;
     setDisplayGrid: Dispatch<SetStateAction<boolean>>;
+    /**
+     * Whether the canvas plays the elements' declared motion. Still by default — what is edited is shown as it ends up,
+     * rather than arriving again on every change — and played on asking.
+     */
+    motionPlaying: boolean;
+    setMotionPlaying: Dispatch<SetStateAction<boolean>>;
+    /** How many times the motion was asked to play from its start — what the canvas restarts its animations on. */
+    motionReplays: number;
+    /** Plays every motion on the canvas from its start, and leaves it playing. */
+    replayMotion: () => void;
     zoom: number;
     setZoom: Dispatch<SetStateAction<number>>;
     displayMode: DisplayMode;

package/dist/modules/App/components/AppHeader/MotionButton.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The elements' declared motion on the canvas: still while editing — each element shown as it ends up — and played
+ * from the start on asking, loops included.
+ */
+declare const MotionButton: () => import('react').JSX.Element;
+export default MotionButton;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/ElementMotion.d.ts

@@ -0,0 +1,19 @@
+import { ElementMotion as Motion } from '@plitzi/sdk-shared/schema/motion';
+export type ElementMotionProps = {
+    motion?: Motion;
+    /** Whether the element holds children — what arriving one by one is about. */
+    canHoldItems?: boolean;
+    /** A page does not move: what is in it does. */
+    isPage?: boolean;
+    /** `undefined` removes it: the element does not move. */
+    onUpdate?: (key: string, value: Motion | undefined, isDefinition?: boolean) => void;
+};
+/**
+ * How the element arrives — and when, and whether its children follow one by one — and whether it keeps moving: the
+ * presets the SDK's stylesheet plays, each previewed on its tile, and the choices read back as a sentence. Opacity and
+ * transforms only, stilled for a visitor who asked for less motion.
+ *
+ * Saved as soon as it is one the page can play; while it is not, the tab says why and the element keeps the one it had.
+ */
+declare const ElementMotion: ({ motion, canHoldItems, isPage, onUpdate }: ElementMotionProps) => import('react').JSX.Element;
+export default ElementMotion;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionPresets/MotionPresets.d.ts

@@ -0,0 +1,20 @@
+import { PresetCopy, PresetKind } from '../../helpers';
+export type MotionPresetsProps = {
+    kind: PresetKind;
+    /** The question the presets answer, which names the group. */
+    title: string;
+    /** What choosing none is called here, and what it looks like. */
+    none: PresetCopy;
+    presets: Record<string, PresetCopy>;
+    value: string;
+    /** The person asked their system for less motion: the stage shows where a preset ends, without playing it. */
+    still: boolean;
+    onChange: (value: string) => void;
+};
+/**
+ * One of the tab's two questions — how it arrives, whether it keeps moving — answered by picking a preset, with a stage
+ * that plays the one being looked at on a card (over and over while the pointer or the focus rests on it) and otherwise
+ * the chosen one, once. The stage is as wide as the sidebar; the chips wrap into as many columns as it fits.
+ */
+declare const MotionPresets: ({ kind, title, none, presets, value, still, onChange }: MotionPresetsProps) => import('react').JSX.Element;
+export default MotionPresets;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionPresets/components/MotionPresetChip/MotionPresetChip.d.ts

@@ -0,0 +1,12 @@
+export type MotionPresetChipProps = {
+    /** The preset, or `''` for none. */
+    value: string;
+    label: string;
+    selected: boolean;
+    onSelect: (value: string) => void;
+    /** The pointer or the focus came to it: the section's stage shows it. */
+    onLook: (value: string) => void;
+    onLookAway: () => void;
+};
+declare const MotionPresetChip: ({ value, label, selected, onSelect, onLook, onLookAway }: MotionPresetChipProps) => import('react').JSX.Element;
+export default MotionPresetChip;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionPresets/components/MotionPresetChip/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionPresetChip } from './MotionPresetChip';
+export * from './MotionPresetChip';
+export default MotionPresetChip;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionPresets/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionPresets } from './MotionPresets';
+export * from './MotionPresets';
+export default MotionPresets;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionSection/MotionSection.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+export type MotionSectionProps = {
+    title: string;
+    children: ReactNode;
+};
+/** A band of the tab, headed the way the style inspector's categories are. */
+declare const MotionSection: ({ title, children }: MotionSectionProps) => import('react').JSX.Element;
+export default MotionSection;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionSection/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionSection } from './MotionSection';
+export * from './MotionSection';
+export default MotionSection;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionSummary/MotionSummary.d.ts

@@ -0,0 +1,11 @@
+export type MotionSummaryProps = {
+    /** What the element will do, in words — or why it cannot yet. */
+    sentence: string;
+    problems: string[];
+    /** Whether the canvas is playing the motion, rather than holding it still. */
+    playing: boolean;
+    onPlay: () => void;
+};
+/** The choices read back as one sentence, and the way to watch them on the canvas, which is otherwise still. */
+declare const MotionSummary: ({ sentence, problems, playing, onPlay }: MotionSummaryProps) => import('react').JSX.Element;
+export default MotionSummary;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionSummary/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionSummary } from './MotionSummary';
+export * from './MotionSummary';
+export default MotionSummary;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionTiming/MotionTiming.d.ts

@@ -0,0 +1,10 @@
+import { Draft } from '../../helpers';
+export type MotionTimingProps = {
+    draft: Draft;
+    /** Whether the element holds children — what arriving one by one is about. */
+    canHoldItems: boolean;
+    onChange: (key: keyof Draft, value: string) => void;
+};
+/** When the arrival plays and how long it takes — and, for an element with children, whether they come one by one. */
+declare const MotionTiming: ({ draft, canHoldItems, onChange }: MotionTimingProps) => import('react').JSX.Element;
+export default MotionTiming;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionTiming/components/MotionTriggerOption/MotionTriggerOption.d.ts

@@ -0,0 +1,9 @@
+import { MotionTrigger } from '@plitzi/sdk-shared/schema/motion';
+export type MotionTriggerOptionProps = {
+    trigger: MotionTrigger;
+    label: string;
+    selected: boolean;
+    onSelect: (trigger: MotionTrigger) => void;
+};
+declare const MotionTriggerOption: ({ trigger, label, selected, onSelect }: MotionTriggerOptionProps) => import('react').JSX.Element;
+export default MotionTriggerOption;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionTiming/components/MotionTriggerOption/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionTriggerOption } from './MotionTriggerOption';
+export * from './MotionTriggerOption';
+export default MotionTriggerOption;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/components/MotionTiming/index.d.ts

@@ -0,0 +1,3 @@
+import { default as MotionTiming } from './MotionTiming';
+export * from './MotionTiming';
+export default MotionTiming;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/helpers.d.ts

@@ -0,0 +1,46 @@
+import { ElementMotion, MotionEnter, MotionLoop, MotionTrigger } from '@plitzi/sdk-shared/schema/motion';
+export type Timing = 'duration' | 'delay' | 'stagger';
+/** What the fields hold while typed: the presets as chosen, the timings as written. */
+export type Draft = {
+    enter: string;
+    on: string;
+    loop: string;
+} & Record<Timing, string>;
+export type PresetKind = 'enter' | 'loop';
+/** A preset as a person reads it: its name, what it looks like, and the words the summary says it with. */
+export type PresetCopy = {
+    label: string;
+    hint: string;
+    phrase: string;
+};
+export declare const ENTER_COPY: Record<MotionEnter, PresetCopy>;
+export declare const LOOP_COPY: Record<MotionLoop, PresetCopy>;
+export declare const ARRIVES_NONE: PresetCopy;
+export declare const LOOP_NONE: PresetCopy;
+export declare const TRIGGER_COPY: Record<MotionTrigger, {
+    label: string;
+    hint: string;
+}>;
+/** The gap a person gets on asking for children one by one, before they say another. */
+export declare const DEFAULT_STAGGER = 80;
+export declare const draftOf: (motion: ElementMotion | undefined) => Draft;
+/** The draft as a motion: the fields left empty are left out, and `on` only beside an arrival it times. */
+export declare const motionOf: (draft: Draft) => Record<string, unknown>;
+/** What the element will do, in one or two sentences — what a person checks their choices against. */
+export declare const describeMotion: (motion: ElementMotion) => string;
+/**
+ * How much stronger a loop is played on the stage than on the page. A loop is meant to be barely noticed — 8 px of
+ * float, 4% of pulse, 2° of sway — and on a card a few dozen pixels wide that reads as nothing at all.
+ */
+export declare const LOOP_PREVIEW_EMPHASIS = 3;
+/** Whether the stage plays this preset stronger than the page does — what its caption owns up to. */
+export declare const isEmphasised: (kind: PresetKind, name: string) => boolean;
+/**
+ * A preset played on a tile: the frames the SDK's stylesheet plays (sdk-shared), an arrival at its default duration,
+ * a loop at a third of its period — a 6 s float is too slow to read while a pointer rests on it — and, one that swings
+ * back, `LOOP_PREVIEW_EMPHASIS` times stronger. A full turn is a turn at any strength.
+ */
+export declare const previewOf: (kind: PresetKind, name: string, repeat: boolean) => {
+    keyframes: Keyframe[];
+    options: KeyframeAnimationOptions;
+} | undefined;

package/dist/modules/Builder/components/BuilderElementTools/ElementMotion/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './ElementMotion';
+export type { ElementMotionProps } from './ElementMotion';

package/dist/package.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@plitzi/plitzi-builder",
-  "version": "0.38.2",
+  "version": "0.38.3",
   "homepage": "./",
   "license": "AGPL-3.0",
   "files": [