jsgui3-server 0.0.148 → 0.0.150

package/docs/books/adaptive-control-improvements/07-delivery-roadmap-and-ownership.md

@@ -0,0 +1,137 @@
+# Chapter 7 — Delivery Roadmap and Ownership
+
+This chapter turns the playbooks into an executable delivery sequence.
+
+## 7.1 Phase Plan
+
+### Phase 1 — Foundation (Platform Utilities)
+
+Deliver:
+
+1. View environment service
+2. Adaptive composition helper
+3. Responsive parameter resolution
+4. Initial mode-attribute + density token overlays
+
+Exit criteria:
+
+- utility APIs are documented and used in at least one upgraded control
+- root mode attributes update correctly in runtime
+
+### Phase 2 — Tier 1 Controls
+
+Deliver in this order:
+
+1. Master_Detail
+2. Split_Pane
+3. Tabbed_Panel
+4. Data_Table
+
+Exit criteria:
+
+- all Tier 1 controls pass required matrix assertions
+- no regressions in desktop baseline behavior
+
+### Phase 3 — Tier 2 Controls
+
+Deliver:
+
+1. Sidebar_Nav
+2. Toolbar
+3. Modal
+4. Form_Container
+
+Exit criteria:
+
+- shell navigation and core form workflows are adaptive across matrix
+
+### Phase 4 — Tier 3/4 and polish
+
+Deliver:
+
+- Window/Window_Manager adaptive constraints
+- Wizard and secondary control adjustments
+- density/touch refinements and final a11y polish
+
+Exit criteria:
+
+- project-level adaptive checklist reaches defined target threshold
+
+## 7.2 Ownership Model
+
+Recommend three streams in parallel:
+
+1. Platform stream:
+   - shared utilities, root attributes, token overlays
+2. Control stream:
+   - Tier 1/Tier 2 upgrades using shared utilities
+3. QA stream:
+   - viewport-matrix suites, screenshot artifacts, regression checks
+
+This avoids serial bottlenecks and keeps quality moving with implementation.
+
+## 7.3 Milestone Definitions
+
+### Milestone A — “Adaptive Infrastructure Ready”
+
+- foundation utilities merged
+- one control successfully migrated using new pattern
+
+### Milestone B — “Shell Controls Ready”
+
+- Tier 1 control set complete except Data_Table
+- shell behaviors validated across matrix
+
+### Milestone C — “Data-Dense Ready”
+
+- Data_Table mode family complete
+- key data workflows verified on phone/tablet/desktop
+
+### Milestone D — “Catalog Ready (Primary)”
+
+- Tier 2 controls complete
+- quality checklist green for prioritized control set
+
+## 7.4 Risk Register
+
+### Risk 1: control-level bespoke implementations diverge
+
+Mitigation:
+
+- enforce shared helper usage in review criteria
+
+### Risk 2: adaptive state leaks into domain model
+
+Mitigation:
+
+- explicit model-layer audit in PR checklist
+
+### Risk 3: desktop regressions during mobile improvements
+
+Mitigation:
+
+- mandatory desktop matrix profiles and before/after screenshots
+
+### Risk 4: test burden slows delivery
+
+Mitigation:
+
+- reusable matrix runner and assertion helper library
+
+## 7.5 Definition of Done for the Program
+
+The adaptive control improvement program is complete when:
+
+1. Tier 1 and Tier 2 controls are upgraded and documented.
+2. Shared adaptive utilities are adopted consistently.
+3. Mode-attribute and density-token styling policies are in place.
+4. Viewport-matrix quality gates are integrated in regular testing.
+5. The resulting developer path for adaptive control work is easier than ad-hoc responsive code.
+
+---
+
+This concludes the implementation-focused adaptive control improvement book.
+
+For implementation reviews and pull requests, continue with:
+
+- `08-appendix-tier1-acceptance-and-pr-templates.md`

package/docs/books/adaptive-control-improvements/08-appendix-tier1-acceptance-and-pr-templates.md

@@ -0,0 +1,261 @@
+# Chapter 8 — Appendix: Tier 1 Acceptance Checklists and PR Templates
+
+This appendix provides implementation-ready acceptance criteria and copy/paste PR templates
+for the first four Tier 1 controls:
+
+1. Master_Detail
+2. Split_Pane
+3. Tabbed_Panel
+4. Data_Table
+
+Use this appendix as the final gate before merge.
+
+## 8.1 Shared Tier 1 Acceptance Gate
+
+Every Tier 1 control PR must satisfy all items below.
+
+### A. Layer and state architecture
+
+- [ ] Adaptive behavior is mapped to Layer B/C/D (not Layer A domain logic).
+- [ ] No viewport/layout/density state is stored in `data.model`.
+- [ ] Resolved adaptive state is in `view.data.model`.
+- [ ] Transient UI state is in `view.model`.
+
+### B. Composition and environment
+
+- [ ] Uses shared environment contract (`layout_mode`, `density_mode`, `interaction_mode`, `motion_mode`).
+- [ ] Uses adaptive composition branching (or equivalent shared helper), not ad-hoc per-method viewport checks.
+- [ ] Supports phone, tablet, desktop behavior as defined in this book.
+- [ ] Preserves backward compatibility for desktop behavior unless explicitly changed.
+
+### C. Styling and theming
+
+- [ ] Uses mode attributes (`data-layout-mode` etc.) for adaptive styling policy.
+- [ ] Adaptive-relevant hardcoded spacing/sizing values are tokenized.
+- [ ] Touch-target policy is satisfied in touch contexts (minimum 44px where actionable).
+- [ ] Reduced-motion behavior is respected for adaptive transitions.
+
+### D. Accessibility and interaction
+
+- [ ] Keyboard paths remain valid after mode transitions.
+- [ ] ARIA roles/attributes remain correct after adaptive morphing.
+- [ ] Focus management and focus return behavior are defined for overlays/morphs.
+
+### E. Testing and validation
+
+- [ ] Viewport matrix includes: 390x844, 844x390, 768x1024, 1024x768, 1280x720, 1920x1080.
+- [ ] P0 assertions pass in all profiles.
+- [ ] P1 assertions pass in all profiles.
+- [ ] P2 assertions pass for controls where touch/visual ergonomics are central.
+- [ ] No new console errors during mode/orientation transitions.
+
+### F. Documentation and delivery
+
+- [ ] Control docs updated with adaptive mode behavior.
+- [ ] PR includes before/after screenshots for required profiles.
+- [ ] PR notes include known limitations and follow-ups.
+
+## 8.2 Master_Detail Checklist
+
+### Required behavior
+
+- [ ] Desktop: dual-pane (master + detail) default.
+- [ ] Tablet portrait: detail can be inline or overlay per resolved presentation mode.
+- [ ] Phone: list-first flow with detail in sheet/full detail panel pattern.
+
+### State and composition
+
+- [ ] `selected_id` remains domain state in `data.model`.
+- [ ] `detail_presentation` is resolved in `view.data.model`.
+- [ ] `detail_open` is transient in `view.model`.
+- [ ] Mode transition preserves selected item.
+
+### Interaction and a11y
+
+- [ ] Selecting master item updates detail in all modes.
+- [ ] Keyboard selection (Enter/Space) remains valid after morph.
+- [ ] Overlay detail has focus containment and proper close return target.
+
+### Test-specific
+
+- [ ] No horizontal overflow in phone profiles.
+- [ ] Selection-change event contract remains stable.
+
+## 8.3 Split_Pane Checklist
+
+### Required behavior
+
+- [ ] Desktop pointer mode: split + resize handle behavior retained.
+- [ ] Phone mode: no tiny drag-handle dependency (stack/toggle behavior used).
+- [ ] Tablet behavior follows defined portrait/landscape policy.
+
+### State and composition
+
+- [ ] `split_enabled` and orientation policy live in `view.data.model`.
+- [ ] Live ratio and active pane state are `view.model` (session-level).
+- [ ] Domain model remains device-agnostic.
+
+### Interaction and a11y
+
+- [ ] Pointer-only resize paths are gated by interaction mode.
+- [ ] Keyboard accessibility remains valid for pane switching controls.
+- [ ] Focus order is stable across orientation and mode changes.
+
+### Test-specific
+
+- [ ] Desktop drag resize min/max bounds still pass.
+- [ ] Phone profile has a usable pane-switch affordance.
+
+## 8.4 Tabbed_Panel Checklist
+
+### Required behavior
+
+- [ ] Narrow profiles use defined overflow strategy (`scroll`, `fit`, or `overflow_menu`).
+- [ ] Active tab remains visible/selectable in all profiles.
+- [ ] Desktop behavior remains functionally equivalent to prior baseline.
+
+### State and composition
+
+- [ ] Tab content definitions remain domain-side.
+- [ ] `tab_layout` is resolved in `view.data.model`.
+- [ ] Active tab and overflow menu open state are in `view.model`.
+
+### Interaction and a11y
+
+- [ ] Arrow/Home/End keyboard semantics preserved in all supported layouts.
+- [ ] `aria-selected` and control linkage attributes remain correct post-transition.
+- [ ] Focus behavior is deterministic when overflow menu opens/closes.
+
+### Test-specific
+
+- [ ] Mode transitions do not break tab/page pairing.
+- [ ] Touch target policy passes for tab labels in touch profiles.
+
+## 8.5 Data_Table Checklist
+
+### Required behavior
+
+- [ ] Desktop: full grid mode with existing advanced interactions retained.
+- [ ] Tablet: reduced/prioritized column mode.
+- [ ] Phone: card/list representation with access to secondary fields.
+
+### State and composition
+
+- [ ] Row data/filter/sort/selection remain in domain model structures.
+- [ ] `table_mode` and `visible_columns` resolved in `view.data.model`.
+- [ ] Expanded-row and transient interaction state remains in `view.model`.
+
+### Interaction and a11y
+
+- [ ] Selection semantics remain consistent across mode changes.
+- [ ] Keyboard navigation remains valid in grid modes.
+- [ ] Pointer-only features (for example column drag resize) are correctly gated.
+
+### Test-specific
+
+- [ ] Switching between table modes preserves selected row identity.
+- [ ] No data-loss in presentation transitions (grid ⇄ card/list).
+- [ ] Performance and rendering remain acceptable for representative row counts.
+
+## 8.6 Generic Tier 1 PR Template
+
+Use this template for any Tier 1 adaptive control PR.
+
+Repository shortcut:
+
+- `.github/pull_request_template_adaptive_tier1.md`
+
+```md
+# Adaptive Upgrade: <Control_Name>
+
+## Summary
+- Control: <Control_Name>
+- Tier: Tier 1
+- Scope: <brief summary>
+
+## Book Alignment
+- Four-layer impact: <A/B/C/D>
+- Model placement:
+  - data.model: <...>
+  - view.data.model: <...>
+  - view.model: <...>
+- Composition approach: <CSS-only | JS-composition | hybrid>
+
+## Behavior by Mode
+- Phone: <...>
+- Tablet: <...>
+- Desktop: <...>
+
+## Implementation Notes
+- Shared adaptive utilities used: <...>
+- Compatibility notes: <...>
+- Known tradeoffs: <...>
+
+## Testing
+- Viewport profiles covered: 390x844, 844x390, 768x1024, 1024x768, 1280x720, 1920x1080
+- P0 status: <pass/fail>
+- P1 status: <pass/fail>
+- P2 status: <pass/fail>
+- Console error check: <clean/issues>
+
+## Evidence
+- Screenshots: <paths>
+- Test files: <paths>
+
+## Checklist
+- [ ] Shared Tier 1 gate complete
+- [ ] Control-specific gate complete
+- [ ] Docs updated
+```
+
+## 8.7 Control-Specific PR Template Add-ons
+
+Append one of these blocks to the generic template.
+
+### Master_Detail add-on
+
+```md
+## Master_Detail Specific Checks
+- [ ] Selection persistence across mode transitions
+- [ ] Detail presentation policy implemented (inline/overlay/sheet)
+- [ ] Keyboard select behavior validated in all modes
+```
+
+### Split_Pane add-on
+
+```md
+## Split_Pane Specific Checks
+- [ ] Touch mode disables tiny-handle dependency
+- [ ] Desktop resize path unchanged and validated
+- [ ] Orientation and pane focus order validated
+```
+
+### Tabbed_Panel add-on
+
+```md
+## Tabbed_Panel Specific Checks
+- [ ] Overflow strategy implemented and validated
+- [ ] ARIA and keyboard behavior intact after layout changes
+- [ ] Active tab visibility guaranteed in narrow profiles
+```
+
+### Data_Table add-on
+
+```md
+## Data_Table Specific Checks
+- [ ] Grid/tablet/card-list mode family implemented
+- [ ] Visible column policy resolved by mode
+- [ ] Selection and sort/filter consistency across mode changes validated
+```
+
+## 8.8 Reviewer Fast-Path Checklist
+
+For rapid review, reviewers can verify in this order:
+
+1. State placement sanity (`data.model` vs view models)
+2. Mode behavior correctness (phone/tablet/desktop)
+3. Keyboard/ARIA integrity
+4. Viewport matrix evidence and pass status
+5. Desktop regression risk and screenshot evidence
+
+If all five checks are green, the PR is generally safe to merge.

package/docs/books/adaptive-control-improvements/README.md

@@ -0,0 +1,66 @@
+# Adaptive Control Improvements for jsgui3-html
+
+This book is a companion to the existing device-adaptive composition book.
+
+- Foundation principles: `docs/books/device-adaptive-composition/`
+- This book: concrete control and platform improvements to implement those principles across the current control catalog.
+
+## Why This Book
+
+The existing adaptive book defines architecture, model boundaries, styling strategy, and rollout phases.
+What it intentionally does not do in depth is provide a control-by-control implementation playbook.
+
+This book fills that gap by answering:
+
+1. Which controls should be upgraded first and why
+2. What specific changes each control needs in composition, state placement, styling, and interaction
+3. Which cross-cutting platform functions should be added to reduce repeated code
+4. What test matrix and quality gates are required before rollout
+
+## Scope
+
+Primary focus:
+
+- Large layout and shell controls
+- Navigation controls with mobile/orientation impacts
+- Data-dense controls that need structural adaptation
+- Cross-cutting adaptive utilities and token updates
+
+Secondary focus:
+
+- Utility controls with strong phone/tablet behavior implications
+
+Out of scope:
+
+- Rewriting stable atomic controls that already adapt via tokens
+- Visual redesigns unrelated to adaptive behavior
+
+## Core Alignment (from Device-Adaptive Composition Book)
+
+This book explicitly applies:
+
+- Chapter 2: Four-layer model (A/B/C/D)
+- Chapter 3: adaptive state in view models, not domain model
+- Chapter 4: mode attributes and token overrides
+- Chapter 6: environment service + adaptive composition helper patterns
+- Chapter 7: viewport-matrix quality gates
+- Chapter 8: phased rollout
+
+## Reading Order
+
+1. `01-control-candidate-matrix.md`
+2. `02-tier-1-layout-playbooks.md`
+3. `03-tier-2-navigation-form-overlay.md`
+4. `04-cross-cutting-platform-functionality.md`
+5. `05-styling-theming-density-upgrades.md`
+6. `06-testing-quality-gates.md`
+7. `07-delivery-roadmap-and-ownership.md`
+8. `08-appendix-tier1-acceptance-and-pr-templates.md`
+
+## Quick Start (Implementers)
+
+1. Build cross-cutting infrastructure from Chapter 4 first.
+2. Upgrade Tier 1 controls from Chapter 2 in priority order.
+3. Add/extend responsive tests from Chapter 6 as each control ships.
+4. Move through Tier 2 playbooks from Chapter 3.
+5. Track delivery against Chapter 7 ownership and milestones.

package/docs/books/admin-ui-authentication/01-threat-model-and-goals.md

@@ -0,0 +1,124 @@
+# Chapter 1 — Threat Model and Goals
+
+## Why this chapter first
+
+Authentication design becomes expensive when started too late. The Admin UI already has telemetry endpoints and an SSE channel, so this chapter defines what we are protecting and what can wait.
+
+## Assets to protect
+
+For jsgui3-server admin surfaces, primary assets are:
+
+1. **Control-plane actions**
+   - starting/stopping resources
+   - changing runtime config
+   - registering/removing routes
+2. **Sensitive observability data**
+   - host/process metadata
+   - route inventories
+   - internal resource names and states
+3. **Availability**
+   - preventing abuse of SSE streams and expensive endpoints
+
+## Threat model (practical)
+
+### External attacker
+- Can probe `/admin` and `/api/admin/*` endpoints.
+- Tries default credentials, weak tokens, replay, or unauthenticated access.
+
+### Internal but unauthorized user
+- Has network access but should not have admin privileges.
+- Attempts to read diagnostic state or execute write actions.
+
+### Session theft and browser attacks
+- Cookie theft, CSRF, XSS-assisted token misuse.
+- Stale sessions after role changes.
+
+### Operational mistakes
+- Admin endpoint exposed publicly by accident.
+- Weak defaults in non-production become production behavior.
+
+## Security goals
+
+### G1: Default deny for admin APIs
+- Any `/api/admin/*` endpoint should require auth by default.
+- Explicit allow-list only for bootstrapping/health if needed.
+
+### G2: Separate read and write permissions
+- Read-only operators should access telemetry.
+- Mutating operations require stronger roles.
+
+### G3: Short-lived, revocable sessions
+- Session invalidation should take effect quickly.
+- SSE clients must be disconnected when auth is revoked.
+
+### G4: Browser-safe auth transport
+- Prefer secure, httpOnly cookies for web-admin sessions.
+- Apply CSRF protection for state-changing endpoints.
+
+### G5: Deployment-safe defaults
+- Clear behavior in dev vs production.
+- Explicit configuration for trusted origins and cookie policy.
+
+## Non-goals for first implementation phase
+
+To keep delivery realistic, v1 auth does **not** need:
+
+- Multi-tenant federation (SAML/OIDC enterprise SSO) on day one.
+- Fine-grained per-resource ACL matrices.
+- Full audit analytics UI before basic enforcement exists.
+
+## Phased implementation plan
+
+### Phase A — Guard rails (immediate)
+- Keep admin UI read-only while auth is incomplete.
+- Avoid adding new mutation endpoints.
+- Document intended privileged operations.
+
+### Phase B — Baseline authentication
+- Add login/logout endpoint pair.
+- Add session issuance + validation middleware.
+- Require auth for all `/api/admin/v1/*` and `/admin/v1`.
+
+### Phase C — Authorization and hardening
+- Introduce roles: `admin_read`, `admin_write`.
+- Add CSRF for write paths.
+- Add rate limiting and SSE connection caps.
+
+### Phase D — Operational maturity
+- Session revocation, inactivity expiry, and rotation.
+- Structured security/audit logs.
+- Runbook for emergency lockout and credential reset.
+
+## Design constraints from current codebase
+
+Given existing server patterns:
+
+- Admin routes are registered through router adapters.
+- SSE is already used for live events.
+- The current v1 UI is telemetry-first and can remain read-only safely.
+
+This means we can adopt auth incrementally without blocking current UI progress.
+
+## Decision points (to finalize in next chapter)
+
+1. Session storage model: in-memory vs Redis-backed.
+2. Credential source: static bootstrap admin vs user store resource.
+3. Cookie strategy: strict same-site policy for local-only admin vs configurable for reverse proxies.
+4. Role model shape: two-role minimal model vs extensible claims model.
+
+## Selected v1 decisions (current)
+
+The following decisions are now selected for v1 implementation:
+
+1. **Session storage model:** in-memory sessions.
+2. **Credential source:** user resource/store (not env-bootstrap only).
+3. **Protection scope:** protect both `/admin/v1` and `/api/admin/v1/*` immediately.
+
+These choices keep the first auth rollout simple while still enforcing an end-to-end protected admin surface.
+
+## Exit criteria for this chapter
+
+Before coding auth middleware, agree on:
+- which endpoints require `admin_read` vs `admin_write`,
+- session lifecycle requirements,
+- dev/prod default policy matrix.

package/docs/books/admin-ui-authentication/02-session-model-and-token-model.md

@@ -0,0 +1,75 @@
+# Chapter 2 — Session Model and Token Model (v1 Decision)
+
+## Chosen model for v1
+
+This project uses **stateful in-memory sessions** for admin authentication in v1.
+
+### Why this model now
+
+- Fastest path to safe protection of `/admin/v1` and `/api/admin/v1/*`.
+- Works with existing single-process server setup.
+- Easy to reason about and debug while auth surface stabilizes.
+
+### Trade-offs
+
+- Sessions are lost on server restart.
+- Not suitable for multi-instance horizontal scaling without shared storage.
+- Requires follow-up for production HA (Phase D).
+
+## Session shape
+
+A session record contains:
+
+- `session_id`
+- `user` (`username`, `roles`)
+- `created_at`
+- `expires_at`
+
+Cookie name: `jsgui_admin_v1_sid`
+
+Cookie policy (v1):
+
+- `HttpOnly`
+- `SameSite=Lax`
+- `Path=/`
+- `Secure` enabled in production mode
+
+## User credential source (v1)
+
+Credentials are validated against an **in-process user store resource-like service**.
+
+- Primary bootstrap path: `ADMIN_V1_USER` + `ADMIN_V1_PASSWORD`.
+- Development fallback (non-production only): `admin/admin`.
+- Production without explicit password keeps login disabled until configured.
+
+## Endpoint policy
+
+Public endpoints:
+
+- `POST /api/admin/v1/auth/login`
+- `POST /api/admin/v1/auth/logout`
+- `GET /api/admin/v1/auth/session`
+- `GET /admin/v1/login`
+
+Protected endpoints:
+
+- `GET /admin/v1`
+- `GET /api/admin/v1/status`
+- `GET /api/admin/v1/resources`
+- `GET /api/admin/v1/routes`
+- `GET /api/admin/v1/events`
+
+## Request flow
+
+1. Browser requests `/admin/v1`.
+2. If unauthenticated, server redirects to `/admin/v1/login`.
+3. Login form posts credentials to `/api/admin/v1/auth/login`.
+4. Server validates credentials and issues session cookie.
+5. Browser returns to `/admin/v1` and can access protected APIs.
+
+## Planned evolution (post-v1)
+
+- Move session store to Redis or equivalent shared backing store.
+- Add idle timeout refresh strategy.
+- Add session revocation events and forced SSE disconnect.
+- Add CSRF protections for write endpoints before mutation APIs launch.