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