@solidrt/core 0.0.5 → 0.0.7

package/README.md

@@ -36,7 +36,7 @@ Run the app:
 bunx srt run src/index.tsx
 ```
 
-Optionally, create a `tsconfig.json` to enable JSX support and type recognition for SolidRT elements:
+Optionally, create a `tsconfig.json` to enable type recognition for SolidRT elements:
 
 ```json
 {
@@ -51,7 +51,7 @@ Optionally, create a `tsconfig.json` to enable JSX support and type recognition
 
 ## API
 
-See [docs/api.md](https://github.com/wellawaretech/solidrt/blob/main/docs/api.md) for the full API reference.
+See [docs/core.md](https://github.com/wellawaretech/solidrt/blob/main/docs/core.md) for the full API reference.
 
 ## License
 

package/jsx-runtime.d.ts

@@ -1,6 +1,5 @@
 import type {
   WindowProps,
-  CircleProps,
   RectProps,
   OvalProps,
   PathProps,
@@ -16,7 +15,10 @@ export namespace JSX {
   type Element = SolidJSX.Element
   type ElementChildrenAttribute = SolidJSX.ElementChildrenAttribute
 
-  type RefCallback<T> = (el: T) => void
+  // Return type is unconstrained: a ref callback's return value is ignored, so
+  // an arrow like `ref={n => (this.node = n)}` (which returns the assignment)
+  // is accepted as readily as a void-returning block body.
+  type RefCallback<T> = (el: T) => unknown
   type Ref<T> = T | RefCallback<T>
 
   interface IntrinsicAttributes {
@@ -32,6 +34,7 @@ export namespace JSX {
     path: PathProps & LayoutProps
     texture: TextureProps & LayoutProps
     audio: AudioProps
+    "d-view": ViewProps
     "d-rect": RectProps
     "d-oval": OvalProps
     "d-path": PathProps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -20,10 +20,10 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.5"
+    "@solidrt/flux-types": "0.0.7"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.13",
-    "@solidjs/universal": "2.0.0-beta.13"
+    "@solidjs/signals": "2.0.0-beta.14",
+    "@solidjs/universal": "2.0.0-beta.14"
   }
 }

package/src/core.ts

@@ -0,0 +1,78 @@
+import { colord, extend } from "colord"
+import namesPlugin from "colord/plugins/names"
+import type { MeasureTextOptions } from "./types"
+extend([namesPlugin])
+
+export function parseColorToU32(color: string): number {
+  let { r, g, b, a } = colord(color).toRgb()
+  return (((r & 0xFF) << 24) | ((g & 0xFF) << 16) | ((b & 0xFF) << 8) | ((a * 255) & 0xFF)) >>> 0
+}
+
+let handlers = new Map<number, Map<string, Function>>()
+
+export function setEventHandler(nodeId: number, name: string, fn: Function | null | undefined): void {
+  if (fn == null) {
+    handlers.get(nodeId)?.delete(name)
+    return
+  }
+  let nodeHandlers = handlers.get(nodeId)
+  if (!nodeHandlers) {
+    nodeHandlers = new Map()
+    handlers.set(nodeId, nodeHandlers)
+  }
+  nodeHandlers.set(name, fn)
+}
+
+export function getEventHandler(nodeId: number, name: string): Function | undefined {
+  return handlers.get(nodeId)?.get(name)
+}
+
+export function cleanupNodeHandlers(nodeId: number): void {
+  handlers.delete(nodeId)
+}
+
+// Currently-focused node id. Reset to null automatically across engine
+// reloads because the JS environment is rebuilt from scratch.
+let focusedNodeId: number | null = null
+let textInputActive = false
+
+export function setFocus(nodeId: number | null): void {
+  if (nodeId === focusedNodeId) return
+  let oldId = focusedNodeId
+  focusedNodeId = nodeId
+  if (oldId != null) {
+    getEventHandler(oldId, "onBlur")?.()
+  }
+  if (nodeId != null) {
+    getEventHandler(nodeId, "onFocus")?.()
+  }
+  let wantActive = nodeId != null && getEventHandler(nodeId, "onTextInput") != null
+  if (wantActive !== textInputActive) {
+    textInputActive = wantActive
+    ffi.setTextInputActive(wantActive)
+  }
+}
+
+export function getFocusedNodeId(): number | null {
+  return focusedNodeId
+}
+
+export interface BoundingBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+// Returns the node's window-relative bounding box from the most recently
+// computed layout, or null if the node has no layout or has not been laid out
+// yet. This is a snapshot read, not reactive: call it inside onLayout (or an
+// event handler) to get values for the current frame. Phase 1 composes only
+// translations; x/y are wrong when a rotate/scale sits anywhere above the node.
+export function getBoundingBox(node: { id: number }): BoundingBox | null {
+  return ffi.getBoundingBox(node.id)
+}
+
+export function measureText(text: string, options?: MeasureTextOptions): { width: number, height: number } {
+  return ffi.measureText(text, options)
+}

package/src/index.ts

@@ -1,18 +1,23 @@
 export * from "./renderer"
-export { setFocus, getFocusedNodeId } from "./focus"
-export { onRender, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
-export { measureText } from "./text"
+export { setFocus, getFocusedNodeId, measureText, getBoundingBox } from "./core"
+export type { BoundingBox } from "./core"
+export { onFrame, createPacedClock, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
 export { createTexture, decodeImage } from "./gpu"
 export type { DecodedImage } from "./gpu"
 export type {
   LayoutProps,
   TransformProps,
   PointerProps,
+  PointerEvent,
+  WheelEvent,
+  KeyEvent,
+  TextEvent,
   PaintProps,
   WindowProps,
   ViewProps,
   RectProps,
   OvalProps,
+  LineProps,
   PathProps,
   TextProps,
   TextureProps,

package/src/renderer.ts

@@ -1,11 +1,9 @@
 import { createRoot, createEffect } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
 import { attachWindow } from "./window"
-import { parseColorToU32, isColorProp } from "./color"
-import { setEventHandler, cleanupNodeHandlers } from "./events"
-import { getFocusedNodeId, setFocus } from "./focus"
+import { parseColorToU32, setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
 
-export { getEventHandler } from "./events"
+export { getEventHandler } from "./core"
 
 export let nodes = new Map()
 
@@ -56,9 +54,9 @@ export let {
   },
 
   createTextNode: (value: string): ProxyNode => {
-    let proxy = createProxyNode("span")
+    let proxy = createProxyNode("d-span")
     // console.debug("[srt] createTextNode", proxy.id, value)
-    ffi.createNode(proxy.id, "span")
+    ffi.createNode(proxy.id, "d-span")
     ffi.setProperty(proxy.id, "text", "" + value)
     return proxy
   },
@@ -68,7 +66,7 @@ export let {
     ffi.setProperty(node.id, "text", "" + value)
   },
 
-  isTextNode: (node: ProxyNode): boolean => node?.elementType === "span",
+  isTextNode: (node: ProxyNode): boolean => node?.elementType === "d-span",
   setProperty: <T>(node: ProxyNode, name: string, value: T): void => {
     if (!node) return
 

package/src/types.d.ts

@@ -1,9 +1,8 @@
 /// <reference types="@solidrt/flux-types" />
 
-import type { Accessor, JSX as SolidJSX } from "@solidjs/signals"
+import type { JSX as SolidJSX } from "@solidjs/signals"
 
 declare global {
-
   let ffi: {
     createRoot(id: number): void
     createNode(id: number, kind: string): void
@@ -12,6 +11,7 @@ declare global {
     setProperty(nodeId: number, name: string, value: unknown): void
     setTextInputActive(active: boolean): void
     measureText(text: string, options?: MeasureTextOptions): { width: number, height: number }
+    getBoundingBox(id: number): { x: number, y: number, width: number, height: number } | null
   }
 
   let gpu: {
@@ -30,8 +30,6 @@ export interface MeasureTextOptions {
 
 type Children = SolidJSX.Element
 
-type OA<T> = T | Accessor<T>
-
 interface FlexboxProps {
   gap?: number
   rowGap?: number
@@ -39,7 +37,7 @@ interface FlexboxProps {
   flex?: number | "none" | "auto" | (string & {})
   flexGrow?: number
   flexShrink?: number
-  flexBasis?: number
+  flexBasis?: Dimension
 
   flexDirection?: "row" | "column" | "row-reverse" | "column-reverse"
   flexWrap?: "nowrap" | "wrap" | "wrap-reverse"
@@ -96,8 +94,8 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   overflowY?: "visible" | "clip" | "hidden" | "scroll"
 }
 
-import type { LCH } from "./color"
-export type Color = string | LCH
+// Colors are CSS color strings, parsed to a packed u32 by parseColorToU32.
+export type Color = string
 
 export interface PaintProps {
   color?: Color
@@ -110,28 +108,48 @@ export interface PaintProps {
 }
 
 export interface TransformProps {
-  rotate?: OA<number>
-  scale?: OA<number>
-  x?: OA<number>
-  y?: OA<number>
-  cx?: OA<number>
-  cy?: OA<number>
-  scrollX?: OA<number>
-  scrollY?: OA<number>
+  rotate?: number
+  scale?: number
+  x?: number
+  y?: number
+  cx?: number
+  cy?: number
+  scrollX?: number
+  scrollY?: number
+}
+
+export interface PointerEvent {
+  x: number
+  y: number
+}
+
+export interface WheelEvent {
+  x: number
+  y: number
+  deltaX: number
+  deltaY: number
+}
+
+export interface KeyEvent {
+  key: string
+}
+
+export interface TextEvent {
+  text: string
 }
 
 export interface PointerProps {
-  onPointerDown?: Function
-  onPointerUp?: Function
-  onPointerMove?: Function
-  onPointerEnter?: Function
-  onPointerLeave?: Function
-  onWheel?: Function
-  onFocus?: Function
-  onBlur?: Function
-  onKeyDown?: Function
-  onKeyUp?: Function
-  onTextInput?: Function
+  onPointerDown?: (event: PointerEvent) => void
+  onPointerUp?: (event: PointerEvent) => void
+  onPointerMove?: (event: PointerEvent) => void
+  onPointerEnter?: (event: PointerEvent) => void
+  onPointerLeave?: (event: PointerEvent) => void
+  onWheel?: (event: WheelEvent) => void
+  onFocus?: () => void
+  onBlur?: () => void
+  onKeyDown?: (event: KeyEvent) => void
+  onKeyUp?: (event: KeyEvent) => void
+  onTextInput?: (event: TextEvent) => void
   pointerEvents?: "auto" | "none" | "all"
 }
 
@@ -175,12 +193,21 @@ export interface OvalProps extends Position, PaintProps, PointerProps {
   h?: number
 }
 
+export interface LineProps extends PaintProps, PointerProps {
+  x1?: number
+  y1?: number
+  x2?: number
+  y2?: number
+  onLength?: number
+  offLength?: number
+}
+
 export interface PathProps extends Position, PaintProps, PointerProps {
   d?: string
   fillRule?: "nonZero" | "evenOdd"
 }
 
-export interface TextProps extends PaintProps {
+export interface TextProps extends PaintProps, PointerProps {
   children?: Children
   fontFamily?: "sans" | "mono" | (string & {})
   fontSize?: number

package/src/window.ts

@@ -1,21 +1,27 @@
-import { onCleanup, onSettled } from "@solidjs/signals"
-import { getEventHandler } from "./events"
-import { getFocusedNodeId, setFocus } from "./focus"
+import { onCleanup, onSettled, flush, createSignal } from "@solidjs/signals"
+import { getEventHandler, getFocusedNodeId, setFocus } from "./core"
 
 // ------ Animation frames ----------------
 
 let nextFrameId = 1
 let animationFrames = new Map<number, Function>()
 
+// Latest display refresh rate (Hz) reported by the runtime, passed to onFrame
+// callbacks. Defaults to 60 until the first displayRefreshRate event arrives.
+let refreshRate = 60
+
 /**
- * Calls `fn` on every rendered frame. Returns a cleanup function to stop rendering.
- * When called within a reactive scope (e.g. a component or createEffect), cleanup is also automatic.
+ * Calls `fn` before every frame is painted, with the raw runtime signals: `tick`
+ * is the unsmoothed wall-clock time in ms sampled at present, `frame` is the
+ * present count, and `rate` is the current refresh rate in Hz. No pacing is
+ * applied; see createPacedClock for an opt-in smooth clock.
+ * Returns a cleanup function; also auto-cleans within a reactive scope.
  */
-export function onRender(fn: (tick: number, frame: number) => void) {
+export function onFrame(fn: (tick: number, frame: number, rate: number) => void) {
   let frameId: number = null!
 
-  let extendedFn = (tick: number, frame: number) => {
-    fn(tick, frame)
+  let extendedFn = (tick: number, frame: number, rate: number) => {
+    fn(tick, frame, rate)
     frameId = nextFrameId++
     animationFrames.set(frameId, extendedFn)
   }
@@ -28,6 +34,26 @@ export function onRender(fn: (tick: number, frame: number) => void) {
   return cleanup
 }
 
+/**
+ * Opt-in smooth clock built on the raw onFrame signals. Paces by present count
+ * (one refresh period per frame) and slowly corrects toward the raw wall-clock
+ * tick, so it stays smooth while keeping up and tracks real time when the
+ * framerate drops. `gain` (0..1) trades convergence speed for jitter. Returns an
+ * accessor for the paced time in milliseconds.
+ */
+export function createPacedClock(opts?: { gain?: number }) {
+  let gain = opts?.gain ?? 0.05
+  let [time, setTime] = createSignal(0)
+  let clock = 0
+  onFrame((tick, _frame, rate) => {
+    let period = 1000 / rate
+    clock += period
+    clock += (tick - clock) * gain
+    setTime(clock)
+  })
+  return time
+}
+
 // ------ Resize ----------------
 
 interface SafeArea {
@@ -86,57 +112,78 @@ export function attachWindow(_nodeId: number) {
   let unsubKeyUp: () => void = null!
   let unsubTextInput: () => void = null!
   let unsubKeyboardVisibility: () => void = null!
+  let unsubRefreshRate: () => void = null!
+  let unsubFirstResize: (() => void) | null = null
+
+  function runFrame(t: number, frame: number) {
+    if (animationFrames.size > 0) {
+      let frames = animationFrames
+      animationFrames = new Map()
+      for (let fn of frames.values()) fn(t, frame, refreshRate)
+    }
+    flush()
+    draw()
+  }
 
   onSettled(() => {
-    unsubscribe = Flux.on("render", ({ time, frame }: { time: number, frame: number }) => {
-      if (animationFrames.size > 0) {
-        let frames = animationFrames
-        animationFrames = new Map()
-
-        let t = (time * 1000) | 0
-        for (let fn of frames.values()) fn(t, frame)
-      }
-
-      draw()
+    // Sticky event: a late subscriber still receives the current rate.
+    unsubRefreshRate = Flux.on("displayRefreshRate", ({ hz }: { hz: number }) => {
+      if (hz > 0) refreshRate = hz
     })
 
-    unsubDown = Flux.on("pointerDown", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onPointerDown")?.(e)
-      }
-      // Outside-tap blur. Read focus AFTER per-node handlers so a tap that
-      // moves focus to a new node is not immediately blurred again.
-      let focused = getFocusedNodeId()
-      if (focused != null && !targets.includes(focused)) {
-        setFocus(null)
-      }
+    unsubscribe = Flux.on("render", ({ time, frame }: { time: number; frame: number }) => {
+      runFrame(time * 1000, frame)
     })
 
-    unsubUp = Flux.on("pointerUp", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
+    unsubDown = Flux.on(
+      "pointerDown",
+      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
+        for (let nodeId of targets) {
+          getEventHandler(nodeId, "onPointerDown")?.(e)
+        }
+        // Outside-tap blur. Read focus AFTER per-node handlers so a tap that
+        // moves focus to a new node is not immediately blurred again.
+        let focused = getFocusedNodeId()
+        if (focused != null && !targets.includes(focused)) {
+          setFocus(null)
+        }
+      },
+    )
+
+    unsubUp = Flux.on("pointerUp", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
       for (let nodeId of targets) {
         getEventHandler(nodeId, "onPointerUp")?.(e)
       }
     })
 
-    unsubMove = Flux.on("pointerMove", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onPointerMove")?.(e)
-      }
-    })
-
-    unsubEnter = Flux.on("pointerEnter", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onPointerEnter")?.(e)
-      }
-    })
-
-    unsubLeave = Flux.on("pointerLeave", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onPointerLeave")?.(e)
-      }
-    })
-
-    unsubWheel = Flux.on("wheel", ({ targets, ...e }: { targets: number[], [k: string]: any }) => {
+    unsubMove = Flux.on(
+      "pointerMove",
+      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
+        for (let nodeId of targets) {
+          getEventHandler(nodeId, "onPointerMove")?.(e)
+        }
+      },
+    )
+
+    unsubEnter = Flux.on(
+      "pointerEnter",
+      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
+        for (let nodeId of targets) {
+          getEventHandler(nodeId, "onPointerEnter")?.(e)
+        }
+      },
+    )
+
+    unsubLeave = Flux.on(
+      "pointerLeave",
+      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
+        for (let nodeId of targets) {
+          getEventHandler(nodeId, "onPointerLeave")?.(e)
+        }
+      },
+    )
+
+    unsubWheel = Flux.on("wheel", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
       for (let nodeId of targets) {
         getEventHandler(nodeId, "onWheel")?.(e)
       }
@@ -169,8 +216,16 @@ export function attachWindow(_nodeId: number) {
       if (!shown) setFocus(null)
     })
 
-    // trigger first draw
-    draw()
+    // Bootstrap the first frame on the first resize event: by then any
+    // onResize subscribers (which run earlier in the dispatch list) have
+    // set their initial signal values, so runFrame's flush sees a fully
+    // initialized graph. Resize is a sticky event in Flux, so it can replay
+    // synchronously here, while we are still inside this onSettled callback
+    // where flush() is illegal (not reentrant). Defer runFrame to a microtask
+    // so the first frame always runs after this callback returns.
+    unsubFirstResize = Flux.once("resize", () => {
+      queueMicrotask(() => runFrame(0, 0))
+    })
   })
 
   onCleanup(() => {
@@ -185,5 +240,7 @@ export function attachWindow(_nodeId: number) {
     if (unsubKeyUp) unsubKeyUp()
     if (unsubTextInput) unsubTextInput()
     if (unsubKeyboardVisibility) unsubKeyboardVisibility()
+    if (unsubRefreshRate) unsubRefreshRate()
+    if (unsubFirstResize) unsubFirstResize()
   })
 }

package/src/color.ts

@@ -1,9 +0,0 @@
-import { colord, extend } from "colord"
-import namesPlugin from "colord/plugins/names"
-extend([namesPlugin])
-
-// Parses any CSS color string and returns a packed u32: 0xRRGGBBAA
-export function parseColorToU32(color: string): number {
-  let { r, g, b, a } = colord(color).toRgb()
-  return (((r & 0xFF) << 24) | ((g & 0xFF) << 16) | ((b & 0xFF) << 8) | ((a * 255) & 0xFF)) >>> 0
-}

package/src/events.ts

@@ -1,22 +0,0 @@
-let handlers = new Map<number, Map<string, Function>>()
-
-export function setEventHandler(nodeId: number, name: string, fn: Function | null | undefined): void {
-  if (fn == null) {
-    handlers.get(nodeId)?.delete(name)
-    return
-  }
-  let nodeHandlers = handlers.get(nodeId)
-  if (!nodeHandlers) {
-    nodeHandlers = new Map()
-    handlers.set(nodeId, nodeHandlers)
-  }
-  nodeHandlers.set(name, fn)
-}
-
-export function getEventHandler(nodeId: number, name: string): Function | undefined {
-  return handlers.get(nodeId)?.get(name)
-}
-
-export function cleanupNodeHandlers(nodeId: number): void {
-  handlers.delete(nodeId)
-}

package/src/focus.ts

@@ -1,27 +0,0 @@
-import { getEventHandler } from "./events"
-
-// Currently-focused node id. Reset to null automatically across engine
-// reloads because the JS environment is rebuilt from scratch.
-let focusedNodeId: number | null = null
-let textInputActive = false
-
-export function setFocus(nodeId: number | null): void {
-  if (nodeId === focusedNodeId) return
-  let oldId = focusedNodeId
-  focusedNodeId = nodeId
-  if (oldId != null) {
-    getEventHandler(oldId, "onBlur")?.()
-  }
-  if (nodeId != null) {
-    getEventHandler(nodeId, "onFocus")?.()
-  }
-  let wantActive = nodeId != null && getEventHandler(nodeId, "onTextInput") != null
-  if (wantActive !== textInputActive) {
-    textInputActive = wantActive
-    ffi.setTextInputActive(wantActive)
-  }
-}
-
-export function getFocusedNodeId(): number | null {
-  return focusedNodeId
-}

package/src/text.ts

@@ -1,5 +0,0 @@
-import type { MeasureTextOptions } from "./types"
-
-export function measureText(text: string, options?: MeasureTextOptions): { width: number, height: number } {
-  return ffi.measureText(text, options)
-}