@solidrt/core 0.0.51 → 0.0.52

package/AGENTS.md

@@ -1,8 +1,8 @@
 # @solidrt/core - agent notes
 
-Dense, self-contained facts for writing a SolidRT app.
-Full docs live in docs/ (and the website). When this conflicts with prose docs,
-trust this file and the types in src/types.d.ts and jsx-runtime.d.ts.
+Dense, self-contained facts for writing a SolidRT app. The prose lives in
+docs/ (also the website); when this conflicts with it, trust this file and
+the types in src/types.d.ts and jsx-runtime.d.ts.
 
 SolidRT is a custom SolidJS renderer: it paints through a Rust runtime, not the
 DOM. There is no HTML, no CSS cascade, no `className`.
@@ -35,12 +35,19 @@ hardcode desktop pixels.
 
 Exception - fixed-aspect content. For content with fixed internal geometry
 (diagrams, slides, dashboards, games, emulators), do not branch on window size
-at all: author everything in one design space and let `viewBox` fit it.
-`<view flex={1} viewBox={[1280, 800]}>` uniformly scales and centers the
+at all: author everything in one design space and let `designSize` fit it.
+`<view flex={1} designSize={[1280, 800]}>` uniformly scales and centers the
 children (letterboxed), pointer events on them arrive in design coordinates,
-and the same code runs unchanged from a desktop window to a phone. Reach for
-`windowSizeClass` branching only when the layout genuinely reflows across form
-factors.
+and the same code runs unchanged from a desktop window to a phone. Laid-out
+children (flex, percentages, text wrap) resolve against the design size too,
+so a whole panel scales into a smaller box without reflowing; the view itself
+sizes like a replaced element whose intrinsic size is the design size. One
+trap from flexbox, not from designSize: in a flex row a width-only design-size view
+is stretched to the line's height under the default alignment, so give the
+view `alignSelf="flex-start"` (or the row a non-stretch `alignItems`) to get
+the design aspect - `aspectRatio` does not override stretch. Reach for
+`windowSizeClass` branching only when the layout genuinely reflows across
+form factors.
 
 `env` and `capabilities` (both exported from `@solidrt/core`) are the two
 objects that expose this. They are plain objects with REACTIVE GETTERS, not
@@ -73,7 +80,7 @@ you need the raw fact (e.g. `env.displayScale` for asset sizing below).
 Because the drawn size is fluid and the display DPI varies, asset format is a
 real design decision, not an afterthought:
 
-- Prefer VECTORS (`parseSvg` draws mapped to `<d-path>` in a `viewBox` view)
+- Prefer VECTORS (`parseSvg` draws mapped to `<d-path>` in a `designSize` view)
   whenever the render size is fluid or DPI varies - they stay crisp at any
   size x `displayScale()`.
 - RASTER (`<texture>` / `createImage`) needs source resolution >= displayed size
@@ -88,8 +95,9 @@ bun add @solidrt/core        # the renderer
 bun add -d @solidrt/cli      # the `srt` tool (see its AGENTS.md)
 ```
 
-`@solidrt/components` is a separate, optional package of higher-level components
-(see its own AGENTS.md); core primitives alone are enough to build a full app.
+Core primitives alone are enough to build a full app. The optional extensions
+(each with its own AGENTS.md) build on it: `@solidrt/components` (themed
+widgets), `@solidrt/2d` (2D graphics and games), `@solidrt/3d` (scene graph).
 
 tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 
@@ -103,13 +111,23 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-rc.0); bun resolves them from peerDependencies.
+2.0.0-rc.1); bun resolves them from peerDependencies.
 
 ## Element model (the parts that are easy to get wrong)
 
 - `render(() => <App />)`. The returned root MUST be a `<window>` or it throws.
   Call render once, at the top level.
 
+- Errors never halt the app. One thrown while computing an element's props or
+  a child expression is contained at that element: it keeps its last good
+  value, one `Contained error` log line names the node and the .tsx line,
+  and it recovers when the expression computes again. Anything unclaimed
+  beyond that (a throwing `createEffect`, an error while mounting) reaches
+  render()'s root boundary, which replaces the app's window with an error
+  window (message, stack, a Reset button that retries the failed
+  computations) and logs `Uncaught error`. `<Errored>` gives a subtree its
+  own in-place fallback.
+
 - Two kinds of element:
   - Containers - `<window>`, `<view>`. Do layout + transform + pointer events.
     THEY DO NOT PAINT. A `<view>` has no background/fill prop.
@@ -122,11 +140,13 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   Outlines: `drawStyle="stroke"` (or "stroke-and-fill") plus `strokeWidth`.
   Corner radius on draw primitives: `radius` (number or [tl, tr, br, bl]).
 
-- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `line`,
-  `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
+- Registered JSX intrinsics: `window`, `view`, `text`, `span`, `rect`, `oval`,
+  `line`, `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
   `d-oval`, `d-line`, `d-path`, `d-texture`, `d-text`. Line endpoints
   (`x1`/`y1`/`x2`/`y2`) exist only on `d-line`; a laid-out `<line>` has no
-  endpoint props and spans its layout box corner to corner.
+  endpoint props and spans its layout box corner to corner. `points` (a flat
+  `[x0, y0, x1, y1, ...]` array, plus `closed`) turns either form into a
+  polyline and wins over the endpoints while set.
 
 - Plain vs `d-` variant (the `d-` prefix means "detached" - detached from the
   layout engine, Taffy): a plain element (e.g. `rect`) is `RectProps &
@@ -165,6 +185,10 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
   then translate it with `x`/`y`.
 
+- Text `lineHeight` is a MULTIPLIER of fontSize (1.3-1.6 is typical), not
+  pixels. A CSS-reflex value like 22 makes each line box 22x the font size:
+  the text becomes blank space and the parent balloons.
+
 - JSX text children collapse whitespace (ordinary JSX semantics): runs of
   spaces become one, so space-padding a mono label collapses silently. An
   expression container preserves it - `<d-text>{"one    two"}</d-text>` - and
@@ -218,9 +242,55 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   TRACKED compute that reads signals and returns a value, then an UNTRACKED
   effect that receives it - `createEffect(() => count(), (c) => ...)`. The 1.x
   single-callback form `createEffect(() => { ...count()... })` does NOT track
-  here. Per-frame work: `onFrame((tick, frame) => {})` (returns a cleanup;
-  auto-cleaned inside a reactive scope) or standard `requestAnimationFrame`.
-  Also onResize, onLayout, onWindowFocus, onWindowBlur.
+  here.
+  Reading a signal/prop/store at the top level of a component body (not
+  inside JSX, a `createMemo`, or an effect's compute phase) reads it
+  untracked: it silently freezes at the initial value.
+  Writing a signal or store from inside an owned scope (a component body, a
+  `createMemo`, an effect's compute phase) throws
+  `REACTIVE_WRITE_IN_OWNED_SCOPE` in dev; a loader called in the component
+  body that sets state is the classic React / Solid 1.x reflex that hits
+  this. Move the write into an event handler, an effect's apply phase,
+  `onSettled`, or an `untrack` block; opt in narrowly with
+  `createSignal(v, { ownedWrite: true })` for a signal that genuinely is
+  internal state.
+  Signal writes flush on a microtask: a handler that sets a signal and
+  immediately reads it back gets the OLD value. Read it in an effect, or
+  call `flush()` (from @solidjs/signals) to force it through.
+
+- An element-valued prop (children, a content/icon slot) compiles to a getter
+  that builds a fresh native subtree on EVERY read, and a subtree that is
+  never inserted is never freed - native nodes are not garbage collected, so
+  what is only wasted work in DOM Solid is a permanent memory leak here. Read
+  such props exactly once, at the place they are mounted. To inspect
+  children (a typeof probe, counting), resolve them first with the
+  `children()` helper (re-exported from @solidrt/core) and probe the resolved
+  memo - never `typeof props.children` on the raw prop.
+
+- Animation is target-shaped first: declare `transition` on the element and
+  write targets, and the runtime animates natively with no per-frame JS.
+  Reach for per-frame work only for genuinely procedural motion:
+  `onFrame((tick, frame) => {})` is the native hook (runtime-paced, returns a
+  cleanup, auto-cleaned inside a reactive scope); `requestAnimationFrame`
+  exists as a web-standard one-shot but is not the preferred driver. A JS
+  tween loop or an animation library pushing interpolated values through
+  signals is the single most expensive mistake available here - read
+  agents/performance.md before writing either.
+  Window state: onResize, onLayout, onWindowFocus, onWindowBlur exist, but
+  prefer the reactive reads (`env`/`capabilities` above, or the accessors
+  `windowSize()`, `safeArea()`, `displayScale()`, `windowFocused()`,
+  `keyboardHeight()`, `pointerLocked()`) for reading layout and window
+  state. For mouse look, `lockPointer(true)` enters relative mouse mode
+  (cursor hidden and confined, positions freeze) and pointer events keep
+  reporting motion through `movementX`/`movementY`.
+
+- `createPortal` cannot mount during the app's initial render (it throws
+  "no mount target"): gate portal content behind a signal that starts false
+  and open it after startup - overlay content is opened, not born open.
+  `createScroll` containers need an explicit main-axis size (a height, or
+  flex inside a sized parent); with neither they resolve to 0 and the
+  content silently vanishes (`maxHeight` alone does not size it). The
+  runtime warns when this happens.
 
 - Device/GPU access via subpath imports: @solidrt/core/camera, /microphone,
   /speech, /gpu. Image flow: `decodeImage(bytes)` ->
@@ -253,5 +323,4 @@ render(() => <App />)
 Note the two `<d-rect>` underlays: a `<view>`/`<window>` does not paint, so a
 background is a draw-primitive child placed behind the content.
 
-To run and verify (incl. headless), see @solidrt/cli (its AGENTS.md). For
-higher-level components, see @solidrt/components (its AGENTS.md).
+To run and verify (incl. headless), see @solidrt/cli (its AGENTS.md).

package/README.md

@@ -53,7 +53,7 @@ Optionally, create a `tsconfig.json` to enable type recognition for SolidRT elem
 
 ## API
 
-See [docs/20-core](https://github.com/wellawaretech/solidrt/blob/main/docs/20-core/index.md) for the full API reference.
+See [docs/](https://github.com/wellawaretech/solidrt/blob/main/packages/core/docs/index.md) (shipped in the package) for the full API reference.
 
 ## License
 

package/docs/index.md

@@ -0,0 +1,154 @@
+# Core
+
+`@solidrt/core` is the spine of SolidRT. It links SolidJS reactivity
+to the native rendertree: an element vocabulary, layout, input, frames, and
+the environment model for adapting to the device you are running on.
+
+If you only learn one layer, learn this one. Extensions and tools are built
+on it and are replaceable; Core is the part that changes least (SolidRT is
+in alpha, so "least" is not "never").
+
+## Elements
+
+There is no DOM. JSX elements are native rendertree nodes, and the
+vocabulary is deliberately small:
+
+| Element | Purpose |
+| --- | --- |
+| `window` | The app window. One per app, the root of the tree. |
+| `view` | Layout and input. Boxes, flex containers, hit targets. |
+| `text`, `span` | A shaped paragraph, and a styled run inside it. |
+| `rect`, `oval`, `line`, `path` | Painted shapes. |
+| `texture` | A GPU texture: a decoded image, a camera frame, a shader target. |
+
+Layout and paint are separate jobs, which is the one place the vocabulary
+diverges sharply from HTML. A `view` never paints, so there is no
+`backgroundColor`; you put a `rect` behind the content, and by default a
+shape fills the layout box it sits in:
+
+```tsx
+<view padding={16} alignItems="center">
+  <rect color="#1b2440" radius={12} />
+  <text color="white">Boxed</text>
+</view>
+```
+
+Each painting element also has a detached twin: `d-view`, `d-rect`,
+`d-path`, `d-text`, and so on. Detached elements are positioned by their
+parent's coordinate system rather than by layout, so changing one costs no
+reflow. Use them for anything that moves at animation frequency.
+
+## Reactivity
+
+Props are reactive values, not snapshots. A signal read inside JSX
+subscribes exactly one native property to exactly one signal, and an update
+writes that property directly. Nothing re-renders, and there is no virtual
+DOM to diff:
+
+```tsx
+let [x, setX] = createSignal(0)
+
+<d-rect x={x()} w={40} h={40} color="tomato" />
+```
+
+The reactive and control-flow vocabulary comes from SolidJS 2.0 and is
+re-exported from `@solidrt/core`, so an app imports everything from one
+place: `createSignal`, `createMemo`, `createEffect`, `createStore`,
+`onCleanup`, and the control-flow components `For`, `Show`, `Switch`,
+`Match`, `Loading`, `Errored`.
+
+Because props are values rather than accessors, the usual Solid rules apply:
+do not destructure props, and read reactive values inside the expression
+that uses them.
+
+An error thrown while computing an element's props or a child expression is
+contained at that element: it keeps its last good value, the error is logged
+once with the node and source line, and the element recovers when the
+expression computes again. An error nothing claims (a throwing effect, an
+error during mount) replaces the app's window with an error window showing
+the message and stack, with a Reset that retries; the reactive system keeps
+running either way. `<Errored>` gives a subtree its own fallback.
+
+## Layout
+
+Layout is flexbox, plus a line-based subset of CSS grid, over the whole
+element tree. Prop names match CSS: `flexDirection`, `alignItems`,
+`justifyContent`, `gap`, `padding`, `width`, `position`, `top`.
+
+Units are simpler than CSS. A bare number is pixels; a percentage is
+`pct(50)`, a branded value rather than a parsed string:
+
+```tsx
+<view flexDirection="row" gap={8} padding={16}>
+  <view width={pct(50)} />
+</view>
+```
+
+`position` has `relative` and `absolute` only, and an absolute element does
+not itself become a containing block: it resolves against the nearest
+ancestor with `position="relative"`.
+
+## Input
+
+Pointer, wheel, and key events are props on any element:
+`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerEnter`,
+`onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`. Events travel from the
+hit leaf up to the root, and `stopPropagation()` ends the walk. Key events
+bubble the same way, starting at the focused node - or at the window root
+when nothing is focused, so `onKeyDown` on the window is where app-global
+shortcuts live.
+
+Text entry goes to the focused node's `onTextInput`. Focusing a field never
+raises the on-screen keyboard by itself - a tap on the field (or an explicit
+`startTextInput()`) does, and never while a physical keyboard is attached.
+
+Coordinates are logical points, so a handler reads the same numbers on a
+high-density phone screen as on a desktop monitor.
+
+## Frames and animation
+
+`onFrame(callback)` runs before every painted frame with the frame time in
+ms, the frame count, and the display refresh rate; it returns a disposer and
+cleans itself up with the reactive scope it was called in. Rendering is
+demand-driven: the runtime does not spin a render loop when nothing changed,
+so an idle app is genuinely idle.
+
+```tsx
+let [t, setT] = createSignal(0)
+onFrame((tick) => setT(tick))
+
+<d-view rotate={t() / 1000}>...</d-view>
+```
+
+## Environment and devices
+
+`env` and `capabilities` describe where the app is running: `env` is what
+is observed (system theme, text scale, orientation, visibility, connected
+input devices), `capabilities` what follows from it for behavior (hover,
+touch, precise pointer, keyboard navigation, window size class). Which
+runtime features exist on this build is `Flux.capabilities`, by name, never
+by guessing from the OS.
+
+Window-shaped values are reactive too: `windowSize()`, `safeArea()`,
+`displayScale()`, `keyboardHeight()`, `windowFocused()`.
+
+Device access follows the same reactive shape, as `create*` primitives
+imported from Core subpaths rather than an imperative API:
+
+```tsx
+import { createCamera } from "@solidrt/core/camera"
+
+let camera = createCamera()
+
+<texture src={camera.texture()} fit="cover" />
+```
+
+The same pattern covers `@solidrt/core/microphone`, `/sound`,
+`/speech-recognition`, `/text-input`, `/image`, `/color`, and `/gpu`.
+
+## Reference
+
+The [reference](/core/reference/) covers the API by subject: the element
+vocabulary, drawing, text, detached elements, layout, transforms, input,
+shaders, the GPU module, and the shared types. It shows the shipped declarations themselves,
+so it says exactly what your editor says.

package/docs/reference/detached.md

@@ -0,0 +1,85 @@
+# Detached elements
+
+Every painting element has a detached twin: `d-view`, `d-rect`, `d-oval`,
+`d-line`, `d-path`, `d-text`, `d-texture`. A detached element has no layout
+box. It is not part of the layout at all, and instead owns its geometry in
+paint-space pixels, positioned in the coordinate system of its parent.
+
+That is the whole idea, and the reason to reach for one:
+
+```tsx
+let [x, setX] = createSignal(0)
+onFrame((now) => setX(Math.sin(now / 500) * 100))
+
+<view width={pct(100)} height={200}>
+  <d-rect x={x()} y={20} w={40} h={40} color="tomato" />
+</view>
+```
+
+Moving that rect writes one number to one native property. Nothing reflows,
+because there is nothing in the layout to reflow. The same content as a
+laid-out `<rect>` with `left={x()}` would put the layout engine on the path of
+every frame.
+
+**Reach for the detached form first for anything that moves at animation
+frequency**, and for content authored in fixed design units - a chart, a
+diagram, an svg drawing, a particle field. Reach for the layout form when you
+want the element to participate in a flex or grid arrangement, which is most
+static UI.
+
+## What changes
+
+A detached element composes exactly the same paint, text and pointer props as
+its layout twin. One thing is swapped: the [layout](/core/reference/layout/)
+props are replaced by geometry props.
+
+| | Layout form | Detached form |
+| --- | --- | --- |
+| Position | flex or grid placement, `top`/`left`, margins | `x`, `y` in the parent's coordinates |
+| Size | `width`/`height` and the box it is given | `w`, `h`, defaulting to the inherited box |
+| Costs a reflow | yes | no |
+
+`d-view` is the container case: it composes `ViewOwnProps` directly (see
+[elements](/core/reference/elements/)), so it still transforms, clips and
+takes input, but a layout prop on it is dropped with a one-time warning
+rather than silently ignored.
+
+`<span>` has no detached form, since an inline run never has a box of its own
+to detach from.
+
+## Geometry
+
+Detached geometry is paint-space pixels and never affects layout.
+
+{{ decl packages/core/src/types.d.ts PositionProps }}
+
+Most primitives add a size, defaulting to the box they inherit from their
+ancestor, so a `d-rect` with only `x`/`y` still has something to draw:
+
+{{ decl packages/core/src/types.d.ts GeometryProps }}
+
+`d-oval` measures its box rather than a radius:
+
+{{ decl packages/core/src/types.d.ts OvalGeometryProps }}
+
+For `d-text`, width is the shaping width and height is reported bounds only,
+since a paragraph's height always falls out of the text itself:
+
+{{ decl packages/core/src/types.d.ts TextGeometryProps }}
+
+`d-path` takes only a position, since its size is whatever its `d` string
+draws. `d-line` has no width and height either: its geometry is its two
+endpoints (or, as a polyline, its `points`), which is what makes it the
+primitive to reach for when the geometry moves. Both report their bounds
+(getBoundingBox, the tree, a capture) as that geometry plus the stroke, not
+the inherited box:
+
+{{ decl packages/core/src/types.d.ts LineGeometryProps }}
+
+## The other x and y
+
+`x` and `y` also appear on [transform](/core/reference/transforms/) props,
+where they mean a post-layout subtree translation and exist on laid-out views
+too. The two never collide on one element: on a `d-*` primitive `x`/`y` is
+where the geometry is drawn, and on a `view` or `d-view` it is a translation
+applied to the whole subtree. Both are cheap; neither triggers layout.

package/docs/reference/drawing.md

@@ -0,0 +1,95 @@
+# Drawing
+
+The primitives that put pixels on the screen: `rect`, `oval`, `line`, `path`
+and `texture`. They share one paint vocabulary and differ only in the geometry
+they draw.
+
+In their layout form they take no geometry props at all. A shape derives its
+geometry from the layout box it sits in, which is why a `rect` with no props
+fills its parent. To place one freely, use the
+[detached form](/core/reference/detached/) instead.
+
+## Paint
+
+Fill, stroke and blending, shared by every drawing primitive:
+
+{{ decl packages/core/src/types.d.ts PaintProps }}
+
+`color` takes a CSS color string or a gradient from `createLinearGradient` /
+`createRadialGradient`. `drawStyle` picks fill, stroke, or both, and the
+stroke props apply to the stroked part.
+
+Where the stroke sits relative to the geometry differs by primitive, and it is
+deliberate: a stroked `rect` or `oval` paints *inside* its box like a CSS
+border, so nothing bleeds past the box for a clip to cut, while `line` and
+`path` strokes stay centered on their geometry, where the geometry is the
+stroke rather than a box.
+
+## Dashing
+
+A stroke's dash pattern, on `line` and `path`:
+
+{{ decl packages/core/src/types.d.ts DashProps }}
+
+The pattern is walked along the geometry itself: through a polyline's
+vertices and along a path's curves, restarting at each subpath of a path.
+`dashOffset` slides it - write it every frame for marching ants, or
+transition it for a one-shot slide. A dashed stroke keeps its caps on every
+dash, and a stroke-and-fill path dashes only the stroke.
+
+`pathLength` declares what the geometry's length counts as, so the pattern
+can be written in fractions of it: with `pathLength={1}`, `onLength={0.77}
+offLength={1}` draws the first 77%, and transitioning `onLength` from 0 to
+1 draws the geometry on (the SVG line-drawing trick, without having to know
+the length).
+
+## rect
+
+{{ decl packages/core/src/types.d.ts RectProps }}
+
+## oval
+
+{{ decl packages/core/src/types.d.ts OvalProps }}
+
+## line
+
+{{ decl packages/core/src/types.d.ts LineProps }}
+
+A laid-out `<line>` without `points` draws its box's top-left-to-bottom-right
+diagonal, so in practice it is a rule: give it a thin box. Endpoints are a
+detached-only concept, so arbitrary angles and connectors want `d-line`.
+`points` makes either form a polyline - a flat `[x0, y0, x1, y1, ...]` array
+(or a `Float32Array`), optionally `closed` - the numeric middle ground between
+a segment and a path: animate it by writing a new array, nothing is parsed.
+Curves want a path.
+
+## path
+
+{{ decl packages/core/src/types.d.ts PathProps }}
+
+`d` is an SVG path string. Reach for `line` instead when the geometry is
+numbers that animate (endpoints, or a polyline's `points`): a path animates
+by rebuilding its `d` string, where a line moves one number or one array.
+A path dashes like a line (see Dashing above), the pattern restarting at
+each subpath; the dash props are paint-only writes, the `d` is not re-parsed.
+
+## texture
+
+A GPU texture: a decoded image, a camera frame, a video frame, or a shader
+render target. `src` is a texture id, never a URL, which keeps one currency
+for every pixel source in the engine.
+
+{{ decl packages/core/src/types.d.ts TextureProps }}
+
+## Logo
+
+The SolidRT brand mark, the same seven-segment puzzle the scaffold's welcome
+screen and the launcher draw, as a component: a square `view` of `size`
+pixels with the segments as gradient-filled `d-path`s.
+
+{{ decl packages/core/src/logo.tsx LogoProps }}
+
+The default is static and requests no frames; `"once"` and `"loop"` drive a
+staggered per-segment fade through `onFrame`, so the animated forms hold a
+frame request only while they run (`"once"` releases it when the last
+segment is in).

package/docs/reference/elements.md

@@ -0,0 +1,56 @@
+# Elements
+
+The two structural elements. Neither one paints: `window` is the root, `view`
+is a box that lays out, clips, transforms and receives input. Everything
+visible comes from the [drawing](/core/reference/drawing/) and
+[text](/core/reference/text/) primitives inside them.
+
+## window
+
+One per app, the root of the tree. It composes
+[layout](/core/reference/layout/) props, so the window is itself the outermost
+flex container, and [pointer](/core/reference/input/) props, which is where
+app-global key handling lives: key events always end their walk at the window
+root.
+
+{{ decl packages/core/src/types.d.ts WindowProps }}
+
+The `shader` prop runs the finished frame through a GPU program as the last
+step before the screen; see [shaders](/core/reference/shaders/).
+
+## view
+
+A `view` never paints. There is no `backgroundColor`: you put a `rect` behind
+the content, and a shape with no geometry of its own fills the layout box it
+sits in.
+
+```tsx
+<view padding={16} alignItems="center">
+  <rect color="#1b2440" radius={12} />
+  <text color="white">Boxed</text>
+</view>
+```
+
+Its props split in two. `ViewOwnProps` is everything a view offers besides
+layout, and it is what the detached `d-view` composes on its own:
+
+{{ decl packages/core/src/types.d.ts ViewOwnProps }}
+
+The laid-out `view` is that plus the layout props:
+
+{{ decl packages/core/src/types.d.ts ViewProps }}
+
+Three of those props are worth knowing before you need them:
+
+- `designSize` fits a design-space coordinate system into the element's box,
+  scaled uniformly and centered. Everything under the view - layout, paint,
+  input - happens in design units, and the view itself sizes like a
+  replaced element whose intrinsic size is the design size. It is the
+  natural wrapper for `parseSvg` output, any `d-*` subtree authored in
+  fixed units, or a whole laid-out panel that should scale rather than
+  reflow.
+- `repaintBoundary` retains the subtree's display list, and in its
+  `"snapshot"` forms its rasterized pixels too. It is the lever for putting
+  heavy static content next to content that changes every frame.
+- `clipRadius` rounds the clip, and only does anything when `overflow` is
+  non-visible.