solid-tag-runtime 0.0.15 → 0.0.18

package/ARCHITECTURE.md

@@ -1344,11 +1344,11 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 3. `data-solid-runtime` selects a matching HTML controller whose configured root contains the element. Without the attribute, controller selection follows the same rule as unscoped script discovery: a containing scoped controller may participate when `acceptUnscoped:true`, while an unscoped controller naturally accepts it. Equally specific matches are ambiguous and require explicit scope. A controller outside the element's root is never selected merely because it is the only candidate.
 4. The element remains in the DOM and is the light-DOM mount container. Wrapperless rendering belongs to bare `<script render>`.
 5. Renderer configuration (`module`, `component`, `data-solid-runtime`) is never forwarded as component props.
-6. Declarative props use `prop:*`; kebab names normalize to camelCase. Empty/presence values are boolean `true`, other values remain strings.
-7. `.props` carries arbitrary JavaScript references and overrides declarative props.
+6. Declarative prop layers are bulk `props`, individual `prop:*`, then programmatic `.props`. Kebab `prop:*` names normalize to camelCase. Empty/presence values are boolean `true`; plain values remain strings; one outer `{...}` pair opts an individual prop into safe typed-data parsing.
+7. Bulk `props` uses a safe JSON5-style object parser. Declarative parsing never evaluates JavaScript. `.props` carries arbitrary JavaScript references and overrides both declarative layers.
 8. Prop changes update a reactive prop facade and do not remount the component, preserving local state.
 9. Module/component/runtime identity changes increment a generation token, dispose the current owner, and remount. Stale async import successes and failures are ignored; they cannot mount or report an error against a newer identity.
-10. Initial light-DOM child nodes are captured once and exposed as reusable `props.children`; named slots and dynamic child recapture are not part of this phase.
+10. Initial light-DOM child nodes are captured once and exposed as reusable `props.children`. From 0.0.18 the element is hidden while pending by default so those children do not flash before activation; `show-until-ready` intentionally exposes a cloned fallback while pending. Named slots and dynamic child recapture remain out of scope.
 11. Multiple elements may share one evaluated module namespace while owning independent Solid component roots.
 12. Disconnect disposes the mounted root; reconnect mounts a fresh component instance from the retained declaration inputs.
 13. Custom-element registration is global/idempotent per `CustomElementRegistry`, but controller creation does **not** eagerly upgrade existing `solid-render` elements. Initial `register()` / `observe()` first install the complete declarative script batch and then ensure the custom element is registered. `registerSolidRenderElement()` remains available for explicit/custom-registry use.
@@ -1356,7 +1356,7 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 
 Rendering lifecycle joins the existing HTML event stream through `render-mounting`, `render-mounted`, `render-disposing`, and `render-disposed`; failures are also reported through `html-error` with `render`/`solid-render` operations. Lifecycle subscriptions remain observational and cannot alter rendering.
 
-The first `solid-render` phase intentionally excludes named slots, Shadow DOM, automatic numeric/JSON coercion, arbitrary unprefixed prop forwarding, loading/fallback templates, and expression evaluation inside attributes.
+The initial `solid-render` phase excluded named slots, Shadow DOM, typed declarative data, loading/fallback visibility policy, and expression evaluation. `0.0.18` adds safe typed data plus pending/fallback visibility while continuing to exclude named slots, Shadow DOM, arbitrary unprefixed prop forwarding, and JavaScript expression evaluation.
 
 ### 0.0.10 — unresolved scoped render diagnostics
 
@@ -1476,3 +1476,130 @@ Reason: HTML lifecycle subscribers, devtools, status panels, and normal applicat
 Invariant: unrelated DOM mutations must not enqueue runtime discovery or emit `observer-batch`. Observing `document` is therefore robust against diagnostic/application UI churn, while matching declarations and mounted-render cleanup remain live.
 
 Regression coverage: package tests verify unrelated child-list additions enqueue no observer batch, matching runtime scripts still register normally, an `observer-batch` subscriber may render unrelated DOM without recursively triggering additional scans, and relevant declaration removals still dispose mounted render ownership. The browser playground test suite carries the same feedback-loop regression against the native `MutationObserver`.
+
+
+### 0.0.16 — incremental mutation-driven observation
+
+Decision: keep the 0.0.15 declaration-driven relevance filter, but stop turning every relevant `MutationObserver` callback back into `enqueueObserverScan()`. Normal observer callbacks now derive a bounded work set directly from `MutationRecord[]`.
+
+Pipeline:
+
+```text
+MutationRecord[]
+    ↓
+collectObserverMutationBatch()
+    ├── exact added declaration elements
+    ├── exact added <solid-render> retry candidates
+    ├── tracked mounted records affected by removal
+    └── unsafe/unknown host mutation → conservative full scan
+    ↓
+enqueueObserverBatch()
+    ↓
+process exact candidates once
+```
+
+Rules:
+
+1. An added element is checked directly and only its added subtree is queried for matching declarations.
+2. Candidate identity is deduplicated across mutation records before registration.
+3. Elements already owned by the same controller are dropped before observer work is queued, so `append()`/`addModule()` do not rediscover their own DOM mutations.
+4. Relevant removals carry the exact mounted ownership records forward and dispose only records that are actually detached after the mutation batch settles.
+5. `register()`, initial `observe({ registerExisting:true })`, explicit `flush()`, and root-change registration retain full-root scan semantics.
+6. Unknown/custom DOM hosts that cannot be classified safely fall back to the previous full-root scan path.
+7. Define-before-entry/render ordering is preserved because all exact declaration candidates in one observer callback are still claimed and defined as one batch before entries/renders execute.
+
+Invariant: live observation is mutation-driven and incremental. Relevant mutation cost should scale with the changed subtree or tracked removal set, not with total root size. Full-root discovery is reserved for explicit scan operations and conservative fallback.
+
+Regression coverage adds direct-addition and nested-subtree cases that assert zero root selector calls, duplicate-record deduplication, and explicit `append()` under active observation producing no observer batch. `bench/observer.mjs` provides a synthetic scaling check comparing incremental addition with forced `flush()`.
+
+
+### 0.0.17 — explicit observation lifecycle strategies
+
+Decision: observation is a compatibility mechanism for DOM changes the runtime does not already know about, not the primary module lifecycle mechanism. Keep `observe()` continuous by default for compatibility, but add an opt-in bootstrap lifecycle for applications that only need automatic discovery during initial page/framework startup.
+
+Public modes:
+
+```text
+manual / no observer
+    html.register() + explicit APIs + optional html.flush()
+
+bootstrap / temporary observer
+    html.observe({ mode: "bootstrap", idleMs })
+
+continuous / long-lived observer
+    html.observe()
+    html.observe({ mode: "continuous" })
+```
+
+Bootstrap semantics:
+
+1. connect the normal incremental observer;
+2. optionally register existing declarations using the existing `registerExisting` behavior;
+3. remain connected through DOM readiness;
+4. only relevant observer mutations increment bootstrap activity; unrelated UI mutations do not extend observation;
+5. after `idleMs` with no new relevant activity, wait for the controller queue to drain;
+6. if activity occurred during the wait, repeat the quiet-period check;
+7. otherwise disconnect with lifecycle reason `bootstrap-idle`;
+8. a manual `disconnect()` cancels bootstrap settling;
+9. root rebinding preserves bootstrap state and resets relevant activity rather than creating a second observer;
+10. after bootstrap completes, a later `observe()` may start a fresh continuous session.
+
+Default `idleMs` is 50 ms. Invalid modes and negative/non-finite idle values are rejected.
+
+Invariant: use continuous observation only when runtime declarations may enter the DOM through code outside the runtime's explicit APIs. Controlled dynamic module loading should remain observer-free after initial registration.
+
+Regression coverage verifies continuous compatibility, bootstrap initial registration, late startup additions, unrelated mutation filtering, automatic disconnect, option validation, and re-observation after bootstrap.
+
+### 0.0.18 — `<solid-render>` pending visibility and safe typed declarative props
+
+Decision: make reusable `<solid-render>` instances visually stable during asynchronous activation and make declarative prop data expressive without turning HTML attributes into executable JavaScript.
+
+Visibility lifecycle:
+
+```text
+connected / identity changed
+    ↓
+pending
+    ↓
+module import + component mount
+    ↓
+ready
+
+error path: pending → error
+```
+
+Rules:
+
+1. `<solid-render>` is hidden while `data-solid-render-state="pending"` by default.
+2. The HTML runtime installs one document-level visibility rule automatically; application CSS is not required. The rule also covers `solid-render:not(:defined)` once the HTML runtime has initialized, preventing the custom-element upgrade window from exposing fallback content.
+3. `show-until-ready` opts out of hiding and displays a clone of captured initial light-DOM children while pending.
+4. Error state is visible and restores captured initial content as fallback when no component mount exists.
+5. `renderState` exposes `pending | ready | error`; `hideUntilReady` is the programmatic visibility-policy property.
+6. Identity changes immediately re-enter `pending`; existing generation guards remain authoritative, so stale imports cannot reveal or mark ready a newer generation.
+7. Visibility management does not change light-DOM ownership, `props.children` capture, runtime routing, or the independent Solid owner for each instance.
+
+Declarative prop layers:
+
+```text
+props="{ ... }"
+    ↓ overridden by
+prop:*
+    ↓ overridden by
+element.props
+```
+
+Parsing rules:
+
+1. Bulk `props` must parse to a top-level object.
+2. The built-in parser accepts a safe JSON5-style data subset: unquoted keys, single/double quoted strings, arrays/objects, booleans, null, finite numbers, comments, and trailing commas.
+3. Plain individual `prop:*` attribute values remain HTML strings; empty/presence values remain boolean `true`.
+4. One outer `{...}` pair marks an individual prop as typed data. Examples: `{3}`, `{true}`, `{[1,2,3]}`, and `{{a:123}}`.
+5. Declarative parsing never uses `eval`, `new Function`, variable lookup, calls, member access, functions, constructors, or other executable JavaScript semantics. Unsupported expression syntax fails as a render/data error.
+6. Prop-only changes update the existing reactive prop facade and do not remount. Invalid later declarative updates preserve the existing component mount rather than partially applying data.
+7. An optional `parseProps(source, context)` controller hook may replace only declarative data decoding. `context.kind` distinguishes bulk `props` from one typed `prop:*`; module resolution, controller routing, and render ownership are unaffected.
+8. Programmatic `.props` remains the path for functions, signals/accessors, services, DOM nodes, class instances, Maps/Sets, and other identity-sensitive JavaScript values.
+
+Implementation boundary: the safe parser lives under `src/html/` and has no external runtime dependency, preserving direct-browser/zero-build package usage. The core runtime remains completely unaware of these HTML/data semantics.
+
+Regression coverage verifies pending/ready/error state, default hiding, visible fallback opt-out, fallback restoration on error, typed individual values, structured bulk values, precedence, reactive updates without remount, custom parser behavior, non-execution of JavaScript-like input, and automatic visibility-style installation.
+

package/README.md

@@ -16,6 +16,48 @@ host Solid runtime
 
 The core package is module-first and DOM-independent. Browser discovery, ownership, declarative rendering, and `<solid-render>` live in `solid-tag-runtime/html`. Optional Solid setup/provider helpers live in `solid-tag-runtime/solid`.
 
+## 0.0.18 `<solid-render>` lifecycle and typed declarative props
+
+`0.0.18` hides `<solid-render>` light-DOM content until the selected component is ready by default, exposes `pending` / `ready` / `error` through `data-solid-render-state`, and provides `show-until-ready` for intentional fallback content. The HTML runtime installs the pending-visibility rule automatically; applications do not need their own CSS.
+
+Structured component data can now be written declaratively:
+
+```html
+<solid-render
+  module="/Counter.jsx"
+  props="{ initial: 100, options: { theme: 'dark' } }"
+  prop:step="{5}"
+  prop:items="{[1, 2, 3]}"
+></solid-render>
+```
+
+Plain `prop:*` values remain HTML strings; one outer `{...}` pair opts an individual prop into safe typed-data parsing. Bulk `props` uses a safe JSON5-style object syntax. Neither form evaluates JavaScript. Precedence is `props < prop:* < element.props`, and prop-only changes remain reactive without remounting.
+
+## 0.0.17 observation strategies
+
+`0.0.17` adds explicit observation lifecycle strategies while keeping existing behavior backward compatible. `observe()` is still continuous by default. Applications that only need DOM discovery during startup can use `observe({ mode: "bootstrap" })`; it observes through DOM readiness and disconnects after a configurable quiet period of relevant runtime mutations.
+
+```ts
+// Lowest ongoing overhead: initial scan, then explicit runtime APIs.
+await html.register();
+
+// Mostly declarative startup: temporary observer.
+await html.observe({ mode: "bootstrap", idleMs: 50 });
+
+// Unknown external DOM mutations throughout application lifetime.
+await html.observe({ mode: "continuous" });
+```
+
+Only relevant declaration/removal activity extends bootstrap lifetime. Ordinary application UI mutations do not.
+
+## 0.0.16 incremental observer processing
+
+`0.0.16` keeps the `0.0.15` declaration-driven filter but removes the normal relevant-mutation root rescan. `MutationRecord[]` are converted into exact declaration, `<solid-render>`, and mounted-removal candidates; added subtrees are queried locally and duplicate candidates are coalesced before one observer batch.
+
+Explicit APIs such as `append()` and `addModule()` claim ownership before DOM insertion, so an active observer now ignores that already-known work entirely. Full-root discovery remains available for initial registration, `flush()`, root-change registration, and conservative fallback when a host DOM cannot be classified safely.
+
+The key performance invariant is that relevant observer work scales with the changed subtree rather than total root size.
+
 ## 0.0.15 observer hardening
 
 `0.0.15` filters `MutationObserver` records before scheduling HTML discovery. Ordinary UI DOM changes no longer enqueue a full runtime scan or emit an `observer-batch`; matching runtime declarations, `<solid-render>` retry boundaries, and removals that can detach mounted declarative renders still trigger observer work. Explicit `html.flush()` remains a deterministic forced scan.
@@ -167,6 +209,8 @@ See [Wrapperless delegation](./docs/wrapperless-delegation.md).
 
 **In HTML, always use the explicit closing tag.** Do not write `<solid-render ... />`; custom elements are not HTML void elements and the self-closing slash is ignored by the HTML parser.
 
+Initial light-DOM content is hidden until the component is ready by default. Use `show-until-ready` when those children are intentional loading/fallback content. See the [`<solid-render>` guide](./docs/solid-render.md) for structured `props`, typed `prop:*` literals, precedence, and render-state details.
+
 ## Persistent compile cache
 
 The opt-in compile cache persists **pre-link compiler artifacts**. Runtime-specific linked URLs and evaluated module namespaces are never persisted.
@@ -217,9 +261,9 @@ When loading from an import map, map every used package subpath to the same rele
 ```json
 {
   "imports": {
-    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.15",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.15/html",
-    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.15/solid"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.18",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.18/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.18/solid"
   }
 }
 ```

package/bench/observer.mjs

@@ -0,0 +1,103 @@
+import { performance } from "node:perf_hooks";
+import { createRuntime } from "../src/runtime.js";
+import { createHTMLRuntime } from "../src/html.js";
+
+class BenchMutationObserver {
+  static instances = [];
+  constructor(callback) { this.callback = callback; BenchMutationObserver.instances.push(this); }
+  observe(target) { this.target = target; this.connected = true; }
+  disconnect() { this.connected = false; }
+  trigger(records) { if (this.connected) this.callback(records, this); }
+}
+
+function script(id) {
+  const attrs = { type: "solid-js", module: id };
+  return {
+    nodeType: 1,
+    textContent: "export const value = 1;",
+    parentNode: null,
+    getAttribute(name) { return attrs[name] ?? null; },
+    hasAttribute(name) { return Object.prototype.hasOwnProperty.call(attrs, name); },
+    setAttribute(name, value) { attrs[name] = String(value); },
+    matches(selector) { return String(selector).includes('script[type="solid-js"]'); },
+    querySelectorAll() { return []; },
+    contains(target) { return target === this; },
+  };
+}
+
+function makeRoot(size) {
+  const filler = Array.from({ length: size }, () => ({ nodeType: 1 }));
+  const scripts = [];
+  let visited = 0;
+  return {
+    nodes: filler,
+    scripts,
+    querySelectorAll(selector) {
+      visited += this.nodes.length + this.scripts.length;
+      if (selector === "solid-render") return [];
+      return [...this.scripts];
+    },
+    contains(node) { return this.nodes.includes(node) || this.scripts.includes(node); },
+    resetVisited() { visited = 0; },
+    getVisited() { return visited; },
+  };
+}
+
+function makeRuntime() {
+  return createRuntime({
+    compiler: {
+      fingerprint: "observer-bench-v1",
+      analyze() { return { imports: [] }; },
+      transform(source) { return { code: source, diagnostics: [] }; },
+    },
+  });
+}
+
+async function waitTask() { await new Promise(resolve => setTimeout(resolve, 0)); }
+
+async function measureIncremental(size) {
+  BenchMutationObserver.instances.length = 0;
+  const runtime = makeRuntime();
+  const root = makeRoot(size);
+  const html = createHTMLRuntime(runtime, { root, MutationObserver: BenchMutationObserver });
+  await html.observe({ registerExisting: false });
+  root.resetVisited();
+  const element = script(`/incremental-${size}.js`);
+  element.parentNode = root;
+  root.scripts.push(element);
+  const t0 = performance.now();
+  BenchMutationObserver.instances[0].trigger([{ type: "childList", addedNodes: [element], removedNodes: [] }]);
+  await waitTask();
+  const ms = performance.now() - t0;
+  const visited = root.getVisited();
+  html.disconnect();
+  runtime.dispose();
+  return { ms, visited };
+}
+
+async function measureForcedScan(size) {
+  BenchMutationObserver.instances.length = 0;
+  const runtime = makeRuntime();
+  const root = makeRoot(size);
+  const html = createHTMLRuntime(runtime, { root, MutationObserver: BenchMutationObserver });
+  await html.observe({ registerExisting: false });
+  const element = script(`/scan-${size}.js`);
+  element.parentNode = root;
+  root.scripts.push(element);
+  root.resetVisited();
+  const t0 = performance.now();
+  await html.flush();
+  const ms = performance.now() - t0;
+  const visited = root.getVisited();
+  html.disconnect();
+  runtime.dispose();
+  return { ms, visited };
+}
+
+console.log("observer benchmark (synthetic root; lower visited count is the main invariant)");
+console.log("nodes\tincremental ms\tincremental visited\tflush ms\tflush visited");
+for (const size of [1_000, 10_000, 50_000]) {
+  const incremental = await measureIncremental(size);
+  const scan = await measureForcedScan(size);
+  console.log(`${size}\t${incremental.ms.toFixed(3)}\t${incremental.visited}\t${scan.ms.toFixed(3)}\t${scan.visited}`);
+}

package/docs/api/html.md

@@ -25,17 +25,24 @@ Common options:
 - `executeEntries`
 - `executeRenders`
 - `onError`
+- `parseProps(source, context)` for optional custom `<solid-render>` declarative-data parsing
 
 ## Discovery and observation
 
 ```ts
 await html.register(options?);
-await html.observe(options?);
+await html.observe({
+  mode: "continuous" | "bootstrap",
+  idleMs: 50,
+  ...options,
+});
 await html.flush(options?);
 html.disconnect();
 ```
 
-`observe()` filters child-list mutation records and schedules discovery only for mutations that can affect runtime declarations, `<solid-render>` retry work, or mounted declarative-render cleanup. `flush()` bypasses that filter and forces a scan.
+`observe()` is continuous by default. `mode: "bootstrap"` temporarily observes startup DOM activity and resolves after DOM readiness plus `idleMs` with no relevant runtime mutations, at which point the observer is disconnected. `mode: "continuous"` retains long-lived observation.
+
+`observe()` processes relevant child-list mutation records incrementally. Added declarations are discovered from the added node/subtree itself, removals consult tracked mounted ownership, and explicit API-owned elements are skipped. A full-root scan is reserved for initial registration, `flush()`, root-change registration, or conservative fallback. `flush()` always forces a full scan.
 
 ## Explicit ownership
 
@@ -89,3 +96,27 @@ For rendering semantics see [Declarative rendering](../rendering.md) and [`<soli
 For bare `<script render>` ranges, automatic Solid delegated-event setup is available when the underlying runtime was created with `createSolidRuntime()` from `solid-tag-runtime/solid`.
 
 The HTML adapter asks the runtime's private Solid integration to establish document-level delegation lazily, then keeps the declaration in its existing independent `createRoot() + insert()` lifecycle. Selector renders and `<solid-render>` retain their existing container semantics.
+
+## `<solid-render>` state and props
+
+`0.0.18` exposes these element properties/state surfaces:
+
+```ts
+renderer.renderState;     // "pending" | "ready" | "error"
+renderer.hideUntilReady;  // true by default
+renderer.props = { ... }; // strongest prop layer
+```
+
+The DOM mirrors render state through `data-solid-render-state`. Pending content is hidden automatically unless `show-until-ready` is present.
+
+Declarative data layers are:
+
+```text
+props="{ initial: 100 }"
+< prop:step="{5}"
+< renderer.props
+```
+
+Plain `prop:*` values are strings. An outer `{...}` marker parses one individual value with the same safe JSON5-style data parser used by bulk `props`. No declarative form evaluates JavaScript.
+
+A custom parser receives `(source, context)` where `context.kind` is `"props"` or `"prop"`; bulk `props` must return a top-level object.

package/docs/getting-started.md

@@ -97,6 +97,21 @@ Declarative source:
 
 See [HTML runtime](./html-runtime.md), [declarative rendering](./rendering.md), and [`<solid-render>`](./solid-render.md).
 
+
+## Reusable component instance
+
+After the HTML controller registers declarations, an existing runtime module can be instantiated directly from HTML:
+
+```html
+<solid-render
+  module="/Counter.jsx"
+  props="{ initial: 100 }"
+  prop:step="{5}"
+></solid-render>
+```
+
+`<solid-render>` is hidden while pending by default, so initial child content does not flash before the Solid mount is ready. Add `show-until-ready` when the initial children are intentional loading content. Plain `prop:*` values are strings; `{...}` opts an individual prop into safe typed-data parsing.
+
 ## Browser import maps
 
 Map every used package subpath explicitly:
@@ -104,9 +119,9 @@ Map every used package subpath explicitly:
 ```json
 {
   "imports": {
-    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.15",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.15/html",
-    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.15/solid"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.18",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.18/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.18/solid"
   }
 }
 ```

package/docs/html-runtime.md

@@ -20,18 +20,48 @@ const html = createHTMLRuntime(runtime, {
 await html.register();
 ```
 
-## Observe later declarations
+## Choose an observation strategy
+
+For controlled applications, prefer one initial scan plus explicit runtime APIs:
 
 ```ts
-await html.observe({ registerExisting: false });
+await html.register();
+
+await html.addModule(...);
+await html.append(script);
+```
+
+If raw DOM insertion is known and occasional, keep observation disabled and synchronize explicitly:
 
-// after external DOM mutations
+```ts
+root.insertAdjacentHTML("beforeend", markup);
 await html.flush();
 ```
 
-The live observer is declaration-driven rather than mutation-driven. It inspects each `MutationRecord` before scheduling discovery and ignores ordinary UI child-list changes that cannot add a matching runtime declaration or require mounted-render cleanup. This means a document-scoped controller can coexist with application/devtools DOM updates without repeatedly rescanning the document.
+For mostly declarative startup, use a temporary bootstrap observer:
+
+```ts
+await html.observe({
+  mode: "bootstrap",
+  idleMs: 50,
+});
+```
+
+Bootstrap mode observes through DOM readiness, waits until there have been no **relevant runtime mutations** for `idleMs`, drains queued registration work, and disconnects. Ordinary UI mutations do not reset the quiet period.
+
+For pages where declarations can arrive through uncontrolled DOM code throughout the application lifetime, use continuous observation:
+
+```ts
+await html.observe({ mode: "continuous" });
+```
+
+`observe()` with no `mode` remains equivalent to continuous mode for backward compatibility.
 
-`flush()` is intentionally different: it remains an explicit forced scan and can be used as a deterministic synchronization point even when no relevant observer mutation was seen.
+The live observer is declaration-driven and incremental. It inspects each `MutationRecord`, ignores ordinary UI child-list changes, and derives exact runtime declaration/removal candidates from relevant added or removed subtrees. Normal relevant mutations do not rescan the configured root.
+
+Added subtrees are queried only within the subtree that changed, duplicate candidates are coalesced, and elements already claimed through explicit APIs are skipped before observer work is queued. This means observer cost scales primarily with changed runtime-relevant DOM rather than total page size.
+
+`flush()` is intentionally different: it remains an explicit forced full-root scan and can be used as a deterministic synchronization point after known raw DOM insertion.
 
 ## Script declarations
 
@@ -122,3 +152,9 @@ A low-level `createRuntime()` controller behaves exactly as before and does not
 When the runtime comes from `createSolidRuntime()` in `solid-tag-runtime/solid`, a bare `<script render>` can lazily request the document-level delegated-event setup required by Solid 2. Each marker-range declaration still owns an independent reactive root and disposer; the delegation host is infrastructure only and is not a shared reactive owner.
 
 See [Solid runtime setup](./solid-runtime-setup.md) and [Wrapperless delegation](./wrapperless-delegation.md).
+
+## `<solid-render>` declarative data and pending visibility
+
+The HTML controller also owns the declarative-data parser configuration used by `<solid-render>`. The default parser treats bulk `props` as a safe JSON5-style object and treats `prop:name="{...}"` as an explicitly typed individual value. Plain individual attributes remain strings. Applications may override this data parser with `parseProps`, but parsing never changes module/runtime ownership.
+
+When a controller is created in a browser document it installs one internal visibility rule for `<solid-render>`. Pending elements are hidden by default, including the pre-upgrade `:not(:defined)` window after the runtime has initialized. `show-until-ready` opts into visible fallback content. The custom element itself drives `data-solid-render-state="pending|ready|error"`.

package/docs/lifecycle-events.md

@@ -74,6 +74,11 @@ html.subscribe("element-registered", event => {
 
 HTML events cover ownership, observation, roots, entry execution, render mounting/disposal, warnings, and errors.
 
-`observer-batch` is emitted only when observer work is actually scheduled. Unrelated child-list mutations are filtered before discovery, so a lifecycle subscriber may render diagnostics/status UI inside an observed document without causing a self-sustaining observer/event loop. Explicit `html.flush()` still performs and reports a forced scan.
+`observer-batch` is emitted only when semantic observer work is scheduled. Unrelated child-list mutations are filtered before discovery, and relevant additions are processed from their exact changed subtree instead of rescanning the whole root. A lifecycle subscriber may therefore render diagnostics/status UI inside an observed document without causing a feedback loop. Explicit `html.flush()` still performs and reports a forced full-root scan.
 
 Listener exceptions are isolated from runtime/HTML operations and are reported to the console rather than aborting the underlying action.
+
+
+## Bootstrap observation lifecycle
+
+`observe({ mode: "bootstrap" })` emits the normal `observer-connected` event and later an `observer-disconnected` event with reason `bootstrap-idle` when its relevant-mutation quiet period completes. Unrelated UI DOM mutations neither emit `observer-batch` nor extend bootstrap lifetime.

package/docs/rendering.md

@@ -69,3 +69,7 @@ Combining `entry` and `render` on one declaration is rejected.
 ## Runtime scope diagnostics
 
 A scoped render declaration is immediate work. If `data-solid-runtime="main"` cannot be handled by any registered controller covering that DOM root, the HTML adapter emits `html-warning` with code `unresolved-runtime-scope` and logs one warning.
+
+## Reusable `<solid-render>` lifecycle
+
+Reusable `<solid-render>` instances use container rendering rather than the marker-range wrapperless path. From `0.0.18`, they are hidden while pending by default and expose `data-solid-render-state="pending|ready|error"`. `show-until-ready` keeps captured initial children visible as fallback content. Structured `props` and typed `prop:*="{...}"` values are data-only and do not evaluate JavaScript. See [`<solid-render>`](./solid-render.md).