@solidrt/core 0.0.50 → 0.0.52

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.

package/docs/reference/gpu.md

@@ -0,0 +1,204 @@
+# GPU
+
+`@solidrt/core/gpu` is the programmable half of rendering: textures you
+upload, shader passes that render into textures, and pipelines that draw
+your own geometry into them. Everything it produces is a texture id, and a
+texture id goes anywhere a texture goes: `<texture src={id} />` to display
+it, a `textures` binding to sample it from another pass, `readTexture` to
+bake it.
+
+The imperative primitives (`uploadTexture`, `setTargetParams`, `addDraw`,
+`destroyTexture`, ...) are the `flux:gpu` module and are documented in the
+[runtime reference](/runtime/gui/gpu/). This page is the reactive layer
+over them and the contracts that hold across both.
+
+## The model
+
+A target is retained, not redrawn. Creating one renders it once; after that
+it re-renders exactly when something it depends on changes - a param, a
+bound texture, a buffer it draws from, its size - and never otherwise. A
+static shader costs zero passes per frame.
+
+Sampler bindings are live dependencies. A target bound as another's
+`textures` input re-renders its consumer whenever it re-renders itself, in
+topological order, so a chain (a plasma pass feeding a mesh pipeline) is
+driven by writing only the first target's uniforms. A cycle throws.
+
+Targets whose pass is state rather than a function of its inputs
+(accumulation, feedback, simulation) opt out with `render: "manual"`: the
+runtime never renders them, only `renderTarget(id)` does, in call order,
+normally from `onFrame`.
+
+## Three layers
+
+- **Fused.** `createShaderTexture` compiles a fragment source and renders it
+  fullscreen; `createPipelineTexture` does the same over your own vertex
+  buffer. One call, one texture, program and target sharing a lifetime. The
+  shader-toy shape.
+- **Raw.** `compileShader`, `linkProgram`, `createRenderPipeline`, then
+  `createShaderTarget` per target. A pipeline (program plus draw state:
+  attribute layout, topology, blend, cull, depth) backs any number of targets
+  and compiles nothing per target. Reach for it when programs are shared or
+  lifetimes differ.
+- **Draw list.** `createDrawTarget` renders many entries in one pass, each
+  entry its own pipeline, buffer, params and textures, added and removed with
+  `addDraw` / `removeDraw` and sorted with `setDrawOrder`. A scene, in one
+  texture.
+
+`@solidrt/3d` builds its scene graph on the third layer; nothing there is
+hidden from this one.
+
+## Creating
+
+Every `create*` helper frees its resource when the reactive owner that
+created it is disposed. Created outside a reactive scope (after an `await`,
+in an event handler with no owner) nothing is registered and the matching
+`destroy*` is yours to call; `{ autoFree: false }` opts out of the auto-free
+inside a scope for resources rebuilt by hand. `label` names the resource in
+the dev tooling's GPU inventory and in engine log messages.
+
+{{ decl packages/core/src/gpu.ts createTexture }}
+
+{{ decl packages/core/src/gpu.ts createMutableTexture }}
+
+{{ decl packages/core/src/gpu.ts createShaderTexture }}
+
+{{ decl packages/core/src/gpu.ts createPipelineTexture }}
+
+{{ decl packages/core/src/gpu.ts createShaderTarget }}
+
+{{ decl packages/core/src/gpu.ts createDrawTarget }}
+
+{{ decl packages/core/src/gpu.ts createShaderTextureMemo }}
+
+{{ decl packages/core/src/gpu.ts ShaderSpec }}
+
+## Buffers
+
+{{ decl packages/core/src/gpu.ts createBuffer }}
+
+{{ decl packages/core/src/gpu.ts beginBufferWrite }}
+
+{{ decl packages/core/src/gpu.ts writeBuffer }}
+
+A buffer's size is fixed at creation, an entry's buffers are not: `setDraw`
+(single-draw targets) and `setDrawBuffers` (draw-list entries) re-point a
+role the entry already fills - `buffer`, `indexBuffer` + `indexFormat`,
+`instanceBuffer` - at another buffer. That is how a population grows past
+its reservation: create a larger buffer, write it, swap, destroy the old.
+The swap is replace-only (roles are pipeline layout state) and keeps the
+entry's draw range, rechecked against the new sizes.
+
+## Uniforms
+
+Uniforms are driven by name. Declaratively, `<texture src={id}
+params={{ uTime: t() }} />` writes the target's params paced to the next real
+repaint, which is the preferred form; `setTargetParams` and `setDrawParams`
+are the imperative forms for targets no element holds. A number drives a
+scalar, a flat number array drives the declared type (2, 3, 4 for `vec2`,
+`vec3`, `vec4`, 16 column-major for `mat4`, element size times length for
+arrays). `textures` binds `sampler2D` uniforms to texture ids the same way.
+
+Every write is validated at the call site against the linked program:
+
+- a name the program never declares throws, listing the active uniforms;
+- a value whose length does not fit the declared type throws;
+- a `sampler2D` named in `params` (or a non-sampler named in `textures`)
+  throws;
+- a name the source declares but the compiler optimized out is accepted
+  with a warning and skipped, so one param object can drive several shader
+  variants that do not all read every uniform.
+
+On a draw target, target-level `params` and `textures` are the shared set
+every entry reads (a camera's view-projection written once per move), applied
+before each entry's own, and a shared name only some entries declare applies
+where declared.
+
+The fused preamble declares exactly what the runtime provides: `#version
+300 es`, precision, `vUV` (fragment path), `fragColor`, and `iResolution`,
+filled with the target size in physical pixels. Anything app-driven - a time
+uniform - is the source's own declaration, driven like any other uniform, so
+forgetting to drive it is a compile error rather than a value stuck at zero.
+A source starting with its own `#version` line gets no preamble and compiles
+as written.
+
+## Sampling
+
+`filter` (`"linear"` default, `"nearest"`), `wrap` (`"clamp"` default,
+`"repeat"`) and `mipmap` (`false` default) are declared at creation and are
+a property of the texture id: `<texture>` display and shader sampling follow
+the same state, so a nearest texture upscales with hard pixels everywhere.
+Changing any of them means a new id.
+
+Without a mip chain, shader sampling of a minified texture skips texels and
+aliases (3d surfaces at distance, a target sampled at a fraction of its
+size). `mipmap: true` keeps the chain on the id and the runtime rebuilds it
+after every upload (data textures) and every render (targets) - there is
+nothing to schedule. Shader sampling then minifies through it (trilinear
+for `"linear"`, per-level nearest for `"nearest"`). The `<texture>` display
+draw samples the full-size level only, so a supersampled target shown
+through `<texture>` should stay at 2x. Rebuilding is one GPU pass per
+upload or render; a per-frame texture pays it per frame.
+
+One binding can deviate: a `textures` value may be `{ id, filter?, wrap? }`
+instead of a bare id, sampling that texture with a different filter or
+wrap in this binding only - blur a `"nearest"` atlas linearly, tile a
+clamped target in one consumer. The texture's own state stays what
+`<texture>` paints and what every other binding uses. `mipmap` is not
+overridable: the chain either exists on the id or it does not.
+
+## Blending
+
+Combining passes is a render-tree job: stack `<texture>` elements and set
+`blendMode` on them. Within one pipeline draw, `blend` on the pipeline
+decides how overlapping geometry combines: `"add"` and `"multiply"` are
+order-independent (glows, shadows); `"alpha"` composites over in draw-list
+order with premultiplied output, normally after the opaques with
+`depthWrite: false`, and nothing sorts for you (`setDrawOrder` does, or a
+scene layer above). Anything else overwrites.
+
+## The pixel contract
+
+Three facts hold for every texture and target:
+
+- **Clip space is y-down.** `gl_Position` y = -1 is the top of the target.
+  A vertex stage carrying camera-up geometry negates y or folds the flip into
+  its projection. The fragment path absorbs the flip, so `vUV` is 0..1 with
+  a top-left origin.
+- **Color is premultiplied alpha.** A target's RGB is already multiplied by
+  its A: write `vec4(rgb * a, a)`. `vec4(rgb, a)` composites as opaque.
+  `clearColor` is premultiplied too.
+- **Values are non-linear RGBA8** (or `"r8"` for single-channel data), with
+  no color-space conversion anywhere. Filtering and blending operate on the
+  stored values.
+
+## UI as a texture
+
+`snapshotTexture(ref)` (from `@solidrt/core`) is the texture id behind a
+`repaintBoundary="snapshot"` view: the subtree's rasterized pixels, usable
+wherever a texture id is - a `<texture>`, a shader or draw target binding,
+a 3d material. The id is allocated on first call and stable for the node's
+lifetime; the runtime re-points it after every re-rasterization, which
+happens only when the subtree changes, so a static panel sampled by an
+animated consumer costs no repaint. Premultiplied, top-left origin, cropped
+to the layout box. Empty until the boundary's first paint. The boundary owns
+it: `destroyTexture` on it throws, and unmounting the boundary releases it
+on the deferred-destroy path (a consumer still sampling it keeps the last
+pixels). A boundary showing its own texture is not a feedback loop: its
+rasterization is the change, so it does not re-invalidate itself.
+
+## Readback
+
+`captureSnapshot` renders a render-tree node to pixels and `readTexture`
+reads any texture back; both resolve `{ width, height, data }`. This is the
+one-shot bake path (a glyph atlas, a processed image), paid for with a
+readback stall and a paint pass of latency per call. Never per frame; to
+feed live content into a shader, bind a texture that updates in place
+instead - for a UI subtree, `snapshotTexture`.
+
+## Limits
+
+`limits` holds the device ceilings queried at startup: maximum texture and
+target size, sampler inputs per pass, vertex attributes per pipeline. Creates
+and binds validate against them and throw naming the limit; read them to
+size within the device instead.

package/docs/reference/index.md

@@ -0,0 +1,50 @@
+# Reference
+
+Core's API is its types. `@solidrt/core` ships `types.d.ts` and
+`jsx-runtime.d.ts` as sources, with a doc comment on every prop that deviates
+from the CSS or DOM meaning you already expect, so these pages show those
+declarations directly rather than paraphrasing them.
+
+They are grouped by subject, not by element. Most props live on several
+elements at once (every element takes pointer handlers, every drawing
+primitive takes paint props), so a page per element would print the same
+interface a dozen times and still not say where a prop comes from.
+
+- [Elements](/core/reference/elements/) - `window` and `view`, the structural
+  vocabulary
+- [Drawing](/core/reference/drawing/) - `rect`, `oval`, `line`, `path`,
+  `texture`, and the paint props they share
+- [Text](/core/reference/text/) - `text` and `span`
+- [Detached elements](/core/reference/detached/) - the `d-*` forms and their
+  paint-space geometry
+- [Layout](/core/reference/layout/) - flexbox, the grid subset, and the box
+  props
+- [Transforms](/core/reference/transforms/) - post-layout transform, opacity,
+  and scroll offsets
+- [Input](/core/reference/input/) - handlers and the event objects they receive
+- [Shaders](/core/reference/shaders/) - the `shader` prop on `window` and
+  `view`
+- [GPU](/core/reference/gpu/) - textures, shader targets, pipelines and the
+  draw list from `@solidrt/core/gpu`
+- [Types](/core/reference/types/) - the shared aliases
+
+## The element vocabulary
+
+Every JSX intrinsic and the prop interfaces it composes. `ref` is available on
+all of them and is left out here.
+
+{{ intrinsics packages/core/jsx-runtime.d.ts }}
+
+Read a row as the sum of its parts: `<rect>` takes paint props, pointer props
+and layout props, while `<d-rect>` swaps the layout props for detached
+geometry. The pages above cover the interfaces in that table.
+
+## Clearing a prop
+
+Writing `undefined` (or `null`) to a prop resets it to its default - the
+value it had before anything was set, per element kind. So the reactive
+pattern `scale={style()?.scale}` is safe: when the binding clears, the
+element returns to its unset state instead of erroring. On a `span`,
+clearing a prop returns the run to inheriting from its paragraph. Content
+props are the exception: `text` on a span and `d` on a path require a value.
+A wrong-typed value is an error either way.

package/docs/reference/input.md

@@ -0,0 +1,58 @@
+# Input
+
+Pointer, wheel, key and text events are props on any element. There is no
+`addEventListener` and no event registry: a handler prop is the subscription.
+
+Events travel from the hit leaf up to the root, and `stopPropagation()` ends
+the walk.
+
+## Handlers
+
+{{ decl packages/core/src/types.d.ts PointerProps }}
+
+`pointerEvents="none"` takes an element out of hit testing, and the walk skips
+it as an ancestor too, so the `parentX`/`parentY` of an event stay in the frame
+you would expect.
+
+Focus is explicit: `setFocus(node)` moves it, `onFocus`/`onBlur` report it,
+and `focusable` only marks an element as a candidate for `getFocusables()`,
+so a focus-navigation scheme (a component set's, or your own) can enumerate
+targets without the runtime imposing one.
+
+## Pointer events
+
+Coordinates are logical points, so a handler reads the same numbers on a
+high-density phone screen as on a desktop monitor. Three frames are reported,
+which is what makes drag idioms short:
+
+{{ decl packages/core/src/types.d.ts PointerEvent }}
+
+The drag idiom is `x = parentX - grab offset`, taking the grab offset from
+`localX`/`localY` at pointer down.
+
+{{ decl packages/core/src/types.d.ts WheelEvent }}
+
+## Key events
+
+Key events use the W3C UI Events vocabulary: `key` is the logical,
+layout-dependent value (`"a"`, `"!"`, `"Enter"`, `"ArrowLeft"`), and `code` is
+the physical key position (`"KeyA"`, `"Digit1"`).
+
+{{ decl packages/core/src/types.d.ts KeyEvent }}
+
+Routing differs from pointer events in where the walk starts: keydown and
+keyup dispatch along the focused node's ancestor chain and always end at the
+window root, and with nothing focused they go to the window root alone.
+`<window onKeyDown>` is therefore the app-global shortcut point.
+
+## Text entry
+
+Printable characters do not arrive as key events. Text entry goes to the
+focused node's `onTextInput`:
+
+{{ decl packages/core/src/types.d.ts TextEvent }}
+
+Focusing a field never raises the on-screen keyboard by itself. A tap on the
+field does, or an explicit `startTextInput()`, and never while a physical
+keyboard is attached. `textInputHints` on the node is read when a session
+starts.

package/docs/reference/layout.md

@@ -0,0 +1,44 @@
+# Layout
+
+Layout is flexbox plus a line-based subset of CSS grid, over the whole element
+tree. Prop names match CSS, so `flexDirection`, `alignItems`,
+`justifyContent`, `gap`, `padding` and `width` mean what you expect.
+
+These props exist on `window`, `view`, and the layout form of every drawing
+and text primitive. They do not exist on the
+[detached](/core/reference/detached/) forms, which own their geometry instead.
+
+## Units
+
+A bare number is pixels. A percentage is `pct(50)`, a branded value rather
+than a parsed string, though the `"50%"` string form is accepted so pasted CSS
+keeps working.
+
+```tsx
+<view flexDirection="row" gap={8} padding={16}>
+  <view width={pct(50)} />
+</view>
+```
+
+{{ decl packages/core/src/types.d.ts Dimension }}
+
+{{ decl packages/core/src/types.d.ts LengthPercentage }}
+
+## The box
+
+{{ decl packages/core/src/types.d.ts LayoutProps }}
+
+Two divergences from CSS are worth reading twice. `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"`. And `float` / `clear` are not page layout; they apply
+to an element child of a `<text>`, where it becomes an inline atom the lines
+wrap around.
+
+## Flexbox
+
+{{ decl packages/core/src/types.d.ts FlexboxProps }}
+
+## Grid
+
+{{ decl packages/core/src/types.d.ts GridProps }}

package/docs/reference/shaders.md

@@ -0,0 +1,46 @@
+# Shaders
+
+Two elements take a `shader` prop: `window` runs a program over the finished
+frame, and `view` runs one over its own rasterized subtree. Both are
+declarative - the pass exists while the prop is declared and the resources go
+away when it is removed.
+
+Everything about the program itself (compiling, linking, lifetime) belongs to
+the raw shading layer: `compileShader` and `linkProgram` from
+`@solidrt/core/gpu`.
+
+## The shared contract
+
+Both passes bind their input as `uniform sampler2D uSource` with a top-left
+origin, like every sampled texture in the engine, and fill `iResolution` by
+name with the pass size in physical pixels. Both fill `params` uniforms by
+name, paced to the next real repaint: a number drives a scalar, and a flat
+number array drives the declared GLSL type (2, 3 or 4 for `vec2`, `vec3`,
+`vec4`, and 16 column-major for `mat4`).
+
+## Window
+
+{{ decl packages/core/src/types.d.ts WindowShaderProps }}
+
+The window pass draws attributeless triangles with `vertexCount` vertices
+fetched via `gl_VertexID`, defaulting to a single covering triangle.
+
+## View
+
+A boundary shader requires a snapshot boundary (`repaintBoundary="snapshot"`
+or `"snapshot-no-aa"`). The cost is snapshot semantics, and it is kept
+explicit: declared without one, the shader is ignored with a warning.
+
+{{ decl packages/core/src/types.d.ts ViewShaderProps }}
+
+The pass is split from content invalidation, so animating `params` over a
+static subtree re-runs only the pass against the cached snapshot and never
+re-rasterizes it.
+
+The effect samples the subtree's own pixels and nothing else. Grading,
+warping and dissolving a panel work; anything that needs what is *behind* the
+panel does not. Hit testing stays on layout geometry, so a distortion moves
+pixels, not hit targets.
+
+`outset` grows the rasterized canvas by a transparent margin on every side,
+for effects that write past the edge such as a glow or a drop shadow.