@solidrt/cli 0.0.41 → 0.0.43

package/AGENTS.md

@@ -32,10 +32,16 @@ Two reliable checks that need no GUI:
 
 1. `bunx srt bundle src/index.tsx` - exit 0 means the app compiles. Fast.
 2. `bunx srt render src/index.tsx --size 480x640 --duration 1 --fps 2` -
-   renders offscreen via EGL/wgpu and writes `frame-NNNNNN.png`. This actually
+   renders offscreen via EGL and writes `frame-NNNNNN.png`. This actually
    proves the app renders. Combine with `--fps`/`--duration` (defaults
    1280x720, 60fps, 1s).
 
+Also headless: the bundled flux runtime runs a plain `.js` file directly -
+`node_modules/@solidrt/<platform>/flux script.js` (e.g.
+`@solidrt/linux-x64-gnu`). No display, no dev server, full `flux:*` module
+access. The right tool for micro-benchmarks and for probing flux module
+behavior in isolation.
+
 `render` gotchas:
 - Frames are written to the RUNTIME's working dir (`~/.local/share/SolidRT/go/`),
   NOT the directory you ran the command from. Look there for the PNGs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -28,17 +28,16 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.41",
-    "@solidrt/linux-arm64-gnu": "0.0.41",
-    "@solidrt/linux-x64-gnu": "0.0.41",
-    "@solidrt/win32-x64-msvc": "0.0.41"
+    "@solidrt/darwin-arm64": "0.0.43",
+    "@solidrt/linux-arm64-gnu": "0.0.43",
+    "@solidrt/linux-x64-gnu": "0.0.43",
+    "@solidrt/win32-x64-msvc": "0.0.43"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.41",
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.41",
+    "@solidrt/flux-types": "0.0.43",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest"
   }

package/scaffold/AGENTS.md

@@ -54,9 +54,12 @@ Authoritative references ship inside the installed packages - read them:
    top-level props, not inside `layout`/`style`.
 3. `render(() => <App/>)` once, top level. The root MUST be a `<Window>`
    (from @solidrt/components) or the core `<window>` - it throws otherwise.
-4. `Window`/`View` do not paint on their own; they only paint when you set
-   `style.backgroundColor`/`borderColor` etc - there is no separate
-   background element to place by hand.
+4. Components' `Window`/`View` do not paint on their own; they only paint
+   when you set `style.backgroundColor`/`borderColor` etc - there is no
+   separate background element to place by hand. That is the components level
+   only: the core `<view>`/`<window>` have no background prop at all - in a
+   core-only app the background is a draw-primitive child
+   (`<d-rect color={...} />`) behind the content.
 5. There is no onClick/onPress on host elements. Use `Pressable`/`Button`
    from components (`onPress`), or `onPointerDown` on a `View` for anything
    custom.
@@ -125,7 +128,15 @@ Authoritative references ship inside the installed packages - read them:
     effect's apply phase, or `onSettled`; opt in narrowly with
     `createSignal(v, { ownedWrite: true })` for a signal that genuinely is
     internal state.
-19. Cover/contain images: give `Image` a `fit` prop ("fill" | "cover" |
+19. Transform origin on a `d-view`: unset `originX`/`originY` pivots
+    scale/rotate at the view's local (0,0), the point its children's
+    coordinates are drawn against (a laid-out view pivots at its own box
+    center; a d-view has no box). To pivot a detached group around its
+    content's center, set the origin explicitly in pixels
+    (`originX={100} originY={50}` for content drawn in a 200x100 local
+    space). Avoid pct()/keyword origins on a d-view - they resolve against
+    the box inherited from the nearest laid-out ancestor.
+20. Cover/contain images: give `Image` a `fit` prop ("fill" | "cover" |
     "contain" | "none" | "scale-down", CSS object-fit semantics, centered)
     plus a box via `layout` in any form - numbers, pct(), flex. Without
     `fit`, only NUMERIC layout sizes reach the image; `width: pct(100)`
@@ -153,7 +164,7 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    to compileShader/linkProgram. Params drive any uniform type: a number
    fills a `float`/`int` scalar, a flat number array fills `vec2`/`vec3`/
    `vec4` (2/3/4 numbers) or `mat4` (16, column-major), dispatched by the
-   shader's own declaration - a ported shader's `vec2 uCenter` or Shadertoy's
+   shader's own declaration - a ported shader's `vec2 uCenter` or
    `vec3 iResolution` needs no splitting into scalars. To combine several
    GPU passes, stack `<texture>` elements and set `blendMode` (e.g. a base
    pass plus an additive `blendMode="plus"` pass) rather than writing a
@@ -171,7 +182,10 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    on screen and to shaders sampling the texture.
 2. Reduce setProperty calls wherever possible: one path string rebuilt per
    frame beats N elements with N animated positions; a shader beats the path
-   string. get_stats' setPropsPerFrame is the counter to watch.
+   string. get_stats' setPropsPerFrame is the counter to watch. Compiled JSX
+   attribute expressions diff before writing, so a per-frame expression that
+   returns an unchanged value costs no property write - setPropsPerFrame
+   counts values that actually changed, not expressions re-run.
 3. Never leave onFrame registered while nothing animates: a pending onFrame
    is a standing frame request, so the runtime renders and presents every
    vsync even when the callback body does nothing - an invisible 60fps GPU
@@ -187,7 +201,11 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    system classifies these as Transform and keeps the node's own cache).
    What DOES invalidate the cache is any paint or content change inside the
    subtree - colors, path data, text, a Show toggling - so drive animation
-   with transforms and keep the cached content itself static.
+   with transforms and keep the cached content itself static. Off a boundary,
+   `opacity` on a view is NOT cheap: it wraps the subtree in a compositing
+   layer (save_layer) for as long as it is below 1. To fade a single
+   primitive, put the alpha in its `color` (`rgba(...)`) - paint alpha is
+   free; reserve view `opacity` for fading a genuine group as a whole.
 5. "snapshot" boundaries pay first-frame texture allocation + raster:
    creating many at once (dealing a board of 64 sprites) is a visible
    one-frame hiccup - pool or pre-warm if that moment matters.
@@ -308,6 +326,9 @@ its tools over guessing at runtime state:
 - get_buffer: a vertex-buffer range decoded to numbers (f32/u16/u8, 64 KiB
   per call) - verify geometry after a writeBuffer instead of inferring it
   from pixels
+- list_debug / call_debug: the app's own debug commands (registered with
+  `registerDebug` from `srt:dev`) - list them, then invoke by name with a
+  JSON argument. Per client, like get_snapshot
 - reload: rebuild from source and push to every client - THE dev loop is
   edit -> reload -> get_logs -> get_snapshot. reload surfaces build errors
   but not type errors; run `bunx srt check` for those.
@@ -350,8 +371,17 @@ flag: `"args": [..., "mcp", "--port", "N"]`.
 - console.log + get_logs is your primary probe into runtime state. For state
   you will want repeatedly (a pose, a mode, a counter), bind a debug key that
   logs it and read it back via get_logs.
-- Key events are delivered ONLY to the focused node (no bubbling): call
-  setFocus(node.id) from the window's ref or onKeyDown never fires. `key` and
+- Better than debug keys when driving the app over MCP: register debug
+  COMMANDS - `registerDebug(name, fn)` from `srt:dev`, invoked via the
+  list_debug/call_debug tools. `seek`/`pause`/`play` commands turn verifying
+  an animation into "jump to t, snapshot, look"; a `zoom` command that
+  shrinks a viewBox to a region gives magnified captures without touching
+  source. Registrations reset on hot reload, so register at module init;
+  sync return values only.
+- Key events start at the focused node and bubble to the window root; with
+  nothing focused they go to the window root alone. So a debug key bound via
+  `<window onKeyDown>` always fires (unless a focused component consumes the
+  key with stopPropagation, as TextInput does for editing keys). `key` and
   `code` are W3C KeyboardEvent values, so arrow keys arrive as "ArrowLeft"/
   "ArrowRight"/"ArrowUp"/"ArrowDown" (not "Left"), alongside "Enter",
   "Escape", "a".
@@ -365,6 +395,13 @@ flag: `"args": [..., "mcp", "--port", "N"]`.
 - When a human reports a visual bug: capture a snapshot and SAY WHAT YOU SEE
   in it before investigating, so you agree on the symptom. If you cannot see
   the problem in the capture, say that instead of guessing.
+- Snapshots are downscaled by the time you see them, so a full-window capture
+  cannot show you a defect a few pixels across. Whenever you hand-author
+  geometry - a `d-path` from raw path math, a `radius` where two shapes meet,
+  a stroke join - inspect it MAGNIFIED once, when you write it: a throwaway
+  entry file drawing the construction at 4-8x (pushed with `load`), or a
+  `zoom` debug command on the real app. Verifying that a shape is in the
+  right place is not the same check as verifying it is drawn right.
 - GPU/geometry bugs: inspect the actual GPU data FIRST - get_gpu_resources
   for draw counts/uniforms/sizes, get_texture for atlas or data-texture
   contents ("is this tile blank?" is a ten-second question), get_buffer for

package/scaffold/package.json

@@ -9,12 +9,12 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.41",
-    "@solidrt/components": "0.0.41"
+    "@solidrt/core": "0.0.43",
+    "@solidrt/components": "0.0.43"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.41",
-    "@solidrt/flux-types": "0.0.41",
+    "@solidrt/cli": "0.0.43",
+    "@solidrt/flux-types": "0.0.43",
     "typescript": "^7"
   }
 }

package/src/bundler.ts

@@ -72,7 +72,11 @@ async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
 }
 
 // Bun build plugin that runs JSX/TSX through babel-preset-solid (universal
-// generate, targeting @solidrt/core) plus the TS preset. Plain .js/.ts app
+// generate, targeting @solidrt/core) plus the TS preset. `moduleName` only ends
+// up as an import specifier in the emitted code, resolved from the app's tree at
+// bundle time; the CLI itself never loads core, so core is deliberately neither
+// a dependency nor a peer of this package (a second copy under the CLI could be
+// hoisted over the app's and bundle two runtime instances). Plain .js/.ts app
 // modules take the same path (solid is a no-op without JSX) so inlineImport
 // can rewrite their `with { type: "binary" }` imports too; dependency code
 // (node_modules) skips the babel detour and keeps Bun's native loaders.