jsgui3 Lab Experimentation

jsgui3 Lab Experimentation

Scope

• Run existing lab experiments to confirm behavior (event delegation, activation, MVVM, mixins, helpers)
• Create minimal new lab experiments when encountering unknown or disputed jsgui3 behavior
• Promote stable findings into the repo memory system (Skills + Patterns/​Lessons + guides when appropriate)

Inputs

• The question you’re trying to answer (1 sentence)
• The target surface (control/​server route/​activation path/​event semantics/​perf)
• Whether you need SSR-only, client activation, or browser semantics (delegation/​bubbling)

Procedure

1. Inventory prior art

   • Search docs first: node tools/​dev/​md-scan.js --guide --search "<topic>" --json
   • Then search sessions: node tools/​dev/​md-scan.js --dir docs/​sessions --search "<topic>" --json

2. Check whether a lab experiment already covers it

   • Open lab index: src/​ui/​lab/​README.md
   • Open manifest: src/​ui/​lab/​manifest.json
   • Optional: render the Lab Console card list (quick sanity): node src/​ui/​lab/​checks/​labConsole.check.js

3. Run the smallest relevant check(s)

   • Each experiment should have a check.js (or check.all.js) that exits cleanly.
   • Prefer targeted runs, e.g.:
     • node src/​ui/​lab/​experiments/​002-platform-helpers/​check.js
     • node src/​ui/​lab/​experiments/​004-theme-mixin/​check.js

4. If the answer is still unclear, create a minimal new experiment

   • Create src/​ui/​lab/​experiments/​NNN-short-slug/
   • Add README.md (hypothesis + expected result) and check.js (deterministic assertions)
   • Add an entry to src/​ui/​lab/​manifest.json and the table in src/​ui/​lab/​README.md

5. If the behavior touches event semantics, run the delegation suite

   • Use the shared runner (reuses one browser/​page):
     • node src/​ui/​lab/​experiments/​run-delegation-suite.js --scenario=005,006
   • Add/​adjust scenarios if your change affects capture/​bubble/​selector matching/​stopPropagation.

6. If the behavior requires SSR + client activation + real interactivity, run a Puppeteer scenario suite

   • Use the scenario suite runner (single browser, many scenarios):
     • node tools/​dev/​ui-scenario-suite.js --suite=scripts/​ui/​scenarios/​control-harness-counter.suite.js
   • This is the recommended fast path for validating control activation wiring (DOM linking, event listeners, state updates) without paying the cost of full Jest/​Puppeteer E2E per test.
   • Prefer this over adding more “JS-only DOM semantics” scenarios when what you really need is jsgui3 activation behavior.

7. Distill the validated finding into durable memory

   • Create/​extend a Skill (this registry): docs/​agi/​SKILLS.md
   • Add/​extend a Pattern if it’s broadly reusable: docs/​agi/​PATTERNS.md
   • Write a guide if it’s a subsystem-level discovery: docs/​guides/…
   • Record evidence + commands in the current session directory under docs/​sessions/​...

Validation

• Lab console renders: node src/​ui/​lab/​checks/​labConsole.check.js

• Run the specific experiment check(s) you relied on (examples):

  • node src/​ui/​lab/​experiments/​001-color-palette/​check.js
  • node src/​ui/​lab/​experiments/​002-platform-helpers/​check.js
  • node src/​ui/​lab/​experiments/​004-theme-mixin/​check.js

• If delegation/​event semantics are involved:

  • node src/​ui/​lab/​experiments/​run-delegation-suite.js --scenario=005,006,007,008,011,014

• If you need SSR + activation + browser interaction coverage:

  • node tools/​dev/​ui-scenario-suite.js --suite=scripts/​ui/​scenarios/​control-harness-counter.suite.js

Escalation / Research request

Ask for dedicated research if:

• A behavior only reproduces with SSR + activation + bundling and no existing lab harness covers it
• A change appears to require new shared harness utilities (browserHarness / activation harness)
• The experiment needs performance instrumentation (counts, timings, memory) beyond a simple check

References

• Lab index: src/​ui/​lab/​README.md
• Lab manifest: src/​ui/​lab/​manifest.json
• Delegation suite runner: src/​ui/​lab/​experiments/​run-delegation-suite.js
• Puppeteer scenario suites guide: docs/​guides/​PUPPETEER_SCENARIO_SUITES.md
• Pattern: “Lab-First jsgui3 Knowledge Gap Closure” in docs/​agi/​PATTERNS.md
• General experimental research SOP: docs/​agi/​skills/​experimental-research-metacognition/​SKILL.md