@solidrt/core 0.0.10 → 0.0.11

package/AGENTS.md

@@ -0,0 +1,108 @@
+# @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.
+
+SolidRT is a custom SolidJS renderer: it paints through a Rust runtime, not the
+DOM. There is no HTML, no CSS cascade, no `className`.
+
+## Setup
+
+```sh
+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.
+
+tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
+
+```json
+{ "compilerOptions": {
+  "jsx": "preserve",
+  "jsxImportSource": "@solidrt/core",
+  "moduleResolution": "bundler",
+  "strict": true
+} }
+```
+
+Peer deps @solidjs/signals and @solidjs/universal must match (currently
+2.0.0-beta.14); 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.
+
+- Two kinds of element:
+  - Containers - `<window>`, `<view>`. Do layout + transform + pointer events.
+    THEY DO NOT PAINT. A `<view>` has no background/fill prop.
+  - Draw primitives - `<rect>`, `<oval>`, `<path>`, `<texture>`, `<text>`.
+    These paint. To give a view a background, render a draw primitive (e.g.
+    `<d-rect>`) as a child, behind the content.
+
+- Paint color is the `color` prop (a CSS color string). There is NO `fill`,
+  `stroke`, or `background` prop (some older doc examples are wrong about this).
+  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`, `path`,
+  `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`, `d-oval`,
+  `d-path`, `d-texture`, `d-text`. NOTE: `<line>` has a LineProps type but is
+  NOT a registered intrinsic - it will not typecheck.
+
+- Plain vs `d-` variant (the `d-` prefix means "detached" - detached from the
+  layout engine, Taffy): a plain element (e.g. `rect`) is `RectProps &
+  LayoutProps`, so it draws AND is laid out by Taffy. The detached variant
+  (`d-rect`) is `RectProps` only - it draws but is NOT in the layout pass; you
+  place it yourself with `x`/`y` (omit them and it fills the parent, which is
+  how backgrounds work). Reach for `d-` whenever you want explicit coordinate
+  positioning instead of layout. It is also a performance lever: for many
+  directly-positioned, often-animating elements (e.g. hundreds of balls), `d-`
+  skips the per-element layout that plain elements would incur.
+
+- Events: there is NO `onClick`/`onPress`. A "button" is a `<view>`/`<rect>`
+  with `onPointerDown`. Handlers: onPointerDown/Up/Move/Enter/Leave, onWheel,
+  onKeyDown/Up, onTextInput, onFocus/onBlur. Text entry: focus a node with an
+  `onTextInput` handler (setFocus activates the on-screen keyboard).
+
+- Reactivity is plain SolidJS (`createSignal`, `createEffect`, ... from
+  @solidjs/signals). Per-frame work: `onFrame((tick, frame) => {})` (returns a
+  cleanup; auto-cleaned inside a reactive scope). Also onResize, onLayout,
+  onWindowFocus, onWindowBlur.
+
+- Device/GPU access via subpath imports: @solidrt/core/camera, /microphone,
+  /speech, /gpu. Image flow: `decodeImage(bytes)` -> `createTexture(data,w,h)`
+  -> `<texture src={id} />`.
+
+## Minimal app, core primitives only (verified to render)
+
+```tsx
+import { render } from "@solidrt/core"
+import { createSignal } from "@solidjs/signals"
+
+function App() {
+  let [count, setCount] = createSignal(0)
+  return (
+    <window flexDirection="column" alignItems="center" justifyContent="center" gap={24}>
+      <d-rect color="#0b0f17" />                  {/* window background */}
+      <text color="#1f6feb" fontSize={48} fontWeight={800}>{count()}</text>
+      <view onPointerDown={() => setCount((c) => c + 1)}
+        padding={16} alignItems="center" justifyContent="center">
+        <d-rect color="#1f6feb" radius={12} />    {/* button background, underlays the label */}
+        <text color="#ffffff" fontSize={20}>increment</text>
+      </view>
+    </window>
+  )
+}
+
+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).

package/README.md

@@ -4,6 +4,8 @@ A low-level toolkit for creating cross-platform applications.
 
 _SolidRT is in pre-alpha stage. Anything can and will be changed._
 
+> LLM agents: see [AGENTS.md](./AGENTS.md) for a dense, self-contained quickstart.
+
 ## Getting started
 
 Prerequisites: [bun](https://bun.sh) (only required for development; not needed to run built apps).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -17,16 +17,17 @@
   "files": [
     "src/",
     "jsx-runtime.d.ts",
-    "LICENSE"
+    "AGENTS.md"
   ],
   "dependencies": {
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.10"
+    "@solidrt/flux-types": "0.0.11"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.14",
-    "@solidjs/universal": "2.0.0-beta.14"
+    "@solidjs/universal": "2.0.0-beta.14",
+    "solid-js": "2.0.0-beta.14"
   }
 }

package/src/gpu.ts

@@ -20,4 +20,27 @@ export function createMutableTexture(data: Uint8Array, width: number, height: nu
 
 export function uploadTexture(textureId: number, offset: number = 0): void {
   gpu.uploadTexture(textureId, offset)
+}
+
+// Compile a GLSL ES 3.00 fragment shader and render it into a texture, returning
+// the texture id (usable anywhere a normal texture id is, e.g. <texture src>).
+// The fragment body may reference vUV (0..1, top-left origin), iResolution,
+// iTime, and any `uniform float` it declares; pass their values via `params`.
+// `textures` binds each declared `uniform sampler2D` to an existing texture id
+// (e.g. a camera or decoded image) so the shader can read it; those inputs are
+// re-sampled on every setShaderParams call, so live sources stay current.
+export function createShader(
+  fragmentSrc: string,
+  width: number,
+  height: number,
+  params?: Record<string, number>,
+  textures?: Record<string, number>,
+): number {
+  return gpu.createShader(fragmentSrc, width, height, params, textures)
+}
+
+// Re-render an existing shader texture with new param values and request a
+// frame. Use this to animate (e.g. update iTime each frame).
+export function setShaderParams(textureId: number, params: Record<string, number>): void {
+  gpu.setShaderParams(textureId, params)
 }

package/src/index.ts

@@ -1,5 +1,5 @@
 export * from "./renderer"
-export { setFocus, getFocusedNodeId, measureText, getBoundingBox } from "./core"
+export { setFocus, getFocusedNodeId, measureText, getBoundingBox, parseColorToU32 } from "./core"
 export type { BoundingBox } from "./core"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
 export { createTexture, decodeImage } from "./gpu"

package/src/types.d.ts

@@ -40,6 +40,14 @@ declare global {
     createTexture(data: Uint8Array, width: number, height: number): number
     createMutableTexture(data: Uint8Array, width: number, height: number): number
     uploadTexture(textureId: number, offset?: number): void
+    createShader(
+      fragmentSrc: string,
+      width: number,
+      height: number,
+      params?: Record<string, number>,
+      textures?: Record<string, number>,
+    ): number
+    setShaderParams(textureId: number, params: Record<string, number>): void
     decodeImage(bytes: Uint8Array): { data: Uint8Array, width: number, height: number }
   }