jsgui3-server 0.0.149 → 0.0.151

package/docs/books/creating-a-new-admin-ui/17-next-steps-process-resource-roadmap.md

@@ -0,0 +1,356 @@
+# Chapter 17 — Next Steps Roadmap (Process/Resource-Centric Admin)
+
+## Purpose of This Chapter
+
+This chapter is a **handoff-grade implementation roadmap** for the next phase of the Admin UI. It captures the current baseline, architectural direction, concrete work packages, and acceptance criteria so another agent (or engineer) can continue confidently.
+
+This roadmap is intentionally **domain-agnostic**: it does not assume crawler-specific behavior or any workload-specific semantics.
+
+---
+
+## Current Baseline (Already Implemented)
+
+### Admin UI v1 shell and read-only sections
+
+- Admin shell with sidebar, toolbar, content, and status bar.
+- Dashboard stat cards.
+- Read-only sections for Resources, Routes, Settings with loading/error/retry states.
+- Control-first rendering for section content (tables, key-value rows, actions) using jsgui controls, not direct DOM string patching.
+- Interactive shell wiring implemented for:
+  - sidebar item activation
+  - phone tab synchronization
+  - hamburger/overlay sidebar toggling
+  - custom section insertion and refresh replacement
+  - logout/retry actions in dynamic panels
+
+### Telemetry adapter and APIs
+
+- `/api/admin/v1/status`
+- `/api/admin/v1/resources`
+- `/api/admin/v1/routes`
+- `/api/admin/v1/events` (SSE)
+
+### Authentication and authorization groundwork
+
+- Login/logout/session endpoints:
+  - `POST /api/admin/v1/auth/login`
+  - `POST /api/admin/v1/auth/logout`
+  - `GET /api/admin/v1/auth/session`
+- Protected UI + API surface (`/admin/v1` and `/api/admin/v1/*`).
+- In-memory sessions and role groundwork:
+  - `admin_read`
+  - `admin_write` (reserved for future mutation endpoints)
+
+### Documentation baseline
+
+- Auth book started:
+  - Threat model
+  - Session/token model
+  - middleware/authorization patterns
+- Troubleshooting updated with generated shim cache guidance.
+- Admin shell and testing chapters updated to match current implementation (`Chapter 12`, `Chapter 16`).
+
+### Test baseline (currently implemented)
+
+- `tests/admin-ui-render.test.js` (rendering baseline)
+- `tests/admin-ui-jsgui-controls.test.js` (interactive behavior + SSE lifecycle + DOM-pattern guard)
+- Included in `tests/test-runner.js` as `admin-ui-jsgui-controls.test.js`.
+
+---
+
+## Architectural Direction: Process as Resource
+
+## Decision
+
+Adopt **Process as a Resource type** and keep a **ProcessManager as a Resource** for orchestration.
+
+### Why this is the right direction
+
+1. Uniform control plane: everything is a resource with lifecycle and telemetry.
+2. Better admin UX: one table model for states/health/actions.
+3. Extensible orchestration: manager policies can evolve independently.
+4. Natural language remains intact: teams still talk about “processes,” while implementation is resource-based.
+
+### Conceptual model
+
+- `Process_Resource` extends `Resource`.
+- `Process_Manager_Resource` extends `Resource` and manages a set of `Process_Resource` instances.
+- Resource pool remains the system registry and event bus anchor.
+
+---
+
+## Target Capabilities (Next Phase)
+
+The next phase should improve the admin interface as a **task/process coordinator** while keeping risk low.
+
+### Read-side capabilities (implement first)
+
+1. Process inventory and state overview.
+2. Process detail panel (identity, runtime, state timeline).
+3. Process manager summary (counts, policy settings, queue pressure if available).
+4. Event stream correlation for process state transitions.
+
+### Write-side capabilities (planned later)
+
+1. Start/stop/restart process operations.
+2. Desired-state reconciliation through manager policy.
+3. Controlled write actions guarded by `admin_write` + CSRF + audit logs.
+
+---
+
+## Data Contract Proposal (Generic)
+
+These contracts should be introduced incrementally and versioned under `/api/admin/v1/...`.
+
+### `GET /api/admin/v1/processes`
+
+Returns process-like resources in normalized shape. V1 returns all items (no pagination). If pagination is needed later, add `?limit=N&offset=M` query parameters — but defer until there's evidence of large inventories.
+
+**Process state enum** (strict at adapter level):
+`starting` | `running` | `degraded` | `crashed` | `stopped` | `unknown`
+
+Resources whose state doesn't map cleanly to one of these values should be normalized to `unknown`.
+
+```json
+{
+  "ok": true,
+  "items": [
+    {
+      "name": "worker-a",
+      "type": "Process_Resource",
+      "manager": "default_process_manager",
+      "desired_state": "running",
+      "observed_state": "running",
+      "health": "healthy",
+      "pid": 12345,
+      "uptime_seconds": 842,
+      "restart_count": 0,
+      "last_error": null,
+      "updated_at": 1739590000000
+    }
+  ]
+}
+```
+
+### `GET /api/admin/v1/processes/:name`
+
+Returns detailed process metadata and recent events.
+
+### `GET /api/admin/v1/process-managers`
+
+Returns manager-level summaries:
+
+- total managed processes
+- running/degraded/crashed counts
+- policy configuration snapshot
+
+### SSE event names (existing + proposed)
+
+- existing: `resource_state_change`, `crashed`, `recovered`, `heartbeat`
+- proposed normalized process events:
+  - `process_state_changed`
+  - `process_unhealthy`
+  - `process_exited`
+  - `process_restarted`
+
+---
+
+## UI Roadmap (Admin v1.x)
+
+### UI-1: Processes section (read-only)
+
+Add a dedicated sidebar item and panel:
+
+- columns: Name, Manager, Desired, Observed, Health, Uptime, Restarts
+- sorting by state and uptime
+- status color badges
+- empty/error/loading states
+
+**Adaptive composition** (ref: Device-Adaptive Composition book, Chapter 2 — four-layer model)
+
+- **Desktop**: dense table layout with all columns visible.
+- **Tablet**: table with horizontal scroll or column prioritization (hide Restarts, Manager).
+- **Phone**: card list — one card per process showing Name, Observed State badge, and Health. Tap to navigate to detail.
+- Use `[data-layout-mode]` attribute selectors, not raw `@media` queries (Chapter 4).
+- Touch targets for state badges and row actions must meet 44×44 px minimum.
+
+**Acceptance criteria**
+
+- panel loads with auth-protected API
+- handles empty inventories gracefully
+- updates key state badges from SSE without full reload
+- SSE auto-reconnects on stream drop with exponential backoff (1s → 2s → 4s → max 30s)
+- renders correctly across the viewport test matrix: phone portrait (390×844), tablet landscape (1024×768), desktop wide (1920×1080)
+
+### UI-2: Process detail drawer/panel (read-only)
+
+Selecting a process shows:
+
+- identity + manager
+- desired vs observed state
+- runtime metadata
+- recent event timeline
+
+**Adaptive composition** (ref: Device-Adaptive Composition book, Chapter 2)
+
+- **Desktop**: side drawer (right panel, ~400px) overlays or splits alongside the process list.
+- **Tablet**: drawer pushes list content or opens as a slide-over.
+- **Phone**: full-screen panel with back-navigation to the process list.
+- Use JS composition (`compose_adaptive()`) for the discrete phone → drawer switch (Chapter 6).
+
+**Acceptance criteria**
+
+- all values match API payload
+- timeline updates while panel is open via SSE (auto-reconnect on drop)
+- no write actions exposed yet
+- drawer/panel transition works across all three layout modes
+
+### UI-3: Process manager summary panel (read-only)
+
+Displays manager-level health and policy snapshot.
+
+**Adaptive composition** (ref: Device-Adaptive Composition book, Chapter 2)
+
+- **Desktop/Tablet**: stat cards in a responsive grid (like Dashboard).
+- **Phone**: single-column stacked cards.
+- Use CSS-only continuous adaptation (flexbox wrap) — no JS composition switch needed.
+
+**Acceptance criteria**
+
+- supports multiple managers
+- summarizes counts correctly
+- includes "last updated" timestamp and stale-data indicator
+- cards reflow correctly at phone viewport width
+
+---
+
+## Backend Roadmap (Process/Resource layer)
+
+### BE-1: Normalize process resource shape
+
+Add utility mapping in admin adapter to produce a stable process DTO from heterogeneous resources.
+
+**Acceptance criteria**
+
+- missing fields fall back to explicit defaults:
+  - `health` → `'unknown'`
+  - `desired_state` → `null`
+  - `observed_state` → `'unknown'`
+  - `restart_count` → `0`
+  - `uptime_seconds` → `null`
+  - `last_error` → `null`
+  - `pid` → `null`
+  - `manager` → `null`
+  - `updated_at` → `Date.now()` (timestamp of normalization)
+- no access to hazardous getters that can throw side effects
+
+### BE-2: Add process inventory endpoints
+
+Implement read-only endpoints listed above under `admin_read` guard.
+
+**Acceptance criteria**
+
+- unauthenticated => 401
+- authenticated without role => 403
+- authenticated with `admin_read` => 200
+
+### BE-3: Event normalization bridge
+
+Map generic pool events to process-centric event names when resource type indicates process semantics.
+
+**Event mapping table**
+
+| Pool event | Condition | Normalized event |
+|---|---|---|
+| `resource_state_change` | `resource.type === 'Process_Resource'` | `process_state_changed` |
+| `crashed` | resource is process type | `process_exited` (with `exit_reason: 'crash'`) |
+| `recovered` | resource is process type | `process_restarted` |
+| `resource_state_change` where `new_state` is degraded | resource is process type | `process_unhealthy` |
+
+Normalized event payloads should include: `{ name, manager, previous_state, current_state, timestamp }`.
+
+**Acceptance criteria**
+
+- existing events remain available (normalized events are additive, not replacements)
+- normalized events are documented in this chapter's data contract section
+- unmapped resource types pass through without transformation
+
+---
+
+## Security and Authorization Next Steps
+
+### S-1: Role policy enforcement consistency
+
+Ensure every new process endpoint is explicitly guarded (`admin_read` for read endpoints now).
+
+### S-2: Write action gate (future)
+
+Before adding any mutation endpoint:
+
+1. require `admin_write`
+2. require CSRF protection for browser-initiated writes
+3. emit audit events (actor, action, target, result)
+
+---
+
+## Testing Roadmap
+
+### T-1: API auth contract tests
+
+- unauthorized requests return 401
+- role violations return 403
+- valid read role returns 200
+
+### T-2: UI smoke tests for process panels
+
+- login flow
+- process panel renders
+- SSE updates state badge in place
+
+### T-3: Regression checks
+
+- existing status/resources/routes views still pass
+- no route collisions with static assets
+- startup still succeeds without process resources present
+
+---
+
+## Implementation Order (Recommended)
+
+1. **BE-1** process DTO normalization helper
+2. **BE-2** `/processes` and `/process-managers` read endpoints
+3. **UI-1** process list panel
+4. **UI-2** process detail panel
+5. **BE-3 + UI-3** normalized events + manager summary
+6. tests for auth and rendering regression
+
+This order keeps risk low by landing read-side observability first.
+
+---
+
+## Open Questions for Reviewer Agent
+
+1. ~~Should process endpoints be nested under `/api/admin/v1/resources/processes` or top-level `/api/admin/v1/processes`?~~ **Resolved: top-level.** The process endpoint is a first-class concept, not a filtered view of a generic resource browser that doesn't exist yet.
+2. Should timeline events be pulled (`GET`) only, or include in-band SSE replay snapshots?
+3. What minimum manager policy fields should be exposed in v1 read-only summary?
+4. ~~Should process state enums be strict at adapter level now?~~ **Resolved: yes.** Strict enum (`starting | running | degraded | crashed | stopped | unknown`) at the adapter layer. Costs nothing, prevents downstream string-comparison drift. `unknown` covers unmapped resources.
+
+---
+
+## Definition of Done for Next Milestone
+
+The next milestone is complete when:
+
+1. Admin UI has a working **Processes** read-only section.
+2. Process inventory and manager summary endpoints exist and are documented.
+3. Role-guarded access is verified (`401/403/200` behavior).
+4. SSE-driven process state updates appear in UI.
+5. No workload-specific logic is introduced into this repo.
+
+---
+
+## Notes for Contributors
+
+- Keep naming conventions aligned with project rules (`snake_case` for functions/variables, PascalCase classes).
+- Keep process/resource abstractions generic.
+- Avoid introducing write actions until CSRF + audit plan is implemented.

package/docs/books/creating-a-new-admin-ui/README.md

@@ -0,0 +1,68 @@
+# Creating a New Admin UI
+
+**A comprehensive guide to building the jsgui3-server Administration Interface**
+
+---
+
+## About This Book
+
+This book documents the design, architecture, and implementation of a rich administration interface for jsgui3-server. The admin UI is built entirely with jsgui3 controls — dogfooding the framework to create a production-quality dashboard that provides real-time visibility into server internals, process health, resource pools, routing tables, build outputs, and configuration.
+
+The admin UI lives at `admin-ui/v1/` and is served automatically at the `/admin/v1` route of any running jsgui3-server instance.
+
+## Design Reference
+
+The visual design is inspired by a Windows Aero-era aesthetic — glass-effect title bars, warm parchment content areas, subtle gradients, and grouped panels with classic separators. The SVG design reference (`server-admin-interface-aero.svg`) provides the canonical visual target.
+
+## Chapters
+
+| # | Chapter | Description |
+|---|---------|-------------|
+| 01 | [Introduction & Vision](01-introduction-and-vision.md) | Goals, audience, design philosophy, and what the admin UI aims to achieve |
+| 02 | [Architecture & Data Flow](02-architecture-and-data-flow.md) | Client-server architecture, data paths, isomorphic rendering, and component hierarchy |
+| 03 | [Server Introspection — What Data Is Available](03-server-introspection.md) | Audit of every data source in jsgui3-server that the admin UI can surface |
+| 04 | [The Admin Module Adapter Layer](04-admin-module-adapter-layer.md) | API endpoints, telemetry collection, and the bridge between server internals and the UI |
+| 05 | [Domain Controls — Stat Cards & Gauges](05-domain-controls-stat-cards-and-gauges.md) | Status indicator cards, numeric displays, progress gauges, and sparkline charts |
+| 06 | [Domain Controls — Process Manager Panel](06-domain-controls-process-manager.md) | Process tree, fork visualization, PID/memory display, start/stop/restart actions |
+| 07 | [Domain Controls — Resource Pool Inspector](07-domain-controls-resource-pool-inspector.md) | Resource table, type badges, health indicators, memory breakdown |
+| 08 | [Domain Controls — Route Table & API Explorer](08-domain-controls-route-table-and-api-explorer.md) | HTTP method badges, route listing, handler types, interactive API testing |
+| 09 | [Domain Controls — Log Viewer & Activity Feed](09-domain-controls-log-viewer-and-activity-feed.md) | Timestamped log stream, severity filtering, auto-scroll, search |
+| 10 | [Domain Controls — Build Status & Bundle Inspector](10-domain-controls-build-status-and-bundle-inspector.md) | Bundle size cards, module count, build timing, source map status |
+| 11 | [Domain Controls — Configuration Panel](11-domain-controls-configuration-panel.md) | Read-only and editable config fields, port/debug/entry-point display |
+| 12 | [The Admin Shell — Layout, Sidebar, & Navigation](12-admin-shell-layout-sidebar-navigation.md) | Window chrome, sidebar navigation, toolbar, status bar, content area routing |
+| 13 | [Integrating with the Server — Telemetry Endpoints](13-telemetry-integration.md) | Modifying `server.js` and `Admin_Module` to expose new telemetry APIs |
+| 14 | [Real-Time Updates — SSE & Observable Integration](14-realtime-sse-observable-integration.md) | Connecting the UI to `HTTP_SSE_Publisher` and `HTTP_Observable_Publisher` for live data |
+| 15 | [Styling & Theming — The Aero-Inspired Design System](15-styling-theming-aero-design-system.md) | Token definitions, gradient recipes, glass effects, typography, and density |
+| 16 | [Testing & Quality Assurance](16-testing-and-quality-assurance.md) | Unit tests, integration tests, viewport matrix testing, and acceptance criteria |
+| 17 | [Next Steps — Process/Resource Roadmap](17-next-steps-process-resource-roadmap.md) | Handoff-grade implementation plan for process-centric admin capabilities, auth boundaries, and test gates |
+
+## Key Principles
+
+1. **Dogfooding** — The admin UI is built entirely with jsgui3 controls. Every pattern used here validates the framework.
+2. **Zero Configuration** — The admin UI is available at `/admin/v1` on every jsgui3-server instance with no extra setup.
+3. **Read Before Write** — The admin UI primarily reads and displays server state. Write operations (restart, config change) are guarded and opt-in.
+4. **Incremental Delivery** — Each domain control is independently functional. The shell composes them, but each can be developed and tested in isolation.
+5. **Real Data Only** — No mock data in production. Every number shown comes from actual server telemetry.
+
+## Prerequisites
+
+- Familiarity with jsgui3-html control lifecycle (`compose` → `activate`)
+- Understanding of jsgui3-server's publisher and resource systems
+- Node.js and basic HTTP/SSE concepts
+
+## Directory Structure
+
+```
+admin-ui/
+├── v1/
+│   ├── client.js              # Client-side entry point (registers Admin_Shell)
+│   ├── server.js              # Admin module (adapter layer + auth + telemetry)
+│   ├── admin_auth_service.js  # Session auth service
+│   ├── admin_user_store.js    # In-memory user store
+│   ├── controls/
+│   │   ├── admin_shell.js     # Main shell with sidebar + content
+│   │   ├── stat_card.js       # Stat card control
+│   │   └── group_box.js       # Reusable grouped panel container
+│   └── utils/
+│       └── formatters.js      # Shared formatting helpers
+```

package/docs/books/device-adaptive-composition/01-platform-feature-audit.md

@@ -0,0 +1,177 @@
+# Chapter 1 — Platform Feature Audit
+
+Before proposing new infrastructure, we need to understand what jsgui3 already provides and where the real gaps are. This chapter walks through the existing capabilities, illustrates them with actual platform code, and identifies what's missing.
+
+## Existing Strengths
+
+### 1) Isomorphic Composition Model
+
+Controls in jsgui3 are composed on the server and activated on the client. The constructor builds the DOM tree; the `activate()` method wires up event listeners. This gives us a crucial advantage for adaptive UI: we can make **structural composition decisions** at construction time, not just CSS overrides.
+
+For responsive design, this means a control can choose entirely different internal compositions based on environment state — a sidebar can be composed as a `Drawer` on mobile and as a static panel on desktop, using the same business logic, without CSS gymnastics.
+
+### 2) Layout Primitives with Practical APIs
+
+The layout primitives in `controls/organised/1-standard/6-layout/` provide building blocks for most responsive patterns:
+
+**Stack** — flexbox container with direction, gap, alignment, wrapping:
+
+```js
+const nav = new Stack({
+    context,
+    direction: 'row',    // or 'column'
+    gap: 8,
+    align: 'center',
+    justify: 'between',
+    wrap: true            // allows items to flow to next line
+});
+```
+
+Stack supports runtime property changes (`set_direction()`, `set_gap()`, etc.), which means a control can switch from horizontal to vertical layout without rebuilding its DOM tree.
+
+**Cluster** — wrapped inline groups for tags, chips, buttons:
+
+```js
+const chips = new Cluster({ context, gap: 6, align: 'center' });
+```
+
+**Center** — centering with max-width constraint:
+
+```js
+const content = new Center({ context, max: 960 });
+```
+
+**Grid_Gap** — CSS Grid with column/row templates and gap.
+
+**Split_Pane** — resizable dual-panel layout:
+
+```js
+const editor = new Split_Pane({
+    context,
+    orientation: 'horizontal',
+    initial_ratio: 0.3
+});
+```
+
+**Drawer** — the most responsive-aware primitive today. It already has a `breakpoint` property and an `overlay_mode` that switches between overlay and docked behavior:
+
+```js
+const nav_drawer = new Drawer({
+    context,
+    position: 'left',
+    breakpoint: 960,      // below this width: overlay mode
+    overlay_mode: true,
+    content: nav_panel
+});
+```
+
+In `activate()`, the Drawer listens for `window.resize` and calls `update_responsive_state()`:
+
+```js
+update_responsive_state() {
+    if (typeof window === 'undefined') return;
+    const is_overlay = this.overlay_mode && window.innerWidth < this.breakpoint;
+    if (is_overlay) {
+        this.remove_class('drawer-docked');
+        this.add_class('drawer-overlay-mode');
+    } else {
+        this.add_class('drawer-docked');
+        this.remove_class('drawer-overlay-mode');
+    }
+}
+```
+
+This is the closest thing to adaptive composition behavior in the current platform. It proves the pattern works; the question is how to generalize it.
+
+### 3) Design Token Infrastructure
+
+The token system in `css/jsgui-tokens.css` provides a comprehensive set of CSS custom properties with the `--j-` prefix:
+
+- **Spacing scale** (8px base): `--j-space-1` through `--j-space-8`
+- **Typography scale**: `--j-text-xs` through `--j-text-xl`
+- **Radius, shadow, motion**: `--j-radius-sm` through `--j-radius-full`, `--j-shadow-sm` through `--j-shadow-xl`
+- **Color system**: semantic foreground/background tokens with full dark-mode overrides
+- **Motion tokens**: `--j-duration-fast`, `--j-duration-normal`, `--j-duration-slow` with automatic zeroing under `prefers-reduced-motion`
+
+The admin theme bridge (`--admin-*` tokens) provides an additional layer used by data-oriented controls like tables, forms, and editors.
+
+Dark mode is handled via `[data-theme="dark"]` or `.jsgui-dark-mode` selectors, and the `Admin_Theme` presets map named themes to token overrides. This gives a solid foundation for device-adaptive theming — the same token-override pattern can drive density and layout-mode styling.
+
+### 4) MVVM Foundations
+
+`Data_Model_View_Model_Control` and `control_model_factory.js` provide explicit separation between:
+
+- **`data.model`** — domain state (business data)
+- **`view.data.model`** — presentation state (what the view needs to render)
+- **`view.model`** — view-instance state (UI interaction state)
+- **`view.ui`** — UI structure metadata
+
+The factory function `ensure_control_models()` sets up this stack automatically:
+
+```js
+ensure_control_models(this, spec);
+// After this call:
+//   this.data.model       → Data_Object (domain state)
+//   this.view.data.model  → Data_Object (presentation state)
+//   this.view.ui          → Control_View_UI (structure)
+```
+
+This separation is essential for adaptive UI. Device-specific state (layout mode, sidebar visibility, density) belongs in the view model, not the data model. The infrastructure already exists; we just need conventions for using it with environment state.
+
+### 5) Interaction and Accessibility Utilities
+
+`control_mixins/keyboard_navigation.js` provides orientation-aware keyboard handling — arrow keys navigate differently in vertical vs horizontal contexts, which is directly relevant when layouts change orientation across breakpoints.
+
+The guidance in `docs/accessibility_and_semantics.md` establishes patterns for ARIA roles, focus management, and screen reader support. The existing `prefers-reduced-motion` reset in the token system ensures motion tokens go to `0ms` when the user requests reduced motion.
+
+## Current Gaps
+
+### 1) No Unified Responsive Policy Layer
+
+Responsive behavior is currently ad-hoc. The Drawer has its own `breakpoint` property and resize listener. Other controls rely on whatever `@media` queries the app developer writes. There is no shared service that answers the question "what layout mode are we in?" and notifies controls when it changes.
+
+This means every control that needs responsive behavior reinvents its own detection logic, and controls can't coordinate — a sidebar might think it's in "desktop" mode while a toolbar uses a different breakpoint to decide it's in "tablet" mode.
+
+### 2) No Declarative Viewport/Container Model
+
+The platform doesn't currently expose semantic mode labels. A developer can read `window.innerWidth`, but there's no first-class concept of:
+
+- **Layout mode**: phone / tablet / desktop
+- **Density mode**: compact / cozy / comfortable
+- **Interaction mode**: touch / pointer / hybrid
+- **Motion mode**: normal / reduced
+
+These concepts exist implicitly — Drawer's breakpoint check is really a layout-mode check — but they aren't formalized into a shared vocabulary.
+
+### 3) Display-Mode System: Architecturally Rich but Not Productionized
+
+`control_mixins/display.js` contains a sophisticated class hierarchy (`Ctrl_Display`, `Ctrl_Display_Modes`, `Ctrl_Display_Mode_Category`, `Ctrl_Display_Modes_Categories`) designed to let controls express multiple display modes with categories like size, layout, colors, and interactivity. The architecture envisions controls that can render as icons, thumbnails, cards, or full panels depending on context.
+
+However, this system is still in design-exploration phase. The classes exist and work, but no production controls use them as their display-mode API. The code contains extensive design notes like:
+
+> "Want it to be easy to call on and use display mode functionality."
+> "May want nice CSS transitions between display modes."
+
+This is valuable forward thinking that aligns well with adaptive composition. The question is whether to productionize this existing architecture or build the adaptive system alongside it and unify later.
+
+### 4) Responsive Testing Is Not Standardized
+
+The Playwright test suite validates rich interactivity across 14+ test suites, but all tests run at a single viewport size. There is no systematic viewport-matrix testing (run the same assertions at phone, tablet, and desktop sizes) and no structural assertions like "no horizontal overflow at 390px width."
+
+## Summary
+
+| Area | Status | Key Asset |
+|------|--------|-----------|
+| Isomorphic composition | Strong | Constructor + activate() split |
+| Layout primitives | Strong | Stack, Drawer, Split_Pane, Grid_Gap |
+| Token/theme system | Strong | `--j-*` and `--admin-*` tokens, dark mode |
+| MVVM model separation | Strong | data.model, view.data.model, view.ui |
+| Accessibility | Adequate | keyboard_navigation, reduced-motion |
+| Responsive policy | Gap | No shared environment service |
+| Declarative adaptive modes | Gap | No layout_mode / density_mode vocabulary |
+| Display-mode API | In design | Classes exist, not productionized |
+| Viewport-matrix testing | Gap | No multi-viewport Playwright runner |
+
+The platform is well-positioned. The composition model, token system, and model separation give us the right foundations. What's needed is a thin coordination layer — an environment service and adaptive composition helpers — that turns ad-hoc responsive code into a consistent, testable pattern.
+
+**Next:** [Chapter 2](02-responsive-composition-model.md) introduces the four-layer composition model that organizes adaptive decisions.