solid-tag-runtime 0.0.15 → 0.0.18

package/docs/solid-render.md

@@ -1,20 +1,21 @@
 # `<solid-render>`
 
-`<solid-render>` references an already-defined runtime module and mounts a component instance into its own light DOM.
+`<solid-render>` references an already-defined runtime module and mounts one component instance into its own light DOM.
 
 ```html
 <script type="solid-jsx" module="/Counter.jsx">
-  export default function Counter() {
-    return <button>Counter</button>;
+  export default function Counter(props) {
+    return <button>{props.initial}</button>;
   }
 </script>
 
-<solid-render module="/Counter.jsx"></solid-render>
+<solid-render
+  module="/Counter.jsx"
+  props="{ initial: 100 }"
+></solid-render>
 ```
 
-## Important HTML syntax rule
-
-**Always use an explicit closing tag in HTML.**
+## Always use an explicit closing tag
 
 Correct:
 
@@ -28,7 +29,68 @@ Do not write:
 <solid-render module="/Counter.jsx" />
 ```
 
-Custom elements are not HTML void elements. The HTML parser ignores the XML-style self-closing slash, so following siblings may become children of `<solid-render>`. Because initial child content is captured as `props.children`, this can make later page content appear to disappear.
+Custom elements are not HTML void elements. The HTML parser ignores the XML-style self-closing slash, so following siblings may accidentally become children of `<solid-render>`.
+
+## Hidden until ready by default
+
+`0.0.18` prevents initial light-DOM content from flashing before the requested component is ready.
+
+```html
+<solid-render module="/Counter.jsx">
+  this text is captured, but does not flash before the component mounts
+</solid-render>
+```
+
+The runtime installs the required visibility rule automatically; application CSS is not required.
+
+The element exposes its current state:
+
+```text
+data-solid-render-state="pending"
+data-solid-render-state="ready"
+data-solid-render-state="error"
+```
+
+The normal lifecycle is:
+
+```text
+pending
+  ↓
+module import / component mount
+  ↓
+ready
+```
+
+On failure:
+
+```text
+pending → error
+```
+
+Error state is visible, and captured initial content is restored as fallback content.
+
+The visibility rule is installed as soon as the HTML runtime is created. For pages that need to avoid any paint before the runtime bootstrap itself executes, load/bootstrap the HTML runtime early in the document.
+
+### Show fallback content while pending
+
+If initial children are intentional loading content, opt out of hiding:
+
+```html
+<solid-render
+  module="/Account.jsx"
+  show-until-ready
+>
+  Loading account…
+</solid-render>
+```
+
+Programmatically:
+
+```ts
+renderer.hideUntilReady = false;
+```
+
+The state attribute still transitions through `pending`, `ready`, and `error`; only the visibility policy changes.
 
 ## Named component
 
@@ -39,6 +101,8 @@ Custom elements are not HTML void elements. The HTML parser ignores the XML-styl
 ></solid-render>
 ```
 
+Without `component`, `module.default` is used.
+
 ## Runtime selection
 
 ```html
@@ -50,48 +114,180 @@ Custom elements are not HTML void elements. The HTML parser ignores the XML-styl
 
 The selected controller must match scope rules and contain the element within its configured root.
 
-## Declarative props
+## Structured declarative props
+
+Use `props` for a structured object:
 
 ```html
 <solid-render
   module="/UserCard.jsx"
-  prop:name="Alice"
-  prop:user-id="42"
-  prop:compact
+  props="{
+    user: {
+      name: 'Alice',
+      age: 32,
+    },
+    compact: true,
+    tags: ['admin', 'active'],
+  }"
 ></solid-render>
 ```
 
-Rules:
+The built-in parser accepts safe JSON5-style data conveniences:
 
-- `prop:user-id` becomes `userId`
-- a present empty prop becomes `true`
-- other attribute values remain strings
-- renderer configuration (`module`, `component`, `data-solid-runtime`) is not forwarded
-- `prop:module` is a normal component prop and does not collide with renderer `module`
+- unquoted object keys
+- single- or double-quoted strings
+- arrays and nested objects
+- numbers, booleans, and `null`
+- trailing commas
+- line/block comments
 
-## Programmatic props
+Declarative props are **data only**. The parser never uses `eval()` or `new Function()` and does not resolve JavaScript variables, member access, calls, functions, or constructors.
 
-```ts
-const element = document.querySelector("solid-render");
+This is rejected rather than executed:
+
+```html
+<solid-render props="{ value: getValue() }"></solid-render>
+```
+
+The top-level `props` value must be an object.
+
+## Individual `prop:*` values
+
+Plain HTML attribute values remain strings:
+
+```html
+<solid-render
+  prop:first="123"
+  prop:second=123
+></solid-render>
+```
+
+Both values are the string `"123"`.
+
+A present empty prop remains boolean `true`:
+
+```html
+<solid-render prop:compact></solid-render>
+```
+
+To opt one prop into typed data parsing, wrap it in one outer `{...}` pair:
+
+```html
+<solid-render
+  prop:count="{3}"
+  prop:enabled="{true}"
+  prop:missing="{null}"
+  prop:label="{'3'}"
+  prop:items="{[1, 2, 3]}"
+  prop:options="{{ theme: 'dark', step: 5 }}"
+></solid-render>
+```
+
+Effective values:
+
+```js
+{
+  count: 3,
+  enabled: true,
+  missing: null,
+  label: "3",
+  items: [1, 2, 3],
+  options: { theme: "dark", step: 5 },
+}
+```
+
+The outer braces are a typed-data marker, not JavaScript expression syntax. Object values naturally use double braces because the inner braces belong to the object literal.
+
+`prop:user-id` still normalizes to `userId`.
+
+## Prop precedence
+
+The effective prop layers are:
+
+```text
+props="..."
+    ↓ overridden by
+prop:*
+    ↓ overridden by
+element.props
+```
+
+Example:
+
+```html
+<solid-render
+  module="/Counter.jsx"
+  props="{ initial: 100, step: 5 }"
+  prop:step="{10}"
+></solid-render>
+```
 
-element.props = {
-  user,
+Then:
+
+```ts
+renderer.props = {
+  step: 20,
   onSave,
-  service,
 };
 ```
 
-Programmatic values may contain arbitrary JavaScript references and override declarative `prop:*` values.
+The effective `step` is `20`. Programmatic `.props` can contain arbitrary JavaScript values such as functions, signals, services, class instances, Maps/Sets, or identity-sensitive objects.
+
+## Reactive prop updates
+
+Changing any of these updates the existing mounted component without remounting:
+
+```text
+props attribute
+prop:* attributes
+element.props
+```
+
+For example:
+
+```ts
+renderer.setAttribute(
+  "props",
+  "{ initial: 200, options: { theme: 'light' } }",
+);
 
-## Reactive updates
+renderer.setAttribute("prop:step", "{20}");
+```
 
-Changing `prop:*` or `.props` updates the existing component instance without remounting.
+Local component state is preserved.
 
 Changing `module`, `component`, or `data-solid-runtime` changes render identity and therefore disposes/remounts.
 
+Invalid declarative data produces a `solid-render` error; it is never partially executed as JavaScript.
+
+## Custom declarative parser
+
+Applications with a domain-specific data syntax may override declarative parsing at the HTML-controller boundary:
+
+```ts
+const html = createHTMLRuntime(runtime, {
+  parseProps(source, context) {
+    if (context.kind === "props") {
+      return myObjectParser(source);
+    }
+
+    return myValueParser(source);
+  },
+});
+```
+
+Context distinguishes:
+
+```text
+kind: "props"   bulk props attribute
+kind: "prop"    typed prop:* value
+```
+
+A custom bulk parser must still return an object. Parser customization changes data decoding only; it does not change runtime selection, module resolution, or component ownership.
+
 ## Children
 
-Initial child DOM becomes `props.children`:
+Initial child DOM is captured once and becomes `props.children`:
 
 ```html
 <solid-render module="/Card.jsx">
@@ -99,7 +295,9 @@ Initial child DOM becomes `props.children`:
 </solid-render>
 ```
 
-Initial children are captured once. Named slots and dynamic child recapture are not part of the current API.
+By default those children are hidden while the element is pending, then instantiated through `props.children` when the component mounts. With `show-until-ready`, a clone is also displayed as fallback content while pending.
+
+Named slots and dynamic child recapture are not part of the current API.
 
 ## Multiple instances
 

package/docs/solid-runtime-setup.md

@@ -126,7 +126,7 @@ When provider fallback is needed and there is no versioned Solid anchor, this re
 import { TESTED_SOLID_VERSION } from "solid-tag-runtime/solid";
 ```
 
-For `0.0.14` and `0.0.15`, the tested fallback line is Solid `2.0.0-rc.13`.
+For `0.0.14` through `0.0.18`, the tested fallback line is Solid `2.0.0-rc.13`.
 
 If an existing Solid mapping is explicitly versioned, that version becomes the family anchor for generated siblings. An explicitly unversioned existing mapping remains unversioned; the loader does not pretend it is pinned.
 

package/examples/observer-strategies.js

@@ -0,0 +1,19 @@
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+export async function manual(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.register();
+  return html;
+}
+
+export async function bootstrap(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.observe({ mode: "bootstrap", idleMs: 50 });
+  return html; // disconnected after startup settles
+}
+
+export async function continuous(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.observe({ mode: "continuous" });
+  return html;
+}

package/examples/render.html

@@ -37,14 +37,19 @@
     <solid-render
       data-solid-runtime="main"
       module="/Counter.jsx"
-      prop:label="Counter A"
+      props="{ label: 'Counter A' }"
+      prop:initial="{100}"
     ></solid-render>
 
     <solid-render
       data-solid-runtime="main"
       module="/Counter.jsx"
       prop:label="Counter B"
-    ></solid-render>
+      prop:initial="{200}"
+      show-until-ready
+    >
+      Loading Counter B…
+    </solid-render>
 
     <!--
       This bootstrap is ordinary JavaScript. The surrounding application/import

package/html.d.ts

@@ -18,8 +18,13 @@ export interface HTMLAttributeElementLike {
 
 export interface HTMLModuleScriptElement extends HTMLAttributeElementLike {}
 
+export type SolidRenderState = "pending" | "ready" | "error";
+
 export interface SolidRenderElement extends HTMLAttributeElementLike, HTMLAppendTarget {
   props: Record<string, unknown>;
+  readonly renderState: SolidRenderState;
+  /** Default true. Set false to expose captured fallback children while pending. */
+  hideUntilReady: boolean;
   childNodes?: ArrayLike<any> | Iterable<any>;
   attributes?: ArrayLike<{ name: string; value: string }> | Iterable<{ name: string; value: string }>;
   replaceChildren?(...nodes: any[]): void;
@@ -32,6 +37,7 @@ export interface HTMLAppendTarget {
 }
 
 export interface HTMLDocumentLike extends HTMLModuleRoot, HTMLAppendTarget {
+  head?: HTMLAppendTarget;
   body?: HTMLAppendTarget;
   documentElement?: HTMLAppendTarget;
   createElement?(tagName: string): any;
@@ -159,6 +165,8 @@ export interface RemoveHTMLElementResult {
 
 export interface RegisterHTMLOptions extends DefineScriptOptions {
   selector?: string;
+  /** Override safe declarative data parsing for `<solid-render props>` and typed `prop:*="{...}"`. */
+  parseProps?: HTMLDeclarativePropsParser;
   executeEntries?: boolean;
   /** Execute declarative render actions. Default: true. */
   executeRenders?: boolean;
@@ -223,7 +231,13 @@ export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];
 export type HTMLRuntimeEventOfType<T extends HTMLRuntimeEventType> =
   Extract<HTMLRuntimeEvent, { type: T }>;
 
+export type HTMLObservationMode = "continuous" | "bootstrap";
+
 export interface ObserveHTMLOptions extends RegisterHTMLOptions {
+  /** Observation lifecycle. Default: "continuous". */
+  mode?: HTMLObservationMode;
+  /** Bootstrap-mode quiet period after DOM readiness and the last relevant mutation. Default: 50 ms. */
+  idleMs?: number;
   /** Register scripts already present when observation starts. Default: true. */
   registerExisting?: boolean;
   /** Observe descendant additions as well as direct children. Default: true. */
@@ -251,6 +265,19 @@ export interface AddHTMLModuleOptions extends DefineScriptOptions {
   createElement?: (tagName: string) => HTMLModuleScriptElement;
 }
 
+export interface HTMLDeclarativePropsParseContext {
+  element: SolidRenderElement;
+  /** `props` parses a top-level object; `prop` parses one typed prop value. */
+  kind: "props" | "prop";
+  attribute: string;
+  key?: string;
+}
+
+export type HTMLDeclarativePropsParser = (
+  source: string,
+  context: HTMLDeclarativePropsParseContext,
+) => unknown;
+
 export interface HTMLRuntimeOptions extends ObserveHTMLOptions {
   appendTo?: HTMLAppendTarget;
   createElement?: (tagName: string) => HTMLModuleScriptElement;
@@ -317,6 +344,8 @@ export interface CustomElementRegistryLike {
 export interface RegisterSolidRenderElementOptions {
   customElements?: CustomElementRegistryLike;
   HTMLElement?: new (...args: any[]) => any;
+  /** Document that receives the built-in pending-visibility rule. Defaults to global document. */
+  document?: HTMLDocumentLike;
 }
 
 export type HTMLObserverController = HTMLRuntimeController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.15",
+  "version": "0.0.18",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -41,7 +41,8 @@
     "README.md",
     "ARCHITECTURE.md",
     "docs",
-    "examples"
+    "examples",
+    "bench"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -49,7 +50,8 @@
   },
   "scripts": {
     "test": "node ./test/run.mjs",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "bench:observer": "node ./bench/observer.mjs"
   },
   "keywords": [
     "solid",