@plitzi/sdk-server 0.37.7 → 0.37.9

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

@@ -134,6 +134,18 @@ A plugin says what HAPPENED through its events (`onPick`, with the seat in the p
 decide what that means — write `state`, open a modal, call a server action. Prefer that to writing `state` from inside
 the component: the flow is visible in the space, the builder shows it, and the same act can come from a button too.
 
+## Behaving in the builder
+
+The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
+belongs to the editor.
+
+- **Outside preview, do nothing on your own.** `usePlitziServiceContext().settings.previewMode` is `false` while the
+  page is edited. Declared interactions are already held back then; your own click handlers, timers, global listeners,
+  permission prompts and map gestures are not — gate them on `previewMode`, and still render something to select.
+- **Never the global `window` or `document`.** The canvas is a frame of its own and the code runs in the builder's
+  window: listen, measure and go full screen through the node's own page (`ref.current.ownerDocument`, its
+  `defaultView`) or `usePlitziServiceContext().utils.getWindow()`. An `instanceof` check takes its class from there too.
+
 ## Components that draw into DOM they do not render
 
 A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never

package/skills/plitzi-authoring/reference/templates-and-export.md

@@ -27,6 +27,12 @@ Never rewrite an exported space by hand. `specFromSpace({ schema, style })` read
 `compareSpaces(original, authorSpace(spec))` must list nothing but what `corrections` explains. The builder's
 **Export** does all three. Edit the code from then on — and tidy it as you go ([structure.md](structure.md)).
 
+A server action reads back the same way: `actionSpecFromEntry({ id, document })` gives the `defineAction` spec that writes
+it — only when that spec writes the very same document, otherwise `reason` says why and it stays JSON — and
+`actionToSource(spec)` writes the module. For the whole space as a project — pages, actions, functions, the source of
+its plugins and runtime, its files — use `plitzi create --from <space>` (and `plitzi pull` later) rather than exporting
+the parts by hand.
+
 For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
 `validateSpace({ schema, style })`.