jsgui3 SSR → Activation Data Bridge

jsgui3 SSR → Activation Data Bridge

Scope

• Explain the real runtime path from server-rendered HTML → client reconstruction (pre_activate) → event binding (activate).
• Use the built-in DOM-attribute “data bridge”:
  • data-jsgui-fields → persisted fields hydration (_persisted_fields)
  • data-jsgui-ctrl-fields → named child control wiring (this.status, this.btn, …)
• Identify high-leverage patch points (plugins / monkeypatch wrappers) for:
  • noisy console warnings
  • missing context.map_Controls registrations
  • text-node alignment issues (&&& no corresponding control)

Non-goals:

• Rewriting the bundler/​publisher.
• Large refactors of upstream jsgui3-* packages without a minimal repro + regression guard.

Inputs

• Which surface is failing?
  • “SSR renders but clicks don’t work”
  • “Persisted fields didn’t hydrate”
  • “ctrl_fields not bound”
  • “Missing context.map_Controls …” warnings
• The minimal repro (prefer an existing lab experiment).

Procedure

1. Start from a lab repro (preferred)

• Use experiment 020 as the known-good baseline:
  • node src/​ui/​lab/​experiments/​020-jsgui3-server-activation/​check.js

1. Confirm SSR emits the bridge attributes

• In SSR HTML, find:
  • data-jsgui-id (identity)
  • data-jsgui-type (constructor key; may be absent for exempt tags)
  • data-jsgui-fields (persisted fields payload)
  • data-jsgui-ctrl-fields (named child ids payload)

1. Understand activation sequence (client)

• Browser boot (from jsgui3-client) does:
  • create Client_Page_Context
  • update standard controls
  • pre_activate(context) (reconstruct controls from DOM)
  • activate(context) (call ctrl.activate() depth-first)

1. Persisted fields hydration (data-jsgui-fields)

• During control construction, jsgui3-html reads data-jsgui-fields from the DOM element and stores it as _persisted_fields.
• Controls typically consume _persisted_fields in activate() to restore state.

1. ctrl_fields hydration (data-jsgui-ctrl-fields)

• During pre_activate_content_controls, jsgui3-html parses data-jsgui-ctrl-fields (key→id) and binds:
  • this[key] = context.map_controls[id]
• This enables patterns like this.btn.on('click', ...) or this.status.dom.el.textContent = ....

1. Interpret the common warnings

• Missing context.map_Controls for type <X>

  • Means SSR (or DOM) said the element is type <X>, but the client context doesn’t have a constructor registered at context.map_Controls[X].
  • Client falls back to generic Control, so activation may still work (but you lose the intended class).

• Missing context.map_Controls for type undefined

  • Often corresponds to tags where data-jsgui-type is intentionally not emitted (notably html/​head/​body in upstream control-core).
  • This is usually log noise unless it breaks reconstruction.

• &&& no corresponding control

  • Emitted during pre-activation content linking when the DOM contains text nodes (often whitespace/​newlines) that don’t correspond to a control entry in content._arr.
  • Often benign, but it is a good signal that DOM↔control-array alignment is fragile.

Patch / plugin strategies

Strategy A: Silence known-noise logs (safe)

• Wrap/​monkeypatch the client-side pre_activate logger to skip warning output for exempt tag names (HTML, HEAD, BODY) when type is missing.

Strategy B: Fill context.map_Controls for common tags (safe)

• Ensure common typed tags are registered (or mapped) so style, main, etc. don’t warn.
• Prefer adding registrations in a single place near client startup rather than scattered per-control.

Strategy C: Make pre_activate_content_controls robust to whitespace text nodes (medium risk)

• Ignore text nodes where nodeType === 3 and nodeValue.trim() === '' during the alignment walk.
• Keep a deterministic repro (experiment 020) and add a regression assertion on console output if/​when you implement this.

Validation

• Primary: node src/​ui/​lab/​experiments/​020-jsgui3-server-activation/​check.js
• If you modify client-side controls/​bundles: npm run ui:client-build

References

• Experiment repro: src/​ui/​lab/​experiments/​020-jsgui3-server-activation/
• Guide: docs/​guides/​JSGUI3_UI_ARCHITECTURE_GUIDE.md (Client-Side Activation Flow)
• Upstream runtime (read-only reference in installed packages):
  • node_modules/​jsgui3-client/​client.js
  • node_modules/​jsgui3-html/​html-core/​html-core.js
  • node_modules/​jsgui3-html/​html-core/​control-enh.js
  • node_modules/​jsgui3-html/​html-core/​control-core.js