@jucie.io/cli 1.0.20 → 1.0.22

package/dist/layout.md

@@ -1,41 +1,100 @@
-# Layout
+# Styling in Jucie
 
-## Architecture
+Every node's style is a **composed style**: CSS plus intents (`$layout`,
+`$axis`, `$width: 'fill'`, …), described in "The style map" below. This
+section is how Jucie's operations write it.
 
-**Frames are first-class layout containers.** Set layout directly on the frame — no wrapper div needed.
+## Pages are frames
 
-**Every page = frame (flex column) → sections (header, main, footer, etc.)**
+- The root of every page is a `frame` with parent `"app"`. Lay it out
+  directly (`setLayout(frameId, 'flex')`, then `$axis: 'y'`); never wrap the
+  page in an extra div.
+- Sections inside it (header, main, footer, …) carry visual styles and size
+  themselves with intents: `$height: 'fill'` on the main section of a column
+  takes the remaining height; `$alignX: 'stretch'` on the frame makes
+  sections full width.
 
-## Key rules
+## Components have artboards
 
-1. Root of tree is ALWAYS type `"frame"` with parent `"app"`
-2. Set flex/grid layout directly on the frame — do NOT wrap in a div
-3. Children of the frame only need visual styles (padding, background-color, etc.)
-4. Use `flex: "1"` on the main content section to fill remaining space
-5. For horizontal layouts (sidebar + content), use a nested div with `display: "flex"`, `"flex-direction": "row"`
-6. For grids, use `display: "grid"` with `"grid-template-columns"` on the container
-7. NEVER use `position: "absolute"` on children of flex/grid parents — the system auto-normalizes them to `position: static` and absolute children won't participate in the flow layout
+- `addComponent` gives the component its own artboard on the canvas, beside
+  the page it came from. Pass `width` / `height` close to the size it is used
+  at (a header: the page width and its bar height; a card: the card's size).
+  Leave `x` / `y` out unless asked; frames and artboards are always moved
+  clear of each other.
+- An instance placed from the palette starts at its artboard's size, so a
+  well-sized artboard is a well-sized instance.
 
-## set_layout vs update_style
+## Layout: setLayout
 
-**Always use `setLayout` / `node:setLayout` for flex/block/grid. Never use `updateStyle({ display: 'flex' })` alone.**
+`setLayout(id, mode, breakpoint?)` is the only way to set or change a
+container's layout (`none` | `block` | `flex` | `grid`). It stores `$layout`
+and fixes up the children: under a free (`none`) parent they get a top/left
+anchor so they can be placed.
 
-`setLayout` does two things `updateStyle` cannot:
+- Then shape it with intents through `updateStyle`: `$axis`, `$alignX`,
+  `$alignY`, `$distribute`, `$wrap`, `$reverse`, plus plain `gap`. For a grid,
+  plain `grid-template-columns`.
+- `breakpoint: '@768'` sets the layout from that width up: a column on
+  phones, a row from tablet (`setLayout(id, 'flex')` + `$axis: 'y'`, then
+  `updateStyle(id, { $axis: 'x' }, '@768')`).
+- `tree:create` takes `$layout` in a node's `styles` and sets it the same way.
+- `updateStyle` ignores `display` and `position` (with a warning): layout is
+  `setLayout`'s, and position follows the parent's layout.
 
-1. Sets the `layout` property on the node (what the runtime uses to determine child flow)
-2. Runs `normalizeLayoutContext` on every child — strips absolute-positioning metadata so they flow correctly
+## updateStyle: where a value is written
 
-Calling `updateStyle({ display: 'flex' })` sets the CSS but leaves children in absolute mode. They will stack or overlap.
+`updateStyle(nodeId, styles, breakpoint?, state?)`
 
-To change layout mode AFTER creation, use `node:setLayout` — NEVER `node:updateStyle` with display or position. `updateStyle` ignores these properties. Only `tree:create` can set display inline (it handles normalization internally).
+- **No breakpoint:** the base, which applies at every width (the Mobile
+  tier). Build the phone layout here first.
+- **`breakpoint: '@768'`** (Tablet) or **`'@1280'`** (Desktop), the app's
+  tiers as listed under `breakpoints` in the scene: from that width up,
+  overriding the base. Write only what differs. Use the app's tiers; another
+  width (`'@900'`) works but isn't one the editor shows.
+- **`state: ':hover'`**, `':focus-visible'`, `'&.is-active'` (a custom state
+  added with `addState`): applies in that state. Combine with a breakpoint
+  for a state at a width (`breakpoint: '@1280', state: '&.is-active'`).
+- **Sizes, insets, placement and container intents ignore the state**:
+  `$width`, `$height`, `width`, `height`, the insets, `$flow`, the anchors,
+  and `$layout` … `$distribute` are always written to the breakpoint itself. In Jucie they can't differ on
+  hover; colors, borders, shadows and the like can.
+- Writing `$width` replaces a raw `width` on that breakpoint, and the reverse;
+  same for height.
+- `removeStyle(nodeId, properties, breakpoint?, state?)` deletes values so the
+  breakpoint below (or the base) shows through. Use it to undo an override
+  instead of writing the base value again.
+
+## Position
+
+- A child of a **free** (`none`) parent is placed by its insets. Its anchors
+  (`$anchorX` / `$anchorY`) say which insets count; without them they're read
+  from the insets you write (`right` alone pins it right). Set an anchor when
+  the edge matters, so nothing else can move it:
+  `updateStyle(id, { $anchorX: 'end', right: '16px', top: '16px' })`.
+- In a block, flex or grid parent the flow places the child and insets are
+  ignored. To take one child out of the flow (a badge on a card, a close
+  button in a dialog), give it `$flow: 'ignore'` plus anchors and insets; its
+  siblings keep flowing.
+- A parent free from one breakpoint up (`setLayout(id, 'none', '@768')`), or
+  `$flow: 'ignore'` at a breakpoint, lets a child flow on phones and be
+  placed from tablet.
+- `$flow: 'sticky'` (with `top: '0'`) sticks a child of a block parent.
+- `$flow` and the anchors are written to the breakpoint like sizes, never to a
+  state.
+
+## Tokens
+
+Reference design tokens by their slugged path: token `color/primary` →
+`var(--color-primary)`, in any value (`border: '1px solid var(--color-line)'`).
 
 ## Build order
 
 ```
-create (type, parent, { name: 'Descriptive Name' })
-  → setLayout(id, 'flex')     # if it will contain children in flow
-  → updateStyle(id, { … })    # visual properties only
-  → updateText(id, 'content') # for text nodes
+create (type, parent, { name: 'Descriptive Name' })   # or tree:create for a whole section
+  → setLayout(id, 'flex')            # containers that hold children in flow
+  → updateStyle(id, { $axis, $alignX, gap, … })        # base (phone) first
+  → updateStyle(id, { … }, '@768')   # then only what changes on tablet / desktop
+  → updateText(id, 'content')        # text nodes
 ```
 
-Always pass `name` in create props.
+Always pass `name` when creating.

package/dist/prerenderWorker.js

@@ -0,0 +1,13 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+// One page per worker: project stores are module singletons, so a fresh
+// import of the server bundle keeps one page's state out of the next.
+const { bundle, url, timeout } = workerData;
+
+try {
+  const { renderPage } = await import(pathToFileURL(bundle).href);
+  parentPort.postMessage({ ok: true, page: await renderPage(url, { timeout }) });
+} catch (error) {
+  parentPort.postMessage({ ok: false, error: error?.message ?? String(error) });
+}