@solidrt/core 0.0.27 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.27"
+    "@solidrt/flux-types": "0.0.28"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.17",

package/src/image.ts

@@ -3,7 +3,7 @@
 // top that fetches/decodes/uploads for you and swaps the texture when the source
 // changes - the same relationship createTexture/createShader have to flux:gpu.
 
-import { createMemo, onCleanup, NotReadyError } from "@solidjs/signals"
+import { createMemo, onCleanup } from "@solidjs/signals"
 import { createTexture, destroyTexture } from "./gpu"
 
 export type DecodedImage = {
@@ -24,6 +24,80 @@ export function decodeImage(bytes: Uint8Array): DecodedImage {
 
 export type ImageSource = string | Uint8Array
 
+// Shared loader for URL sources. Every mount of the same URL shares one
+// fetch/decode/texture (refcounted; the texture is destroyed when the last
+// mount releases it). Byte caching and fetch politeness live below, in the
+// runtime's fetch layer (disk cache + per-host limit); this map exists for
+// what a byte cache cannot provide, sharing the decoded GPU texture.
+// Uint8Array sources bypass all of this: no key, per-mount texture.
+type ImageEntry = {
+  refs: number
+  texture: number
+  promise: Promise<number>
+}
+
+let imageCache = new Map<string, ImageEntry>()
+
+async function loadImage(url: string): Promise<number> {
+  // Images are assets: cache to disk, no freshness. Use a versioned URL (or
+  // fetch + decodeImage manually) when a URL's content must be re-checked.
+  let res = await fetch(url, { cache: "force-cache" })
+  if (!res.ok) throw new Error(`Image fetch failed: HTTP ${res.status} for ${url}`)
+  let bytes = await res.bytes()
+  let decoded: DecodedImage
+  try {
+    decoded = decodeImage(bytes)
+  } catch (e) {
+    throw new Error(`Image decode failed for ${url} (first bytes: ${sniffBytes(bytes)}): ${e}`)
+  }
+  return createTexture(decoded.data, decoded.width, decoded.height)
+}
+
+function acquireImage(url: string): ImageEntry {
+  let entry = imageCache.get(url)
+  if (!entry) {
+    let e: ImageEntry = { refs: 0, texture: -1, promise: undefined as never }
+    e.promise = loadImage(url).then(
+      id => {
+        // Everyone released while the load was in flight: nothing owns the
+        // texture, so drop it here instead of recording it.
+        if (e.refs === 0) {
+          destroyTexture(id)
+          imageCache.delete(url)
+        } else {
+          e.texture = id
+        }
+        return id
+      },
+      err => {
+        // Concurrent mounts shared this rejection; dropping the entry lets a
+        // later remount retry (a transient failure recovers with the network).
+        imageCache.delete(url)
+        throw err
+      },
+    )
+    // Awaiters observe the rejection; this keeps a fully-released failed
+    // entry from surfacing as an unhandled rejection.
+    e.promise.catch(() => {})
+    imageCache.set(url, e)
+    entry = e
+  }
+  entry.refs++
+  return entry
+}
+
+function releaseImage(url: string): void {
+  let entry = imageCache.get(url)
+  if (!entry) return
+  entry.refs--
+  if (entry.refs > 0) return
+  if (entry.texture >= 0) {
+    destroyTexture(entry.texture)
+    imageCache.delete(url)
+  }
+  // Still pending: the settle handler above sees refs === 0 and cleans up.
+}
+
 /**
  * Loads an image as an async computation and returns a reactive accessor for its
  * GPU texture id. This is a SolidJS 2.0 async value: reading it suspends until
@@ -35,6 +109,13 @@ export type ImageSource = string | Uint8Array
  * `<texture src={id()} />`; the texture carries its own pixel size, so no
  * width/height is needed unless you want to scale it.
  *
+ * URL loads are shared: mounts of the same URL reuse one fetch and one texture
+ * (freed when the last user is disposed). The bytes are fetched with
+ * `cache: "force-cache"` - images are assets, cached on disk with no
+ * freshness check - so use a versioned URL when the content behind a URL can
+ * change. A failed load rejects every mount sharing it; a later remount
+ * retries.
+ *
  * For bytes you already hold (a `with { type: "binary" }` import, or anything in
  * memory) this suspends needlessly: `decodeImage` + `createTexture` are both
  * synchronous, so reach for them directly and skip the `<Loading>` boundary.
@@ -43,29 +124,43 @@ export type ImageSource = string | Uint8Array
  */
 export function createImage(src: ImageSource | (() => ImageSource)): () => number {
   let getSrc = typeof src === "function" ? src : () => src
-  let generation = 0
 
   return createMemo<number>(async () => {
     let source = getSrc()
-    let mine = ++generation
 
-    // Register cleanup synchronously, before the await: an onCleanup added after
-    // an await is orphaned because the reactive owner is not restored across it.
-    // The holder is filled in once the texture exists.
+    if (typeof source === "string") {
+      // Acquire and register cleanup synchronously, before the await: an
+      // onCleanup added after an await is orphaned because the reactive owner
+      // is not restored across it.
+      let entry = acquireImage(source)
+      onCleanup(() => releaseImage(source))
+      return await entry.promise
+    }
+
+    // Byte sources decode and upload synchronously; this run owns the texture.
     let holder = { id: -1 }
     onCleanup(() => {
       if (holder.id >= 0) destroyTexture(holder.id)
     })
-
-    let bytes = typeof source === "string" ? await (await fetch(source)).bytes() : source
-
-    // If the source changed while we were loading, this run is superseded. Skip
-    // the GPU upload and stay pending: a texture created here would leak, since
-    // superseded async runs are not otherwise cleaned up. The newer run wins.
-    if (mine !== generation) throw new NotReadyError(source)
-
-    let { data, width, height } = decodeImage(bytes)
-    holder.id = createTexture(data, width, height)
+    let decoded: DecodedImage
+    try {
+      decoded = decodeImage(source)
+    } catch (e) {
+      throw new Error(`Image decode failed (first bytes: ${sniffBytes(source)}): ${e}`)
+    }
+    holder.id = createTexture(decoded.data, decoded.width, decoded.height)
     return holder.id
   })
+}
+
+// A payload that fails to decode is usually not an image at all (an HTML error
+// page, a JSON error body); showing its first bytes makes that recognizable in
+// the log without a debugger.
+function sniffBytes(bytes: Uint8Array): string {
+  let head = ""
+  for (let i = 0; i < Math.min(bytes.length, 24); i++) {
+    let b = bytes[i] ?? 0
+    head += b >= 32 && b < 127 ? String.fromCharCode(b) : "."
+  }
+  return JSON.stringify(head)
 }

package/src/renderer.ts

@@ -1,5 +1,6 @@
 import { createRoot, onCleanup } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
+import type { Element } from "solid-js"
 import * as tree from "flux:rendertree"
 import { attachWindow } from "./window"
 import { setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
@@ -87,6 +88,25 @@ function removeNode(parent: ProxyNode, node: ProxyNode): void {
   }
 }
 
+// A property the native tree rejected must not take down the reactive system:
+// a typo'd or not-yet-implemented prop poisons only itself. Warn once per
+// element kind + property with a stack (the dev server remaps its frames to
+// the .tsx source), then ignore further writes of the same pair.
+let warnedUnknownProps = new Set<string>()
+
+function setTreeProperty(node: ProxyNode, name: string, value: unknown): void {
+  try {
+    tree.setProperty(node.id, name, value)
+  } catch (e) {
+    if (!String(e).includes("unknown property")) throw e
+    let key = node.elementType + "." + name
+    if (warnedUnknownProps.has(key)) return
+    warnedUnknownProps.add(key)
+    let stack = new Error().stack ?? ""
+    console.warn(`Ignoring unknown property '${name}' on <${node.elementType}>\n${stack}`)
+  }
+}
+
 // Applies a single prop to a node: routes events to the handler registry,
 // parses color strings/gradients, and forwards everything else to the tree.
 // Shared by the renderer's setProperty hook and by createElement, which since
@@ -103,16 +123,16 @@ function applyProp<T>(node: ProxyNode, name: string, value: T): void {
   }
 
   if (name === "color" && isGradient(value)) {
-    tree.setProperty(node.id, name, value)
+    setTreeProperty(node, name, value)
     return
   }
 
   if (name === "color" && typeof value === "string") {
-    tree.setProperty(node.id, name, parseColor(value))
+    setTreeProperty(node, name, parseColor(value))
     return
   }
 
-  tree.setProperty(node.id, name, value)
+  setTreeProperty(node, name, value)
 }
 
 export let {
@@ -245,12 +265,23 @@ export function render(code: () => any) {
  * The default mount is the window's flex root, so a portaled node that is not
  * `position: "absolute"` will take flow space and displace app content. Position
  * the portal root absolutely, or pass a `mount` target that does it for you.
+ *
+ * Returns null (nothing in place), so a component may return a portal directly.
+ *
+ * Portals cannot mount during the initial render: the default target is the
+ * window root, which exists only after the app's first build returns, so a
+ * portal created during that build throws. This is the contract, not a bug:
+ * portal content is overlay content, opened by a signal that starts false.
  */
-export function createPortal(node: ProxyNode, mount?: ProxyNode): void {
+export function createPortal(node: Element, mount?: ProxyNode): null {
   let target = mount ?? windowRoot
   if (!target) {
-    throw new Error("createPortal: no mount target (called before render()?)")
+    throw new Error("createPortal: no mount target (portals cannot mount during the initial render; open them after mount)")
+  }
+  if (node === null || typeof node !== "object" || Array.isArray(node)) {
+    throw new Error("createPortal: node must be a single built element")
   }
-  insertNode(target, node)
-  onCleanup(() => removeNode(target, node))
+  insertNode(target, node as ProxyNode)
+  onCleanup(() => removeNode(target, node as ProxyNode))
+  return null
 }

package/src/scroll.ts

@@ -49,6 +49,14 @@ export function createScroll(
 
   let [offset, setOffset] = createSignal<ScrollOffset>({ x: 0, y: 0 })
 
+  // A scroll viewport with no explicit main-axis size resolves to 0 in flex
+  // layout and its content silently vanishes - a classic trap (maxHeight alone
+  // does not size it either). Detect it at measure time and warn once, with a
+  // stack captured at creation so the warning points at the component that
+  // built the scroller (the dev server remaps the frames to .tsx).
+  let origin = new Error().stack ?? ""
+  let warnedCollapsed = false
+
   // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
   // against these between layouts; onLayout re-clamps once new sizes are known.
   let maxX = 0
@@ -72,6 +80,18 @@ export function createScroll(
     let vb = getBoundingBox(vp)
     let cb = getBoundingBox(ct)
     if (!vb || !cb) return
+    if (!warnedCollapsed) {
+      let zeroY = canY && vb.height === 0 && cb.height > 0
+      let zeroX = canX && vb.width === 0 && cb.width > 0
+      if (zeroY || zeroX) {
+        warnedCollapsed = true
+        let axisName = zeroY ? "height" : "width"
+        console.warn(
+          `Scroll container resolved to ${axisName} 0, so its content is invisible. ` +
+            `Give it an explicit ${axisName} or flex; maxHeight/maxWidth alone does not size it.\n${origin}`,
+        )
+      }
+    }
     maxX = Math.max(0, cb.width - vb.width)
     maxY = Math.max(0, cb.height - vb.height)
     let cur = offset()

package/src/types.d.ts

@@ -308,6 +308,11 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   h?: number
   fontFamily?: "sans" | "mono" | (string & {})
   fontSize?: number
+  /**
+   * Line height as a MULTIPLIER of fontSize, not pixels (the theme uses
+   * 1.3-1.6). A CSS-reflex pixel value like 22 makes each line box 22x the
+   * font size, rendering the text as blank space.
+   */
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900