jsgui3-server 0.0.148 → 0.0.150

package/docs/books/device-adaptive-composition/02-responsive-composition-model.md

@@ -0,0 +1,187 @@
+# Chapter 2 — Responsive Composition Model
+
+## The Problem
+
+Consider a typical admin dashboard built on jsgui3. On desktop, it shows a navigation sidebar, a main content area, and a property inspector panel — three columns. On tablet portrait, the property inspector should collapse to a slide-over panel. On phone, the sidebar should become a hamburger-triggered drawer and the inspector should become a full-screen modal.
+
+The naive approach is to build one big layout and write CSS media queries to hide/show regions. But this creates problems:
+
+1. **All three layouts are in the DOM simultaneously**, even when invisible — wasting memory and causing accessibility confusion (screen readers find hidden elements).
+2. **Business logic couples to layout** — event handlers reference elements that may be hidden, requiring defensive checks everywhere.
+3. **Controls can't adapt their own internal structure** — a data table might want to show 2 columns on phone and 8 on desktop, but CSS can only hide columns, not restructure the control.
+
+jsgui3's compositional model offers a better path: compose different control trees for different environments, sharing the same domain data.
+
+## Design Objective
+
+**High-level app code should declare intent, not breakpoint math.**
+
+An app developer should write something like *"use a three-column shell on desktop, two columns on tablet, single column with drawers on phone"* and have the platform resolve the details. The developer should not be manually checking `window.innerWidth` in fifteen places.
+
+## The Four-Layer Composition Model
+
+Adaptive composition in jsgui3 separates concerns into four layers. Each layer has a clear responsibility and communicates with adjacent layers through well-defined contracts.
+
+```
+┌─────────────────────────────────────────────┐
+│  Layer A: Domain Composition                │
+│  (entities, actions, permissions, workflow)  │
+│  ─── completely device-agnostic ───         │
+├─────────────────────────────────────────────┤
+│  Layer B: View Composition                  │
+│  (regions, component hierarchy, adaptive    │
+│   intent declarations)                      │
+├─────────────────────────────────────────────┤
+│  Layer C: Adaptive Resolution               │
+│  (environment service resolves intent →     │
+│   concrete mode, density, interaction)      │
+├─────────────────────────────────────────────┤
+│  Layer D: Concrete Render                   │
+│  (resolved CSS classes, DOM attributes,     │
+│   control params, token values)             │
+└─────────────────────────────────────────────┘
+```
+
+### Layer A: Domain Composition
+
+This is the business logic layer. It defines what data exists, what actions are available, and what workflows the user follows. It should have **zero awareness of screen size or device type**.
+
+Examples of Layer A concerns:
+- "The user has a list of projects"
+- "Each project has a name, status, and due date"
+- "The user can archive a project"
+
+In jsgui3, Layer A lives in `data.model` — the Data_Object instances managed by `ensure_control_models()`. Whether the app runs on a phone or a 4K monitor, the domain model is identical.
+
+### Layer B: View Composition
+
+This layer defines the UI structure: what regions exist, what controls they contain, and how they relate to each other. Critically, Layer B can express **adaptive intent** without committing to specific breakpoints.
+
+Examples of Layer B declarations:
+- "The app has a navigation region, a content region, and a tools region"
+- "The navigation region can collapse to a drawer on narrow screens"
+- "The tools region is optional and can be toggled"
+
+In jsgui3, Layer B lives in the constructor's composition logic — the `compose_ui()` method that builds the control tree. The key design choice is that Layer B expresses *what should adapt* without specifying *when*.
+
+### Layer C: Adaptive Resolution
+
+This is the platform layer that answers the question: "given the current environment, how should composition intent be resolved?" It observes:
+
+- Viewport width and height
+- Orientation (portrait/landscape/square)
+- Input modality (touch/pointer/hybrid)
+- User preferences (reduced motion, contrast, density preference)
+
+And produces a normalized environment contract:
+
+```js
+context.view_environment = {
+    viewport: { width: 768, height: 1024, orientation: 'portrait' },
+    layout_mode: 'tablet',     // 'phone' | 'tablet' | 'desktop'
+    density_mode: 'cozy',      // 'compact' | 'cozy' | 'comfortable'
+    interaction_mode: 'touch', // 'touch' | 'pointer' | 'hybrid'
+    motion_mode: 'normal'      // 'normal' | 'reduced'
+}
+```
+
+This contract is observable — controls and view models can listen for changes and recompose when the environment shifts (for instance, when a browser window is resized across a breakpoint boundary, or when a tablet is rotated).
+
+### Layer D: Concrete Render
+
+The resolved environment drives concrete rendering decisions: CSS classes on the root element (`data-layout-mode="tablet"`), specific token overrides for the density mode, and resolved control parameters.
+
+At this layer, everything is deterministic. Given environment state X, the output is always CSS class set Y and token values Z. This makes testing straightforward — you can assert on Layer D output without needing a real browser.
+
+## How the Layers Interact
+
+Here's the flow for a realistic scenario — a dashboard app loading on a tablet in portrait:
+
+1. **Layer A** is set up: the data model contains projects, user preferences, etc.
+2. **Layer B** composes the shell: nav region, content region, tools region. The nav region is marked as "collapsible."
+3. **Layer C** reads the viewport (768×1024), determines `layout_mode: 'tablet'`, `interaction_mode: 'touch'`.
+4. **Layer D** applies: `data-layout-mode="tablet"` on root, nav region renders as a slide-over panel (not inline sidebar), touch density tokens are applied.
+5. The user rotates to landscape (1024×768).
+6. **Layer C** detects the change, updates to `layout_mode: 'desktop'` (1024px exceeds the tablet threshold).
+7. **Layer B** recomposes: nav region switches from slide-over to inline sidebar.
+8. **Layer D** updates: root attribute changes, CSS transitions the layout.
+
+## SSR Considerations
+
+On the server, there is no viewport. Layer C needs a default. Two strategies:
+
+1. **Desktop-first SSR**: Compose for desktop, let the client refine on activation. This is the simplest approach and avoids layout shift on most users (majority of admin/dashboard users are desktop).
+
+2. **Hint-based SSR**: Pass environment hints through the request (User-Agent parsing, explicit query param, or stored preference). The server composes for the hinted mode. The client validates and corrects if needed.
+
+For most jsgui3 applications, desktop-first SSR is the right default. Mobile refinement happens in `activate()` and is fast because jsgui3's activation is already designed for incremental DOM updates.
+
+## Why CSS-Only Approaches Fall Short
+
+Pure CSS media queries can handle styling changes (font sizes, padding, hiding elements), but they cannot:
+
+- **Restructure the control tree** — replace a sidebar with a tabbed panel
+- **Change control parameters** — switch a table from 8 columns to 2
+- **Coordinate across components** — ensure nav, content, and tools all agree on the same mode
+- **Drive model updates** — notify the view model that the layout changed so other logic can respond
+
+CSS is excellent for Layer D concerns (visual polish, transitions, token overrides). But Layers B and C require JavaScript-level composition decisions, which is exactly what jsgui3's constructor + activate pattern enables.
+
+This doesn't mean we should ignore CSS entirely. The ideal approach is:
+
+- **CSS handles continuous adaptation** — fluid typography, flexible gaps, wrapping
+- **JS handles discrete adaptation** — structural changes at mode boundaries
+
+## Example: Before and After
+
+### Before (ad-hoc responsive code):
+
+```js
+compose_ui(context) {
+    // Developer manually checks width, duplicates logic
+    if (typeof window !== 'undefined' && window.innerWidth < 768) {
+        this.nav = new Drawer({ context, position: 'left' });
+        this.content = new Stack({ context, direction: 'column' });
+        // phone layout...
+    } else if (typeof window !== 'undefined' && window.innerWidth < 1024) {
+        this.nav = new Stack({ context, direction: 'column' });
+        this.content = new Stack({ context, direction: 'column' });
+        // tablet layout...
+    } else {
+        this.nav = new Stack({ context, direction: 'column' });
+        this.tools = new Stack({ context, direction: 'column' });
+        this.content = new Stack({ context, direction: 'column' });
+        // desktop layout...
+    }
+}
+```
+
+Problems: breakpoint values are hardcoded, no coordination with other controls, no observable state, no SSR support, no recomposition on resize.
+
+### After (with adaptive composition):
+
+```js
+compose_ui(context) {
+    const env = context.view_environment;
+
+    compose_adaptive(this, env, {
+        phone:   () => this.compose_phone_shell(),
+        tablet:  () => this.compose_tablet_shell(),
+        desktop: () => this.compose_desktop_shell()
+    });
+}
+```
+
+The `compose_adaptive` helper reads `env.layout_mode`, calls the right branch, and registers a listener so the shell recomposes if the mode changes. The breakpoint thresholds are defined once in the environment service, not scattered across app code.
+
+Each `compose_*_shell()` method shares the same domain model (Layer A) but builds a different control tree (Layer B). The developer writes three short, focused composition functions instead of one tangled conditional.
+
+## Key Design Principles
+
+1. **Domain state never knows about devices.** If you're putting `layout_mode` in your data model, something is wrong.
+2. **Composition intent is separate from resolution.** A region declared as "collapsible" doesn't decide when to collapse — the environment service does.
+3. **Continuous CSS, discrete JS.** Fluid sizing stays in CSS. Structural reorganization happens in constructors.
+4. **Observable, not polled.** The environment service emits change events. Controls don't poll `window.innerWidth`.
+5. **SSR-safe defaults.** Everything works without a viewport. Client activation refines.
+
+**Next:** [Chapter 3](03-data-model-vs-view-model.md) explains how the MVVM model separation keeps adaptive state clean and testable.

package/docs/books/device-adaptive-composition/03-data-model-vs-view-model.md

@@ -0,0 +1,231 @@
+# Chapter 3 — Data Model vs View Model in Adaptive UI
+
+## Why This Matters
+
+The most common mistake in responsive UI architecture is mixing device-specific state into business data. When a developer stores `sidebar_width: 280` next to `project_name: "Alpha"`, two bad things happen:
+
+1. **Serialization pollution.** Save the model to a database and you're persisting pixel values that are meaningless on a different device. Restore it on a phone and a 280px sidebar obscures everything.
+
+2. **Fragile coupling.** Business logic starts depending on layout state. A function that calculates project metrics now has to guard against `undefined` view properties. Tests for business rules require mocking viewport dimensions.
+
+jsgui3's MVVM architecture already provides the right separation. This chapter explains how to use it correctly for adaptive UI, ensuring device-specific decisions never contaminate domain data.
+
+## The Three Model Layers in jsgui3
+
+The `ensure_control_models()` factory creates a stack of model objects on every control:
+
+```
+┌──────────────────────────────────┐
+│  this.data.model                 │  ← Domain state
+│  (Data_Object from lang-tools)   │     "What does the business care about?"
+├──────────────────────────────────┤
+│  this.view.data.model            │  ← Presentation state
+│  (Data_Object)                   │     "What does the view need to render?"
+├──────────────────────────────────┤
+│  this.view.model                 │  ← View-instance state
+│  (Data_Object)                   │     "What is the current UI interaction state?"
+├──────────────────────────────────┤
+│  this.view.ui                    │  ← UI structure metadata
+│  (Control_View_UI)               │     "What controls exist in this view?"
+└──────────────────────────────────┘
+```
+
+Each layer serves a different purpose. Getting data into the right layer is the key to clean adaptive architecture.
+
+## What Goes Where
+
+### `data.model` — Domain State
+
+This is the source of truth for business data. It should be serializable, restorable, and completely ignorant of how it's displayed.
+
+**Belongs here:**
+- `selected_project_id: 'proj-42'`
+- `user_name: 'Alice'`
+- `filter_active: true`
+- `sort_field: 'due_date'`
+- `saved_theme_preference: 'vs-dark'`
+
+**Does NOT belong here:**
+- `sidebar_open: true` (that's a view concern)
+- `viewport_width: 768` (ephemeral device state)
+- `panel_collapsed: false` (UI interaction state)
+- `animation_in_progress: true` (transient rendering state)
+
+The litmus test: *"Would this value make sense if I serialized it to a database and loaded it on a completely different device?"* If yes, it's domain state. If no, it belongs in a view model.
+
+### `view.data.model` — Presentation State
+
+This is derived data that the view needs to render but that doesn't belong in the domain model. It's often computed from the combination of domain state and environment state.
+
+**Belongs here:**
+- `layout_mode: 'tablet'` (resolved from viewport)
+- `should_show_sidebar_inline: true` (derived from layout_mode)
+- `visible_column_count: 4` (derived from available width)
+- `formatted_due_date: 'Feb 14, 2026'` (derived from data.model.due_date)
+- `density_mode: 'compact'` (resolved from interaction mode + user preference)
+
+This is where adaptive decisions materialize as concrete values that controls can bind to.
+
+### `view.model` — View-Instance State
+
+This captures the user's current interaction state within the UI. It's ephemeral — losing it on page reload is acceptable (or it can be persisted to localStorage if desired).
+
+**Belongs here:**
+- `sidebar_open: true`
+- `active_tab_index: 2`
+- `panel_collapsed: false`
+- `scroll_position: 340`
+- `hover_row_id: 'row-7'`
+
+### `view.ui` — UI Structure Metadata
+
+This is structural metadata about what controls exist in the current view. It's managed by the control framework, not typically by app developers.
+
+## A Worked Example
+
+Consider a project dashboard that shows a list of projects and a detail panel. Let's trace a scenario where the user is on a tablet and rotates from portrait to landscape.
+
+### The Models
+
+```js
+// Domain model — same regardless of device
+this.data.model = new Data_Object({
+    projects: [
+        { id: 'p1', name: 'Alpha', status: 'active', due: '2026-03-01' },
+        { id: 'p2', name: 'Beta',  status: 'draft',  due: '2026-04-15' }
+    ],
+    selected_project_id: 'p1',
+    filter_status: 'all'
+});
+
+// View data model — derived from domain + environment
+this.view.data.model = new Data_Object({
+    layout_mode: 'tablet',
+    visible_columns: ['name', 'status', 'due'],    // desktop would show more
+    should_show_detail_inline: false,                // tablet portrait: overlay
+    formatted_projects: [/* computed from domain */]
+});
+
+// View model — current interaction state
+this.view.model = new Data_Object({
+    detail_panel_open: true,
+    list_scroll_position: 0,
+    active_section: 'overview'
+});
+```
+
+### Portrait (768×1024): `layout_mode: 'tablet'`
+
+The environment service resolves `layout_mode: 'tablet'`. View composition responds:
+- `should_show_detail_inline: false` → detail panel is a slide-over
+- `visible_columns: ['name', 'status', 'due']` → 3 columns shown
+- User rotates the device...
+
+### Landscape (1024×768): `layout_mode: 'desktop'`
+
+The environment service detects the change. `layout_mode` updates to `'desktop'`. The view data model recomputes:
+- `should_show_detail_inline: true` → detail panel is now a side panel
+- `visible_columns: ['name', 'status', 'due', 'owner', 'priority']` → 5 columns
+
+**Crucially, nothing in `data.model` changed.** The selected project is still `'p1'`. The filter is still `'all'`. The domain is untouched. Only view-layer state responded to the environment change.
+
+## Using Bindings for Adaptive Derived State
+
+The `Data_Model_View_Model_Control` base class provides binding and computed property APIs that are ideal for deriving adaptive state:
+
+```js
+// In the control's constructor:
+ensure_control_models(this, spec);
+
+// Bind layout_mode changes to column visibility
+this.watch(this.view.data.model, 'layout_mode', (mode) => {
+    const columns = mode === 'phone'
+        ? ['name']
+        : mode === 'tablet'
+        ? ['name', 'status', 'due']
+        : ['name', 'status', 'due', 'owner', 'priority', 'created'];
+
+    this.view.data.model.set('visible_columns', columns);
+});
+
+// Computed property: should detail show inline?
+this.computed(this.view.data.model,
+    ['layout_mode'],
+    (mode) => mode === 'desktop',
+    { property_name: 'should_show_detail_inline' }
+);
+```
+
+When the environment service updates `layout_mode`, the watchers fire, derived state recomputes, and controls that bind to `visible_columns` or `should_show_detail_inline` update automatically. The reactive pipeline in lang-tools handles the propagation.
+
+## The Persistence Rule
+
+A simple rule for adaptive state and persistence:
+
+| Model Layer | Persist to DB? | Persist to localStorage? | Transfer across devices? |
+|-------------|----------------|--------------------------|--------------------------|
+| `data.model` | Yes | If needed | Yes — it's device-agnostic |
+| `view.data.model` | No | Rarely | No — it's derived from environment |
+| `view.model` | No | Optionally | No — it's per-session |
+
+When the showcase app persists theme preferences to localStorage, those preferences are domain-level choices (the user chose "vs-dark"). But the `layout_mode` that determines how the theme studio is displayed is view state — it shouldn't be persisted because it should always reflect the current device.
+
+## Integration with Low-Level Complexity
+
+The goal of this separation is to keep high-level app code simple. But the reactive binding infrastructure underneath is sophisticated — and that's fine. The complexity lives in the right place:
+
+- **lang-tools** provides `Data_Object` with change events, property watching, and computed properties
+- **ModelBinder** and **BindingManager** handle bi-directional syncing between model layers
+- **control_model_factory** auto-wires the model stack
+
+App developers don't need to understand how `BindingManager` resolves circular dependencies or how `Data_Object` batches change events. They need to know: *"put business data in data.model, put device-specific state in view.data.model, and use watchers to derive one from the other."*
+
+## Anti-Patterns to Avoid
+
+### 1. Domain model holding layout state
+
+```js
+// ❌ Bad: domain model knows about layout
+this.data.model.set('sidebar_visible', window.innerWidth > 960);
+```
+
+```js
+// ✅ Good: view model holds layout state
+this.view.data.model.set('sidebar_visible', env.layout_mode !== 'phone');
+```
+
+### 2. Controls reading window dimensions directly
+
+```js
+// ❌ Bad: every control checks the viewport independently
+if (window.innerWidth < 768) { /* phone layout */ }
+```
+
+```js
+// ✅ Good: controls read from the shared environment contract
+const mode = context.view_environment.layout_mode;
+```
+
+### 3. Persisting derived state
+
+```js
+// ❌ Bad: saving viewport-dependent state to the database
+save_to_server({ columns: this.view.data.model.get('visible_columns') });
+```
+
+```js
+// ✅ Good: saving only the user's preference, not the derived result
+save_to_server({ preferred_column_set: this.data.model.get('column_preference') });
+```
+
+## Summary
+
+The model separation already built into jsgui3 through `Data_Model_View_Model_Control` is the right foundation for adaptive UI. The key insight is that **adaptive state is view state, not domain state**. The view data model (`view.data.model`) is where layout mode, density, column visibility, and region configuration live. The domain model (`data.model`) remains pure, portable, and testable.
+
+This separation means you can:
+- Test business logic without mocking viewports
+- Switch devices without corrupting saved state
+- Add new adaptive behaviors without touching domain code
+- Serialize and restore cleanly across sessions and devices
+
+**Next:** [Chapter 4](04-styling-theme-breakpoints.md) covers how the token and theme system supports responsive density and mode-based styling.

package/docs/books/device-adaptive-composition/04-styling-theme-breakpoints.md

@@ -0,0 +1,234 @@
+# Chapter 4 — Styling, Themes, and Breakpoint Strategy
+
+## The Two Kinds of Responsiveness
+
+Responsive UI involves two fundamentally different kinds of adaptation:
+
+1. **Continuous adaptation** — sizes, spacing, and proportions that scale fluidly. A font might be 14px on desktop and 16px on mobile. Padding might shrink from 24px to 12px. These are gradients, not switches.
+
+2. **Discrete adaptation** — structural changes at specific boundaries. A sidebar becomes a drawer. A table becomes a card list. Three columns become one. These are switches, not gradients.
+
+CSS handles continuous adaptation well (fluid units, `clamp()`, flexible layouts). Discrete adaptation typically requires JavaScript composition decisions, as discussed in Chapter 2. But there's an important middle ground: **mode-qualified CSS** that uses data attributes set by the environment service.
+
+This chapter covers how jsgui3's token and theme system supports both kinds of adaptation.
+
+## Current Token Architecture
+
+The token system in `css/jsgui-tokens.css` provides two tiers:
+
+### Design tokens (`--j-*`)
+
+Foundation-level tokens for spacing, typography, radii, shadows, motion, and color:
+
+```css
+/* Spacing scale (8px base) */
+--j-space-1: 4px;    --j-space-2: 8px;    --j-space-3: 12px;
+--j-space-4: 16px;   --j-space-5: 24px;   --j-space-6: 32px;
+
+/* Typography scale */
+--j-text-xs: 0.75rem;   --j-text-sm: 0.875rem;   --j-text-base: 1rem;
+--j-text-lg: 1.125rem;  --j-text-xl: 1.5rem;
+
+/* Motion (zeroed under prefers-reduced-motion) */
+--j-duration-fast: 120ms;   --j-duration-normal: 200ms;   --j-duration-slow: 350ms;
+```
+
+### Component tokens (`--admin-*`)
+
+Higher-level tokens consumed by admin/data controls:
+
+```css
+--admin-font-size: 13px;
+--admin-row-height: 36px;
+--admin-cell-padding: 8px 12px;
+--admin-radius: 4px;
+```
+
+Both tiers include full dark-mode overrides via the `[data-theme="dark"]` selector.
+
+## Strategy 1: Mode Classes Over Scattered Breakpoints
+
+The traditional approach scatters `@media` queries across component stylesheets:
+
+```css
+/* ❌ Scattered: breakpoint values duplicated everywhere */
+@media (max-width: 768px) {
+    .project-list { flex-direction: column; }
+}
+@media (max-width: 768px) {
+    .tool-panel { display: none; }
+}
+@media (max-width: 768px) {
+    .nav-bar { font-size: 14px; }
+}
+```
+
+Problems: the value `768px` is repeated in dozens of files; there's no single source of truth; changing the breakpoint requires a global search-and-replace.
+
+The recommended approach uses **mode attributes** set by the environment service (Layer C):
+
+```html
+<body data-layout-mode="phone" data-density-mode="compact" data-interaction-mode="touch">
+```
+
+Component CSS then targets the mode, not the breakpoint:
+
+```css
+/* ✅ Mode-qualified: breakpoint logic lives in one place (the environment service) */
+[data-layout-mode="phone"] .project-list {
+    flex-direction: column;
+}
+[data-layout-mode="phone"] .tool-panel {
+    display: none;
+}
+[data-layout-mode="phone"] .nav-bar {
+    font-size: var(--j-text-sm);
+}
+```
+
+Benefits:
+- **Single source of truth** for breakpoint thresholds (the environment service)
+- **Testable** — set `data-layout-mode="phone"` on any element in a test and verify styles
+- **Composable** — combine mode, density, and interaction qualifiers: `[data-layout-mode="phone"][data-density-mode="compact"]`
+- **SSR-friendly** — the server can set mode attributes based on request hints
+
+This is the same pattern that dark mode already uses — `[data-theme="dark"]` overrides tokens. We're extending it to layout mode and density.
+
+## Strategy 2: Responsive Token Tiers
+
+Some styling changes are too pervasive to write as individual CSS rules. Font size, row height, padding, and spacing should adapt globally. The right approach is to override tokens at the root based on the active mode.
+
+### Proposed density token overrides
+
+```css
+/* Compact — information-dense, smaller touch targets, less whitespace */
+[data-density-mode="compact"] {
+    --j-space-2: 4px;
+    --j-space-3: 8px;
+    --j-space-4: 12px;
+    --j-space-5: 16px;
+    --admin-font-size: 12px;
+    --admin-row-height: 28px;
+    --admin-cell-padding: 4px 8px;
+}
+
+/* Comfortable — generous whitespace, larger touch targets */
+[data-density-mode="comfortable"] {
+    --j-space-2: 12px;
+    --j-space-3: 16px;
+    --j-space-4: 20px;
+    --j-space-5: 32px;
+    --admin-font-size: 15px;
+    --admin-row-height: 44px;
+    --admin-cell-padding: 12px 16px;
+}
+```
+
+No component CSS needs to change. Every control that uses `--j-space-*` or `--admin-row-height` automatically adapts. The token system does the work.
+
+### Why density and theme are orthogonal
+
+Theme (color identity: light, dark, vs-dark) and density (space economy: compact, cozy, comfortable) are independent axes. A user might want:
+
+- `vs-dark` theme + `compact` density (power user, dark IDE-like)
+- Light theme + `comfortable` density (presentation mode, accessibility)
+- `vs-dark` theme + `comfortable` density (dark mode on a touch tablet)
+
+Implementing them as separate data attributes ensures they compose freely:
+
+```html
+<body data-theme="vs-dark" data-density-mode="compact">
+```
+
+## Strategy 3: Theme Profiles
+
+The showcase app already persists theme state to localStorage. Extending this to include density and layout preferences creates a clean **theme profile** object:
+
+```js
+const profile = {
+    theme: 'vs-dark',
+    density: 'compact',
+    overrides: {
+        '--admin-font-size': '12px',
+        '--admin-radius': '2px'
+    }
+};
+```
+
+This profile object is:
+- **Serializable** — JSON-safe for localStorage, export/import, server storage
+- **Transferable** — share profiles between users or across projects
+- **Testable** — apply a profile in a test fixture and assert visual outcomes
+- **Composable** — merge a base profile with user overrides
+
+The existing showcase app persistence (`showcase_theme_state_v1` localStorage key) can evolve to store full profiles.
+
+## Strategy 4: Touch-Optimized Density
+
+Touch interaction requires larger hit targets (minimum 44×44px per WCAG guidelines, 48×48px recommended by Google Material). The density system should enforce this:
+
+```css
+[data-interaction-mode="touch"] {
+    --admin-row-height: max(var(--admin-row-height), 44px);
+    --j-space-2: max(var(--j-space-2), 8px);
+}
+
+[data-interaction-mode="touch"] button,
+[data-interaction-mode="touch"] [role="button"],
+[data-interaction-mode="touch"] a {
+    min-height: 44px;
+    min-width: 44px;
+}
+```
+
+This is applied as a CSS layer, so it works alongside any density setting — `compact` + `touch` still guarantees accessible hit targets.
+
+## Reduced Motion and Accessibility
+
+The token system already handles reduced motion:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+    :root {
+        --j-duration-fast: 0ms;
+        --j-duration-normal: 0ms;
+        --j-duration-slow: 0ms;
+    }
+}
+```
+
+This should be extended to cover adaptive transitions — the panel collapse animations, nav morphing transitions, and drawer slide-ins that form part of the adaptive composition. If a control uses `transition: transform var(--j-duration-normal)`, reduced-motion users get instant changes automatically.
+
+For high-contrast mode, the token system can add a `[data-contrast="high"]` tier that increases border widths, removes subtle shadows, and ensures minimum contrast ratios.
+
+## Putting It Together: Token Cascade
+
+The full cascade for a control's styling looks like:
+
+```
+Base tokens (--j-*, --admin-*)
+  ↓ overridden by
+Theme tier ([data-theme="vs-dark"])
+  ↓ overridden by
+Density tier ([data-density-mode="compact"])
+  ↓ overridden by
+Interaction tier ([data-interaction-mode="touch"])
+  ↓ overridden by
+User overrides (inline style from theme profile)
+```
+
+Each layer only overrides what it needs. Controls consume tokens through CSS custom properties and adapt automatically as the cascade resolves.
+
+## Summary
+
+| Strategy | Purpose | Mechanism |
+|----------|---------|-----------|
+| Mode classes | Structural CSS adaptation | `data-layout-mode`, `data-density-mode` attributes |
+| Token tiers | Global spacing/sizing adaptation | Token overrides per density mode |
+| Theme profiles | Persistence and transfer | Serializable JSON objects |
+| Touch density | Accessible hit targets | Minimum size enforcement via CSS |
+| Reduced motion | Motion accessibility | Duration tokens zeroed |
+
+The key insight is that jsgui3's token system already handles one axis of adaptation (light/dark theming) very well. Extending the same pattern to density, layout mode, and interaction mode is a natural evolution, not a redesign.
+
+**Next:** [Chapter 5](05-showcase-app-multi-device-assessment.md) applies these strategies to the showcase app to assess what works and what needs to change.