jsgui3-server 0.0.149 → 0.0.151

package/docs/books/device-adaptive-composition/07-testing-harness-and-quality-gates.md

@@ -0,0 +1,265 @@
+# Chapter 7 — Testing Harness and Quality Gates
+
+## Why Responsive Testing Must Be Explicit
+
+A control can pass every interaction test at 1280×900 and still be broken on a phone. Buttons overlap, text overflows, drawers fail to open, keyboard paths become incomplete. These are not edge cases — they affect real users on real devices.
+
+The jsgui3 test suite currently validates rich interactivity across 14+ Playwright suites, all running at a single viewport size. This chapter defines how to extend that coverage to a **viewport matrix** — running key tests across multiple screen dimensions and verifying that adaptive behavior works correctly at each size.
+
+## The Viewport Matrix
+
+### Minimum Required Profiles
+
+Every responsive test suite should exercise these six profiles:
+
+| Profile | Width × Height | Represents |
+|---------|---------------|------------|
+| Phone portrait | 390 × 844 | iPhone 14, typical Android |
+| Phone landscape | 844 × 390 | iPhone 14 rotated |
+| Tablet portrait | 768 × 1024 | iPad, Surface Go portrait |
+| Tablet landscape | 1024 × 768 | iPad landscape |
+| Desktop narrow | 1280 × 720 | Laptop, resized browser |
+| Desktop wide | 1920 × 1080 | Full HD monitor |
+
+### Optional Extended Profiles
+
+For thorough coverage, add:
+
+| Profile | Width × Height | Represents |
+|---------|---------------|------------|
+| Phone small | 320 × 568 | iPhone SE, older Android |
+| Tablet large | 1024 × 1366 | iPad Pro 12.9″ portrait |
+| Desktop 4K | 2560 × 1440 | High-resolution desktop |
+| Embedded narrow | 400 × 600 | Widget in a sidebar |
+
+## Assertion Categories
+
+For each viewport profile, tests should cover these categories, ordered by priority:
+
+### P0: Layout Integrity
+
+The most fundamental check — does the layout work at this size?
+
+```js
+// No horizontal overflow
+const body_width = await page.evaluate(() => document.body.scrollWidth);
+const viewport_width = page.viewportSize().width;
+assert(body_width <= viewport_width + 1, 'No horizontal overflow');
+
+// Key containers are visible
+const content = await page.$('.content-area');
+const box = await content.boundingBox();
+assert(box.width > 100, 'Content area has reasonable width');
+assert(box.height > 50, 'Content area has reasonable height');
+```
+
+### P0: Interaction Integrity
+
+Controls remain usable — clickable, focusable, and responsive:
+
+```js
+// Buttons are clickable (not obscured, not zero-size)
+const buttons = await page.$$('button');
+for (const btn of buttons) {
+    const box = await btn.boundingBox();
+    if (box) {
+        assert(box.width >= 20, `Button width >= 20px`);
+        assert(box.height >= 20, `Button height >= 20px`);
+    }
+}
+
+// Interactive elements respond to clicks
+await page.click('.tab-label:first-child');
+await delay(200);
+const active = await page.$eval('.tab-label:first-child input', el => el.checked);
+assert(active, 'Tab responds to click at this viewport');
+```
+
+### P1: Adaptive Morphing
+
+If the app uses compose_adaptive or region morphing, verify the correct structure appears:
+
+```js
+// At phone width: navigation should be a drawer, not inline
+if (profile.name === 'phone_portrait') {
+    const drawer = await page.$('.drawer');
+    assert(drawer, 'Navigation renders as drawer on phone');
+    const sidebar = await page.$('.nav-sidebar');
+    assert(!sidebar, 'No inline sidebar on phone');
+}
+
+// At desktop width: navigation should be inline sidebar
+if (profile.name === 'desktop_wide') {
+    const sidebar = await page.$('.nav-sidebar');
+    assert(sidebar, 'Navigation renders as sidebar on desktop');
+}
+```
+
+### P1: Accessibility Integrity
+
+Keyboard navigation and ARIA attributes remain correct across sizes:
+
+```js
+// Focus is reachable for all interactive elements
+const focusable = await page.$$('button, a[href], input, select, textarea, [tabindex="0"]');
+assert(focusable.length > 0, 'Has focusable elements');
+
+// ARIA roles are present (not removed by adaptive composition)
+const tabs = await page.$$('[role="tab"]');
+if (tabs.length > 0) {
+    const aria = await tabs[0].getAttribute('aria-selected');
+    assert(aria !== null, 'Tab has aria-selected attribute');
+}
+```
+
+### P2: Visual Integrity
+
+Token-driven styling applies correctly:
+
+```js
+// Theme tokens are applied (not broken by mode switch)
+const bg = await page.$eval('body', el => getComputedStyle(el).backgroundColor);
+assert(bg !== '', 'Body has background color');
+
+// Touch targets meet minimum size on touch profiles
+if (profile.interaction_mode === 'touch') {
+    const buttons = await page.$$('button');
+    for (const btn of buttons) {
+        const box = await btn.boundingBox();
+        if (box) {
+            assert(box.height >= 44, `Touch target >= 44px`);
+        }
+    }
+}
+```
+
+## Practical Harness Pattern
+
+### Viewport Matrix Runner
+
+The existing Playwright test pattern uses self-contained test files with HTTP servers. Extend this with a viewport loop:
+
+```js
+const VIEWPORTS = [
+    { name: 'phone_portrait',   width: 390,  height: 844  },
+    { name: 'phone_landscape',  width: 844,  height: 390  },
+    { name: 'tablet_portrait',  width: 768,  height: 1024 },
+    { name: 'tablet_landscape', width: 1024, height: 768  },
+    { name: 'desktop_narrow',   width: 1280, height: 720  },
+    { name: 'desktop_wide',     width: 1920, height: 1080 }
+];
+
+async function run_viewport_matrix(page, assertions_fn) {
+    const results = [];
+
+    for (const vp of VIEWPORTS) {
+        await page.setViewportSize({ width: vp.width, height: vp.height });
+        await delay(300); // Allow layout reflow and adaptive recomposition
+
+        console.log(`\n── ${vp.name} (${vp.width}×${vp.height}) ──`);
+
+        const vp_results = await assertions_fn(page, vp);
+        results.push({ viewport: vp.name, ...vp_results });
+
+        // Capture screenshot for visual spot-check
+        await page.screenshot({
+            path: path.join(SCREENSHOT_DIR, `${test_name}-${vp.name}.png`),
+            fullPage: true
+        });
+    }
+
+    return results;
+}
+```
+
+### Integration with Existing Test Runner
+
+The aggregate runner at `test/e2e/playwright/run_all_playwright.js` can include viewport-matrix tests as additional suites. Each adaptive control gets its own matrix test file:
+
+```
+test/e2e/playwright/
+  showcase_app.e2e.playwright.js          ← existing (single viewport)
+  showcase_app_responsive.e2e.playwright.js ← NEW (viewport matrix)
+  drawer_responsive.e2e.playwright.js     ← NEW (Drawer adaptation)
+```
+
+### Screenshot Artifacts
+
+Each viewport capture goes to a `screenshots/` directory next to the test file, named with the viewport profile:
+
+```
+screenshots/
+  showcase-phone_portrait.png
+  showcase-phone_landscape.png
+  showcase-tablet_portrait.png
+  showcase-tablet_landscape.png
+  showcase-desktop_narrow.png
+  showcase-desktop_wide.png
+```
+
+These serve as visual regression baselines. They're not pixel-compared automatically (brittle), but they provide quick human review for unexpected layout changes.
+
+## Quality Gates
+
+### Gate Levels
+
+| Gate | Scope | When |
+|------|-------|------|
+| P0 Gate | Layout + interaction integrity at all 6 viewports | Every PR that touches layout or composition |
+| P1 Gate | Adaptive morphing + accessibility at all 6 viewports | Every PR that touches adaptive controls |
+| P2 Gate | Visual integrity + touch targets at all 6 viewports | Before releases |
+
+### Definition of "Responsive Green"
+
+A control suite is "responsive green" when:
+
+1. Zero horizontal overflow at any viewport
+2. All interactive elements remain clickable/focusable
+3. Adaptive morphing produces the correct structure per mode
+4. No uncaught errors in any viewport profile
+5. Screenshots captured successfully for visual review
+
+### Incremental Adoption
+
+Not every test suite needs viewport-matrix coverage immediately. The priority order:
+
+1. **Showcase app** — the reference implementation, highest priority
+2. **Shell/navigation controls** — Drawer, Tabbed_Panel, Accordion
+3. **Data-dense controls** — tables, forms, editors
+4. **Utility controls** — modals, tooltips, popovers
+5. **Atomic controls** — buttons, inputs, chips (usually correct by token inheritance)
+
+## Testing the Environment Service Itself
+
+The View Environment Service (Pattern 1 from Chapter 6) should have its own unit tests:
+
+```js
+// Test: mode resolution from viewport width
+const env = new View_Environment({ defaults: { layout_mode: 'desktop' } });
+env._resolve_from_viewport(390, 844);
+assert(env.state.layout_mode === 'phone');
+assert(env.state.viewport.orientation === 'portrait');
+
+env._resolve_from_viewport(1024, 768);
+assert(env.state.layout_mode === 'desktop');
+assert(env.state.viewport.orientation === 'landscape');
+
+// Test: change events fire correctly
+let change_count = 0;
+env.on('change:layout_mode', () => change_count++);
+env._resolve_from_viewport(390, 844);
+env._resolve_from_viewport(1920, 1080);
+assert(change_count === 2);
+```
+
+## Summary
+
+Responsive testing is not optional — it's a quality gate. The existing Playwright infrastructure is well-suited for viewport-matrix extension. The key additions are:
+
+1. A standard set of viewport profiles
+2. A `run_viewport_matrix()` utility for looping tests across sizes
+3. Prioritized assertion categories (P0/P1/P2)
+4. Screenshot artifacts for visual review
+5. Incremental adoption from showcase → shells → data controls → utilities
+
+**Next:** [Chapter 8](08-roadmap-and-adoption-plan.md) puts everything together into a phased adoption plan.

package/docs/books/device-adaptive-composition/08-roadmap-and-adoption-plan.md

@@ -0,0 +1,250 @@
+# Chapter 8 — Roadmap and Adoption Plan
+
+## Guiding Principle
+
+Ship value incrementally. Each phase should produce usable outcomes — not just infrastructure that waits for future phases to become useful. Every phase ends with working code, passing tests, and updated documentation.
+
+## Phase A: Standardize Environment Vocabulary
+
+**Goal:** Establish a shared language so all controls and apps use the same terms for the same concepts.
+
+### Deliverables
+
+1. **Canonical mode taxonomy document** — formal definitions of:
+   - Layout modes: `phone` (≤599px), `tablet` (600–1023px), `desktop` (≥1024px)
+   - Density modes: `compact`, `cozy` (default), `comfortable`
+   - Interaction modes: `touch`, `pointer`, `hybrid`
+   - Motion modes: `normal`, `reduced`
+
+2. **Root-level mode attributes** — CSS and JS both reference:
+   - `data-layout-mode` on `<html>` or `<body>`
+   - `data-density-mode`
+   - `data-interaction-mode`
+
+3. **Density token override CSS** — a small CSS file that overrides `--j-space-*` and `--admin-*` tokens per density mode (as described in Chapter 4).
+
+### Estimated Effort
+
+Small. Mostly documentation and a CSS file. No runtime code changes.
+
+### Outcome
+
+Every developer and every control has a common vocabulary. CSS selectors like `[data-layout-mode="phone"]` work immediately, even before the environment service exists, because developers can set the attributes manually for testing.
+
+### Dependencies
+
+None. This can start today.
+
+---
+
+## Phase B: Ship Adaptive Helper APIs
+
+**Goal:** Provide the runtime infrastructure so controls can respond to environment changes.
+
+### Deliverables
+
+1. **`View_Environment` service** — the observer class described in Chapter 6, Pattern 1:
+   - Viewport observation with debounced resize handling
+   - Mode resolution from configurable breakpoints
+   - Change events for layout, density, interaction, and motion modes
+   - SSR-safe defaults
+   - Sets root-level data attributes from Phase A
+
+2. **`compose_adaptive()` helper** — the composition branching utility from Chapter 6, Pattern 2:
+   - Reads layout_mode, calls matching branch
+   - Registers change listener for recomposition
+   - Handles fallback (tablet → phone → desktop)
+   - Returns cleanup function
+
+3. **Responsive param branch support in `theme_params`** — Chapter 6, Pattern 3:
+   - Accept mode-keyed param objects
+   - Auto-resolve based on current layout_mode
+   - Re-resolve on mode change
+
+### Estimated Effort
+
+Medium. View_Environment is ~150 lines. compose_adaptive is ~60 lines. Param branching is a modest extension to existing theme_params resolver.
+
+### Outcome
+
+App developers can write `compose_adaptive(this, { phone, tablet, desktop })` and get correct behavior. The boilerplate for responsive composition drops from ~30 lines per control to ~5 lines.
+
+### Dependencies
+
+Phase A (vocabulary must be defined before the service uses it).
+
+---
+
+## Phase C: Upgrade Control Catalog Incrementally
+
+**Goal:** Make existing controls responsive-aware, prioritized by impact.
+
+### Priority Tiers
+
+**Tier 1: Shell and navigation** (highest impact — these define app structure)
+
+| Control | Adaptation |
+|---------|-----------|
+| Drawer | Already has breakpoint support; wire to View_Environment instead of manual resize |
+| Tabbed_Panel | Overflow-scroll on phone when tabs > 4; vertical tabs on narrow embedded |
+| Accordion | Becomes primary navigation pattern on phone |
+| Stack | No changes needed (already flexible); document responsive patterns |
+
+**Tier 2: Data-dense controls** (high visibility in admin/dashboard apps)
+
+| Control | Adaptation |
+|---------|-----------|
+| Data tables | Column reduction via responsive params; card layout option for phone |
+| Forms | Single-column on phone; multi-column on desktop |
+| Code_Editor | Full-bleed on phone; constrained width on desktop |
+| Filter_Chips | Horizontal scroll strip on narrow; wrapped on wide |
+
+**Tier 3: Utility and overlay controls**
+
+| Control | Adaptation |
+|---------|-----------|
+| Drawer (overlay variant) | Already works; ensure touch dismissal |
+| Modals/dialogs | Full-screen on phone; centered constrained on desktop |
+| Tooltips | Suppress on touch (use bottom sheet or inline); show on pointer |
+| Split_Pane | Disable resize handle on phone (stack instead) |
+
+**Tier 4: Atomic controls** (lowest priority — usually correct via token inheritance)
+
+| Control | Adaptation |
+|---------|-----------|
+| Buttons | Touch target enforcement via density tokens |
+| Inputs | Larger padding/height via density tokens |
+| Chips, badges | Usually fine at all sizes |
+
+### Approach
+
+Each control upgrade follows the same pattern:
+1. Add responsive params if needed
+2. Use `compose_adaptive()` for structural changes (or skip if CSS-only adaptation suffices)
+3. Wire to View_Environment instead of manual `window.innerWidth`
+4. Add viewport-matrix test assertions
+5. Update control documentation
+
+### Estimated Effort
+
+Large overall, but each individual control is small (hours, not days). Can be done incrementally by different contributors.
+
+### Dependencies
+
+Phase B (helpers must exist before controls use them).
+
+---
+
+## Phase D: Formalize Responsive Test Suites
+
+**Goal:** Make responsive testing a first-class quality gate.
+
+### Deliverables
+
+1. **`run_viewport_matrix()` test utility** — the shared function from Chapter 7 that loops tests across 6 viewport profiles.
+
+2. **Viewport-matrix tests** for each Tier 1 and Tier 2 control:
+   - Showcase app responsive suite
+   - Drawer responsive suite
+   - Tabbed_Panel responsive suite
+   - Data table responsive suite
+
+3. **Screenshot baseline directory** — organized per-control, per-viewport screenshots checked into the repo for visual regression review.
+
+4. **CI integration** — responsive suites run in the aggregate test runner alongside existing tests.
+
+### Estimated Effort
+
+Medium. The utility is small (~50 lines). Each control's responsive test is ~100 lines (mostly reusing the single-viewport test with a viewport loop wrapper).
+
+### Outcome
+
+Responsive regressions are caught before merge. No more "it works on my desktop" issues.
+
+### Dependencies
+
+Phase C (controls must be adaptive before their responsive tests can verify adaptation). However, the showcase app responsive test can ship with Phase B, since the showcase manually implements adaptive patterns.
+
+---
+
+## Phase E: Showcase App as Reference Implementation
+
+**Goal:** The showcase app demonstrates every adaptive pattern, serving as both a demo and a regression test.
+
+### Deliverables
+
+1. **Adaptive showcase composition** — the showcase app uses `compose_adaptive()` for its shell layout, demonstrating:
+   - 3-column → 2-column → 1-column shell transitions
+   - Nav sidebar → pill bar → drawer morphing
+   - Theme studio → slide-over → presets-only adaptation
+
+2. **Theme profile persistence** — the showcase uses full theme profiles (theme + density + overrides) with export/import.
+
+3. **Responsive Playwright suite** — 6-viewport test covering all showcase sections.
+
+4. **Documentation** — the showcase README documents every adaptive pattern used, linking back to the relevant book chapter.
+
+### Estimated Effort
+
+Medium. Most of the work is refactoring the existing showcase composition to use the new helpers.
+
+### Outcome
+
+New developers can look at the showcase app and see: "this is how you build a responsive jsgui3 app." Every pattern from this book is demonstrated in working code.
+
+### Dependencies
+
+Phases A–D. This is the capstone.
+
+---
+
+## Phase Dependency Map
+
+```
+Phase A (Vocabulary)
+    ↓
+Phase B (Helper APIs)  ──→  Phase D.1 (Showcase responsive test)
+    ↓
+Phase C (Controls)     ──→  Phase D (Full test suites)
+    ↓
+Phase E (Showcase reference)
+```
+
+Phases A and B are sequential prerequisites. Phase C and D overlap — as each control is upgraded, its test is written. Phase E comes last.
+
+## Recommended Near-Term Backlog
+
+Starting from zero, the highest-value first steps are:
+
+| # | Task | Phase | Why First |
+|---|------|-------|-----------|
+| 1 | Define mode taxonomy in docs | A | Foundation — everything references these terms |
+| 2 | Write density-mode CSS overrides | A | Immediately usable in any app |
+| 3 | Implement `View_Environment` service | B | Unlocks all adaptive patterns |
+| 4 | Implement `compose_adaptive()` helper | B | Biggest developer productivity gain |
+| 5 | Add viewport-matrix test for showcase | D.1 | Proves the test harness works |
+| 6 | Wire Drawer to View_Environment | C | First control upgrade, validates the pattern |
+| 7 | Refactor showcase to use compose_adaptive | E | Reference implementation |
+
+## What Not to Build
+
+Some things are explicitly **out of scope** for the near-term, either because they're premature or because simpler alternatives exist:
+
+- **Automatic container-query composition** — useful later, but viewport-level adaptation covers 90% of cases. Ship viewport first.
+- **Visual regression pixel comparison** — screenshot captures for human review are sufficient. Pixel-diff tools add complexity with marginal value at this scale.
+- **Server-side device detection** — User-Agent parsing is unreliable and shrinking in value. Desktop-first SSR with client refinement is simpler and more robust.
+- **per-control CSS-only responsive overrides** — mode attributes and token tiers handle this at scale. Per-control media queries should be the exception, not the pattern.
+
+## Strategic Summary
+
+The adaptive composition system is not a big-bang rewrite. It's a thin coordination layer on top of strong existing foundations:
+
+- **Tokens** already handle theming → extend to density
+- **MVVM** already separates models → use view.data.model for environment state
+- **Drawer** already has breakpoints → generalize the pattern
+- **Playwright** already tests interactivity → add viewport loops
+- **Showcase** already demonstrates controls → make it responsive
+
+Each phase delivers value independently. An app can use Phase A (manual mode attributes in CSS) without Phase B (automatic environment service). Phase C controls gracefully degrade when the environment service isn't present.
+
+The goal is that within a few iterations, building a responsive jsgui3 app is **easier than building a non-responsive one**, because the platform defaults to adaptive behavior.

package/docs/books/device-adaptive-composition/README.md

@@ -0,0 +1,47 @@
+# Device-Adaptive Composition & Styling in jsgui3
+
+A practical guide to building UIs that work well on every screen — from phones in portrait to widescreen desktops — using the jsgui3 platform's compositional architecture.
+
+## Why This Book Exists
+
+Modern web applications are expected to work on a phone held one-handed, a tablet propped on a desk, a laptop with a resized browser window, and a 4K monitor. Most frameworks address this with CSS media queries alone, leaving developers to scatter breakpoint logic across dozens of stylesheets with no architectural guidance.
+
+jsgui3 has a unique advantage: controls are **composed programmatically** on the server and **activated** on the client. That means the platform can make structural composition decisions — not just styling tweaks — based on screen environment. A sidebar can become a drawer. A multi-column layout can collapse to tabs. A data table can transform into a card list. These are composition changes, not CSS hacks.
+
+This book explains how to make those decisions cleanly: where adaptive logic should live, how it interacts with the MVVM model separation that jsgui3 already provides, and what platform infrastructure is needed to make high-level app code stay simple while supporting every device well.
+
+## What You'll Learn
+
+- What responsive infrastructure jsgui3 already has and where the gaps are
+- A layered composition model that separates business logic from device adaptation
+- How to keep adaptive state in view models without polluting domain data
+- A breakpoint and theming strategy built on the existing token system
+- Concrete assessment of how the showcase app behaves across devices
+- Implementation patterns and APIs for adaptive composition
+- How to test responsive behavior systematically with Playwright
+- A phased roadmap for adopting these patterns across the control catalog
+
+## Audience
+
+- **Platform maintainers** designing control APIs and infrastructure
+- **App developers** building product UIs on jsgui3
+- **Contributors** implementing responsive, theme, and accessibility features
+
+## Reading Order
+
+The chapters build on each other. Chapters 1–3 establish concepts. Chapters 4–5 apply them concretely. Chapters 6–8 provide implementation guidance.
+
+1. [Platform Feature Audit](01-platform-feature-audit.md) — what exists today, what's missing
+2. [Responsive Composition Model](02-responsive-composition-model.md) — the four-layer architecture
+3. [Data Model vs View Model](03-data-model-vs-view-model.md) — where adaptive state belongs
+4. [Styling, Themes, and Breakpoints](04-styling-theme-breakpoints.md) — tokens, density, and mode classes
+5. [Showcase App Multi-Device Assessment](05-showcase-app-multi-device-assessment.md) — practical analysis
+6. [Implementation Patterns and APIs](06-implementation-patterns-and-apis.md) — code-level guidance
+7. [Testing Harness and Quality Gates](07-testing-harness-and-quality-gates.md) — viewport-matrix testing
+8. [Roadmap and Adoption Plan](08-roadmap-and-adoption-plan.md) — phased rollout
+
+## Core Thesis
+
+jsgui3 already has strong primitives for compositional controls, design tokens, and MVVM-style model separation. The next step is to formalize adaptive layout and styling decisions as **first-class platform concepts** so that app developers can express adaptive intent in a few lines of declarative code, while the platform's mid-level and low-level layers handle the complexity of resolution, rendering, and testing.
+
+Keep high-level code easy. Let mid-level code absorb complexity. Trust the low-level foundations in lang-tools and html-core to handle the heavy lifting.