@design.estate/dees-catalog 9.5.0 → 9.6.2

package/readme.hints.md

@@ -1,1233 +0,0 @@
-## Forms and inputs — September 2026
-
-- Shared field CSS and `inputLayout` live in `dees-input-base`; use `.field-control` for a single border/focus owner and `.input-action` for compound actions. Keep integrated table editors on their existing cell-owned focus path.
-- `ts_web/demos/inputs.ts` owns the 18-input workspace fixture and focused examples. The showcase saves real form values; do not rebuild view toggles or omit the compound controls from coverage.
-- Compound fields span the settings row. Grouped forms must not clip rings or anchored suggestions. Test editor, grouped, disabled and coarse-pointer layouts.
-- Phone/IBAN event targets are retargeted at shadow boundaries: read the native input from `composedPath()[0]`, and publish one compound change per edit.
-- Input hosts delegate focus; form Enter skips disabled fields and leaves buttons, composition, pickers and multiline editing in control of their own keys.
-- Search-select is an empty source, not a registered input. Dropdown already supports search. Use exact Lit property bindings and verified public events in examples.
-
-!!! Please pay attention to the following points when writing the readme: !!!
-* Give a short rundown of components and a few points abput specific features on each.
-* Try to list all components in a summary.
-* Then list all components with a short description.
-
-## Catalog design and demos
-
-- `ts_web/elements/00theme.ts` owns shared control, surface, spacing, and typography tokens. Controls use 8px corners, grouped surfaces 12px, and modal windows 20px. Modal and dropdown surfaces are opaque.
-- `DeesModal` owns a native `<dialog>` focus scope. A sidebar reserves 400px on desktop and 520px at viewport widths up to 600px unless `height` overrides it; content scrolls within the viewport-clamped frame. Do not measure each selected panel and resize the window on navigation.
-- `00overlay.ts` locates the invoking node's open dialog across slots and shadow roots. Transient controls must stay inside that dialog. A global body portal with a large z-index cannot escape the native top layer.
-- `DeesFormSubmit.focus()` only focuses. Use `submit()` to gather and dispatch values. Demo forms must give every field a real `key`; validation feedback and application submission rules are separate concerns.
-- `ts_web/demos/templates.ts` owns demo layout only. `workspace.ts` provides the shared form fixture. Pages cover a working composition, foundations, inputs, and overlay scenarios; component galleries retain specific variants. Use `DeesPanel.title/subtitle`, `DeesButton`'s `clicked` event, and text-safe local results.
-- The preview runs through `pnpm run watch` on port 3002. Workbench appearance is controlled by its route (`dark` / `bright`), so do not add a competing theme toggle to a page.
-- `DeesStatsGrid` measures its own width with a connection-owned `ResizeObserver`; configured minimum tile width and gap determine columns, and each span is clamped to those columns. Its single tile body owns title/value/context spacing; the unused default tile header is hidden through the tile's public part. Keep metric actions as native controls and dispatch anchored composed context-menu events to preserve dialog ownership and focus restoration.
-- `DeesDataviewStatusobject` renders status explanations and distinct shapes, wraps values through its own size container, and reports clipboard failure without claiming success. In-flight copy requests are invalidated on disconnect. The shared `demos/operations.ts` fixture powers deterministic scenario changes and manual samples for both overview demos.
-
-## Agent Chat Architecture
-
-- Harness presentation is shared through `harness.styles.ts`: neutral 12px cards, 28px action controls, sentence-case status pills and small opacity pulses. Running surfaces do not animate. Session selection changes the inset color and border without moving text or changing drag geometry. Brief outcome flashes and the existing scroll-edge fades remain.
-- Harness demos use `demoPage` or `demoApp` from the catalog helpers. Keep scenario controls outside the chat window; preserve each component's events, state examples and bounded scrolling when changing layouts.
-
-- `DeesHarnessSessionList` resource associations are controlled projections. Resources and associations remain host-owned; component-originated attach, detach, and reassign requests use `requestResourceAssociation()` and reconcile only when fresh `resourceAssociations` arrive.
-- Resource association normalization accepts the first valid record per known resource and ignores incomplete metadata, unknown references, or later duplicate records without mutating inputs. A missing `eligibleSessionIdsByResourceId` entry means no attach/reassign target; existing authoritative associations still render and can detach.
-- Resource pointer dragging is a separate gesture from session grip reordering. It targets an eligible whole session article, never creates a session drop slot, and never emits `harness-session-move`.
-- `DeesHarnessMessageList` owns transcript ordering and responsive tool grouping. Consecutive tools use one generic keyed-grid pipeline partitioned by descriptor layout: compact with compact, subtask with subtask, and full-row tools spanning every column. Never move cards between active and historical owners when status changes.
-- The transcript scroll box is the named inline-size container. Tool columns must respond to its content width so opening the session panel naturally reduces the column count.
-- Group identity is retained through front-window eviction while any card remains. Untouched projected subtasks collapse individually on completion without adding a second grid-level disclosure; other tools keep descriptor or user disclosure state.
-- `IHarnessToolCall.subtask` is an authoritative bounded child-session preview owned by the host. dees-catalog never fetches or subscribes to a runtime.
-- Existing child messages may receive deltas with one `parentMessageId`. Newly introduced child messages require a complete parent `tool-update` snapshot first.
-- `markdownWhileStreaming` defaults to true across chat, message-list, message, and tool-card hosts. Setting it false at an outer host keeps outer and nested child streams plain until the final message-end parse; forward it through render bindings and never add it to timeline rebuild conditions.
-- Inline subagent streams stop after one level through `allowSubtaskStreams`; deeper sessions use `harness-subtask-open`. A projection's `subtask.sessionId` is authoritative for drill-in; calls without a projection continue to use the existing `childSessionId` field.
-- Busy subtask cards slot Agent Brief into the nested message list's scroll flow. Terminal subtasks remove the nested chat and render Agent Brief, then Result, then the bottom drill-in action.
-- Subtask scroll surfaces hide visual scrollbars and toggle 40px top/bottom fades from actual remaining scroll content; never show an edge fade when already at that edge.
-- Authoritative child status controls subtask activity and untouched default expansion. Grid membership depends only on whether a message has a tool call.
-- Transcript resize-follow reacts to content growth only. Disclosure shrink must not repeatedly repin the outer scroll box.
-- `DeesHarnessOverflowText` owns the shared 40px right-edge fade and overflow-only reveal animation used by tool-card subtitles and Tools & Subagents activity text. It runs on hover and once after the initial two-second delay.
-- The session sidebar derives Tools & Subagents from top-level tool messages in the current retained transcript window; it never caches evicted history or includes tools inside child projections.
-
-## PDF Components
-
-- `PdfManager` creates one local module `Worker` per load and acquires the `PDFWorker` and loading task as that load progresses. Failures and aborts release every level acquired so far; successful callers release the returned document on URL change, replacement, or disconnect.
-- Keep PDF.js imported from the installed `pdfjs-dist` package. Runtime CDN imports and worker fallbacks are not allowed.
-- `DeesPdfViewer` uses the PDF.js `TextLayer` class. Cleanup closes render admission, starts document release to interrupt PDF.js operations, and settles release and tracked pipelines together within a bounded deadline.
-- PDF component loads are keyed by connection epoch and URL so stale loads cannot update detached, reconnected, or repurposed elements.
-
-## Chart Components
-
-### dees-chart-area
-- Uses Lightweight Charts; bar, donut, gauge and radar use ECharts.
-- `series` is an array of named series with `{ x, y }` samples, not an ApexCharts data shape.
-- Update the `series` property; see the current README for realtime/range options.
-- Shared chart demos use deterministic samples and explicit next/reset controls.
-- Engines are disposed on detach and re-created on reconnect. Empty series clear
-  the plot instead of substituting sample data.
-- `yAxisFormatter` controls value-axis and legend labels; bound decimal precision.
-
-### dees-chart-log  
-- Server log viewer component (not a chart despite the name)
-- Terminal-style interface with monospace font
-- Supports log levels: debug, info, warn, error, success
-- Features:
-  - Auto-scroll toggle
-  - Clear logs button
-  - Colored log levels
-  - Timestamp with milliseconds
-  - Source labels for log entries
-  - Maximum 1000 entries (configurable)
-  - Light/dark theme support
-- Demo includes realistic server log simulation
-- Note: In demos, buttons use `@clicked` event (not `@click`)
-- Demo uses global reference to access log element (window.__demoLogElement)
-
-## UI Components
-
-### dees-button-group
-- Arranges slotted action buttons with an optional label and horizontal/vertical direction.
-- Does not own a selected value. Use `dees-input-multitoggle` for segmented view,
-  mode or filter selection; use App UI tabs for content-panel navigation.
-
-## Form Components
-
-### dees-input-radio
-- Radio button component with proper group behavior
-- Properties:
-  - `name`: Group name for mutually exclusive selection
-  - `key`: Unique identifier for the radio option
-  - `value`: Boolean indicating selection state
-  - `label`: Display label
-- Features:
-  - Automatic group management (radios with same name are mutually exclusive)
-  - Cannot be deselected by clicking (proper radio behavior)
-  - Form integration: Radio groups are collected by name, value is the selected radio's key
-  - Works both inside and outside forms
-  - Supports disabled state
-- Fixed: Radio buttons now properly deselect others in the group on first click
-- Note: When using in forms, set both `name` (for grouping) and `key` (for the value)
-
-## WYSIWYG Editor Architecture
-
-### Recent Refactoring (2025-06-24)
-
-The WYSIWYG editor has been refactored to improve maintainability and separation of concerns:
-
-#### New Handler Classes
-
-1. **WysiwygBlockOperations** (`wysiwyg.blockoperations.ts`)
-   - Manages all block-related operations
-   - Methods: createBlock, insertBlockAfter, removeBlock, findBlock, focusBlock, etc.
-   - Centralized block manipulation logic
-
-2. **WysiwygInputHandler** (`wysiwyg.inputhandler.ts`)
-   - Handles all input events for blocks
-   - Manages block content updates based on type
-   - Detects block type transformations
-   - Handles slash commands
-   - Manages auto-save with debouncing
-
-3. **WysiwygKeyboardHandler** (`wysiwyg.keyboardhandler.ts`)
-   - Handles all keyboard events
-   - Manages formatting shortcuts (Cmd/Ctrl + B/I/U/K)
-   - Handles special keys: Tab, Enter, Backspace
-   - Manages slash menu navigation
-
-4. **WysiwygDragDropHandler** (`wysiwyg.dragdrophandler.ts`)
-   - Manages drag and drop operations
-   - Tracks drag state
-   - Handles visual feedback during drag
-   - Manages block reordering
-
-5. **WysiwygModalManager** (`wysiwyg.modalmanager.ts`)
-   - Static methods for showing modals
-   - Language selection for code blocks
-   - Block settings modal
-   - Reusable modal patterns
-
-#### Main Component Updates
-
-The main `DeesInputWysiwyg` component now:
-- Instantiates handler classes in `connectedCallback`
-- Delegates complex operations to appropriate handlers
-- Maintains cleaner, more focused code
-- Better separation of concerns
-
-#### Benefits
-- Reduced main component size from 1100+ lines
-- Each handler class is focused on a single responsibility
-- Easier to test individual components
-- Better code organization
-- Improved maintainability
-
-#### Fixed Issues
-- Enter key no longer duplicates content in new blocks
-- Removed problematic `setBlockContents()` method
-- Content is now managed directly through DOM properties
-- Better timing for block creation and focus
-- Slash menu no longer disappears immediately on first "/" press
-- Focus is properly maintained when slash menu opens
-- Removed duplicate event handling methods from main component
-- Simplified focus management throughout the editor
-
-#### Additional Refactoring (2025-06-24 - Part 2)
-- **Removed duplicate code**: handleBlockInput and handleBlockKeyDown methods removed from main component
-- **Simplified focus management**: Removed complex lifecycle methods and timers
-- **Fixed slash menu behavior**: Changed to click events and proper event prevention
-- **dees-wysiwyg-block component**: Now uses static HTML rendering for better content control
-- **Improved formatting preservation**: HTML formatting (bold, italic, etc.) properly preserved in all block types
-
-#### Notes
-- All input handling now goes through WysiwygInputHandler
-- All keyboard handling goes through WysiwygKeyboardHandler
-- The slash menu uses click events instead of mousedown for better UX
-- Focus is maintained using requestAnimationFrame for better timing
-- The refactoring maintains all existing functionality with improved reliability
-
-### Global Menu Architecture (2025-06-24 - Part 3)
-
-The slash menu and formatting menu have been refactored to render globally instead of inside the wysiwyg component. This fixes focus loss issues that were occurring when the menus were re-rendered with the component.
-
-#### Key Components:
-
-1. **DeesSlashMenu** (`dees-slash-menu.ts`)
-   - Singleton component that renders globally in the document body
-   - Accessed via `DeesSlashMenu.getInstance()`
-   - Manages its own visibility, position, and filtering
-   - Emits callbacks when items are selected
-
-2. **DeesFormattingMenu** (`dees-formatting-menu.ts`)
-   - Singleton component that renders globally in the document body
-   - Accessed via `DeesFormattingMenu.getInstance()`
-   - Shows when text is selected
-   - Applies formatting commands via callback
-
-3. **Integration in DeesInputWysiwyg**
-   - Stores singleton instances: `private slashMenu = DeesSlashMenu.getInstance()`
-   - Shows menus with absolute positioning
-   - Menus handle their own rendering and state management
-
-#### Benefits:
-- No focus loss when menus appear/disappear
-- Better performance (menus don't re-render with component)
-- Cleaner separation of concerns
-- Menus persist across component updates
-
-#### Usage:
-```typescript
-// Show slash menu
-this.slashMenu.show(
-  { x: cursorX, y: cursorY },
-  (type: string) => this.insertBlock(type)
-);
-
-// Show formatting menu
-this.formattingMenu.show(
-  { x: selectionX, y: selectionY },
-  (command: string) => this.applyFormat(command)
-);
-```
-
-#### Previous Issues Fixed:
-- Slash menu was disappearing immediately on first "/" press
-- Focus was lost when menus appeared
-- Text selection was not working properly
-- Cursor position was lost after menu interactions
-
-### Arrow Key Navigation (2025-06-24 - Part 4)
-
-Enhanced arrow key handling for seamless navigation between blocks:
-
-#### Features:
-1. **ArrowUp at block start**: Automatically navigates to the end of the previous block
-2. **ArrowDown at block end**: Automatically navigates to the beginning of the next block
-3. **Smart detection**: Checks actual cursor position within the block content
-4. **Slash menu integration**: When slash menu is open, arrow keys navigate menu items instead
-5. **No focus loss**: Navigation maintains focus throughout
-
-#### Implementation:
-- Added `handleArrowUp()` and `handleArrowDown()` methods to `WysiwygKeyboardHandler`
-- Smart cursor position detection for different block types (text, lists, etc.)
-- Helper method `getLastTextNode()` for finding the last text position in complex HTML
-- Prevents default behavior only when navigating between blocks
-- Skips divider blocks during navigation
-
-### Focus Management Improvements (2025-06-24 - Part 5)
-
-Enhanced focus management to prevent focus loss during various operations:
-
-#### Key Improvements:
-
-1. **Formatting Without execCommand**:
-   - Replaced deprecated `document.execCommand` with modern DOM manipulation
-   - Proper selection restoration after formatting
-   - Async formatting operations to maintain focus
-
-2. **Link Dialog**:
-   - Replaced `prompt()` with custom modal dialog
-   - Maintains focus context during async operations
-   - Auto-focuses input field in modal
-
-3. **Robust Focus Methods**:
-   - Double `requestAnimationFrame` for DOM update timing
-   - Fallback focus attempts with microtasks
-   - Contenteditable attribute verification
-
-4. **Cursor Positioning**:
-   - Enhanced `setCursorToStart/End` with edge case handling
-   - Zero-width space insertion for empty elements
-   - Recursive node traversal for complex HTML structures
-
-5. **Async Keyboard Shortcuts**:
-   - Formatting shortcuts use Promise resolution
-   - Prevents focus loss during rapid keyboard input
-
-#### Implementation Details:
-- `focusWithCursor()` method now handles empty blocks and complex HTML
-- `applyFormat()` is async and properly restores selection
-- Link creation no longer uses blocking `prompt()` dialog
-- All focus operations use proper timing with RAF and microtasks
-
-### Focus Loss Prevention for Menus (2025-06-24 - Part 6)
-
-Fixed focus loss issues when slash menu and formatting menu appear:
-
-#### Key Fixes:
-
-1. **Timeout Reduction**:
-   - Replaced 50ms setTimeout with requestAnimationFrame
-   - Immediate focus attempt before falling back to RAF
-   - Reduced delay when inserting blocks
-
-2. **Menu Focus Prevention**:
-   - Added `tabindex="-1"` to prevent menus from taking focus
-   - Added focus event prevention on menus
-   - Menus now use mousedown prevention consistently
-
-3. **Blur Event Handling**:
-   - Skip value updates when slash menu is visible
-   - Prevent auto-save during slash menu interaction
-   - Maintain focus after menu appears with RAF
-
-4. **Block Focus Optimization**:
-   - Try immediate focus if block element exists
-   - Fall back to RAF only when necessary
-   - Consistent focus handling across all block types
-
-#### Implementation:
-- `handleBlockBlur()` checks if slash menu is visible before updating
-- `scheduleAutoSave()` skips saving when slash menu is open
-- Slash menu show adds RAF to restore focus if lost
-- Reduced timing delays throughout the focus chain
-
-### Slash Command Cleanup (2025-06-24 - Part 7)
-
-Fixed the issue where "/" remained in the editor after selecting a block type:
-
-#### The Fix:
-
-1. **In `insertBlock()`**:
-   - Clear slash command before transforming block type
-   - Use regex `/^\/[^\s]*\s*/` to match slash + filter text
-   - Trim the result to ensure clean content
-   - Set content to empty for transformed blocks
-
-2. **Improved Content Handling**:
-   - Wait for `updateComplete` before focusing
-   - Ensure lists start with empty content
-   - Consistent cleanup in both `insertBlock` and `closeSlashMenu`
-
-3. **Edge Cases**:
-   - Handle filtered commands (e.g., "/hea" for heading)
-   - Clear content even with partial matches
-   - Proper content reset for all block types
-
-Now when selecting a block type from the slash menu, the "/" and any filter text is properly removed before the block transformation occurs.
-
-### Enhanced Enter Key and Block Settings (2025-06-24 - Part 8)
-
-Added two major improvements to the wysiwyg editor:
-
-#### 1. Smart Enter Key Behavior:
-
-When pressing Enter, content after the cursor is now moved to the next block:
-
-- **Content Splitting**: Uses Range API to extract content after cursor
-- **HTML Preservation**: Maintains formatting when splitting blocks
-- **Clean Split**: Current block keeps content before cursor, new block gets content after
-- **Empty Block**: If cursor is at end, creates empty new block
-
-Implementation in `WysiwygKeyboardHandler.handleEnter()`:
-```typescript
-// Clone the range to extract content after cursor
-const afterRange = range.cloneRange();
-afterRange.selectNodeContents(target);
-afterRange.setStart(range.endContainer, range.endOffset);
-
-// Extract content after cursor
-const afterContent = afterRange.extractContents();
-```
-
-#### 2. Block Type Changing via Settings Menu:
-
-The block settings menu (three dots) now includes block type selection:
-
-- **Type Selector Grid**: Shows all available block types with icons
-- **Smart Metadata Handling**: 
-  - Clears code language when changing from code block
-  - Clears list type when changing from list
-  - Prompts for language when changing to code block
-- **Visual Feedback**: Currently selected type is highlighted
-- **Instant Update**: Block transforms immediately on selection
-
-Features:
-- Works for all block types (not just code blocks)
-- Preserves content during type transformation
-- Handles special cases like code block language selection
-- Modal closes automatically after selection
-
-### Complete WYSIWYG Refactoring (2025-06-24 - Part 9)
-
-Major architectural improvements to fix Enter key behavior and left arrow focus loss:
-
-#### 1. Async Operation Architecture:
-- All focus operations are now async with proper Promise handling
-- `insertBlockAfter()` waits for component updates before focusing
-- `focusBlock()` ensures DOM is ready with `updateComplete`
-- Eliminated arbitrary timeouts in favor of proper async/await
-
-#### 2. Enter Key Split Content Fix:
-- Added `getSplitContent()` method to block component
-- Properly extracts content before/after cursor using Range API
-- Updates current block and creates new block atomically
-- Content after cursor correctly moves to new block
-
-```typescript
-// In block component
-public getSplitContent(): { before: string; after: string } | null {
-  const beforeRange = range.cloneRange();
-  beforeRange.selectNodeContents(this.blockElement);
-  beforeRange.setEnd(range.startContainer, range.startOffset);
-  // ... extract and return split content
-}
-```
-
-#### 3. Arrow Key Navigation:
-- Added ArrowLeft/ArrowRight handlers for block boundaries
-- Prevents focus loss when navigating between blocks
-- Only intercepts at block boundaries, normal navigation otherwise
-- All arrow key operations are async for proper timing
-
-#### 4. Interface Architecture:
-Created `wysiwyg.interfaces.ts` with proper typing:
-- `IWysiwygComponent` - Main component contract
-- `IBlockOperations` - Block operation methods
-- `IWysiwygBlockComponent` - Block component interface
-- `IBlockEventHandlers` - Event handler signatures
-
-#### 5. Focus Management Improvements:
-- Eliminated double RAF in favor of single async flow
-- Focus operations wait for DOM updates via `updateComplete`
-- Proper cursor positioning after all operations
-- No more focus loss during navigation
-
-#### Key Changes:
-1. Keyboard handler methods are now async
-2. Block operations return Promises
-3. Enter key properly splits content at cursor
-4. Arrow keys handle block navigation without focus loss
-5. All timing is handled via proper async/await patterns
-
-The refactoring eliminates race conditions and timing issues that were causing focus loss and content duplication problems.
-
-### Programmatic Rendering Solution (2025-06-24 - Part 10)
-
-Fixed persistent focus loss issue by implementing fully programmatic rendering:
-
-#### The Problem:
-- User would click in a block, type text, then press arrow keys and lose focus
-- Root cause: Lit was re-rendering components when block content was mutated
-- Even with shouldUpdate() preventing re-renders, parent re-evaluation caused focus loss
-
-#### The Solution:
-
-1. **Static Parent Rendering**:
-   - Parent component renders only once with empty editor content div
-   - All blocks are created and managed programmatically via DOM manipulation
-   - No Lit re-renders triggered by state changes
-
-2. **Manual Block Management**:
-   - `renderBlocksProgrammatically()` creates all block elements manually
-   - `createBlockElement()` builds block wrapper with all event handlers
-   - `updateBlockElement()` replaces individual blocks when needed
-   - No reactive properties trigger parent re-renders
-
-3. **Content Update Strategy**:
-   - During typing, content is NOT immediately synced to data model
-   - Auto-save delayed to 2 seconds to avoid interference
-   - Content synced from DOM only on blur or before save
-   - `syncAllBlockContent()` reads from DOM when needed
-
-4. **Focus Preservation**:
-   - Block components prevent re-renders with `shouldUpdate()`
-   - Parent never re-renders after initial load
-   - Focus remains stable during all editing operations
-   - Arrow key navigation works without focus loss
-
-5. **Implementation Details**:
-   ```typescript
-   // Parent render method - static after first render
-   render(): TemplateResult {
-     return html`
-       <div class="editor-content" id="editor-content">
-         <!-- Blocks rendered programmatically -->
-       </div>
-     `;
-   }
-   
-   // All block operations use DOM manipulation
-   private renderBlocksProgrammatically() {
-     this.editorContentRef.innerHTML = '';
-     this.blocks.forEach(block => {
-       const blockWrapper = this.createBlockElement(block);
-       this.editorContentRef.appendChild(blockWrapper);
-     });
-   }
-   ```
-
-This approach completely eliminates focus loss by taking full control of the DOM and preventing any framework-induced re-renders during editing.
-
-### Code Refactoring and Cleanup (2025-06-24 - Part 11)
-
-Completed comprehensive refactoring to ensure clean, maintainable code with separated concerns:
-
-#### Refactoring Changes:
-
-1. **Drag and Drop Handler Cleanup**:
-   - Removed all `requestUpdate()` calls from drag handler
-   - Handler now only updates internal state
-   - Parent component handles DOM updates programmatically
-   - Simplified drag state management
-
-2. **Unused Code Removal**:
-   - Removed duplicate `showBlockSettingsModal` method (using WysiwygModalManager)
-   - Removed duplicate `showLanguageSelectionModal` method
-   - Removed unused `renderBlock` method
-   - Cleaned up unused imports (WysiwygBlocks, ISlashMenuItem)
-
-3. **Import Cleanup**:
-   - Removed unused type imports
-   - Organized imports logically
-   - Kept only necessary dependencies
-
-4. **Separated Concerns**:
-   - Modal management in WysiwygModalManager
-   - Block operations in WysiwygBlockOperations
-   - Input handling in WysiwygInputHandler
-   - Keyboard handling in WysiwygKeyboardHandler
-   - Drag/drop in WysiwygDragDropHandler
-   - Each class has a single responsibility
-
-5. **Programmatic DOM Management**:
-   - All DOM updates happen through explicit methods
-   - No reactive re-renders during user interaction
-   - Manual class management for drag states
-   - Direct DOM manipulation for performance
-
-6. **Test Files Created**:
-   - `test-focus-fix.html` - Verifies focus management
-   - `test-drag-drop.html` - Tests drag and drop functionality
-   - `test-comprehensive.html` - Tests all features together
-
-The refactoring follows the principles in instructions.md:
-- Uses static templates with manual DOM operations
-- Maintains separated concerns in different classes
-- Results in clean, concise, and manageable code
-
-## Z-Index Management System (2025-12-24)
-
-A comprehensive z-index management system has been implemented to fix overlay stacking conflicts:
-
-### The Problem:
-- Modals were hiding dropdown overlays
-- Context menus appeared behind modals
-- Inconsistent z-index values across components
-- No clear hierarchy for overlay stacking
-
-### The Solution:
-
-#### 1. Central Z-Index Constants (`00zindex.ts`):
-Created a centralized file defining all z-index layers:
-
-```typescript
-export const zIndexLayers = {
-  // Base layer: Regular content
-  base: {
-    content: 'auto',
-    inputElements: 1,
-  },
-  // Fixed UI elements
-  fixed: {
-    appBar: 10,
-    sideMenu: 10,
-    mobileNav: 250,
-  },
-  // Overlay backdrops
-  backdrop: {
-    dropdown: 1999,
-    modal: 2999,
-    contextMenu: 3999,
-  },
-  // Interactive overlays
-  overlay: {
-    dropdown: 2000,     // Dropdowns and select menus
-    modal: 3000,        // Modal dialogs
-    contextMenu: 4000,  // Context menus and tooltips
-    toast: 5000,        // Toast notifications
-  },
-  // Special cases
-  modalDropdown: 3500,    // Dropdowns inside modals
-  wysiwygMenus: 4500,     // Editor formatting menus
-}
-```
-
-#### 2. Updated Components:
-- **dees-modal**: Changed from 2000 to 3000
-- **dees-windowlayer**: Changed from 200-201 to 1999-2000 (used by dropdowns)
-- **dees-contextmenu**: Changed from 10000 to 4000
-- **dees-toast**: Changed from 10000 to 5000
-- **wysiwyg menus**: Changed from 10000 to 4500
-- **dees-appui-profiledropdown**: Uses new dropdown z-index (2000)
-
-#### 3. Stacking Order (bottom to top):
-1. Regular page content (auto)
-2. Fixed navigation elements (10-250)
-3. Dropdown backdrop (1999)
-4. Dropdown content (2000)
-5. Modal backdrop (2999)
-6. Modal content (3000)
-7. Context menu (4000)
-8. WYSIWYG menus (4500)
-9. Toast notifications (5000)
-
-#### 4. Key Benefits:
-- Dropdowns now appear above modals
-- Context menus appear above dropdowns and modals
-- Toast notifications always appear on top
-- Consistent and predictable stacking behavior
-- Easy to adjust hierarchy by modifying central constants
-
-#### 5. Testing:
-Created `test-zindex.demo.ts` to verify stacking behavior with:
-- Modal containing dropdown
-- Context menu on modal
-- Toast notifications
-- Complex overlay combinations
-
-### Usage:
-Import and use the z-index constants in any component:
-```typescript
-import { zIndexLayers } from './00zindex.js';
-
-// In styles
-z-index: ${zIndexLayers.overlay.modal};
-```
-
-This system ensures proper stacking order for all overlay components and prevents z-index conflicts.
-
-## TC39 Standard Decorators Migration (2025-01-17)
-
-Successfully migrated from experimental TypeScript decorators to standard TC39 decorators as recommended by Lit 3.x documentation.
-
-### Migration Overview:
-
-#### 1. Changes Made:
-- **Added `accessor` keyword** to all `@property` and `@state` decorated fields across 69 component files
-- **Updated tsconfig.json**: Removed `experimentalDecorators: true` and `useDefineForClassFields: false`
-- **Fixed optional properties**: Changed `accessor prop?: Type` to `accessor prop: Type | undefined = undefined`
-- **Removed incompatible decorators**: Removed `@query` and non-reactive `@state` decorators from regular fields
-
-#### 2. Key Pattern Changes:
-
-**Before (Experimental Decorators):**
-```typescript
-@property({ type: String })
-public value: string = '';
-
-@property({ type: Boolean })
-public disabled?: boolean;
-```
-
-**After (Standard TC39 Decorators):**
-```typescript
-@property({ type: String })
-accessor value: string = '';
-
-@property({ type: Boolean })
-accessor disabled: boolean | undefined = undefined;
-```
-
-#### 3. Important Rules:
-- **@property and @state**: MUST use `accessor` keyword for reactive properties
-- **@query decorators**: Should NOT use `accessor` (they work with regular fields)
-- **Optional properties**: Cannot use `?` syntax with accessor, must use `| undefined = undefined`
-- **Private fields**: Non-reactive private fields should not use decorators
-
-#### 4. TypeScript Configuration:
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext"
-  }
-}
-```
-Note: `experimentalDecorators` defaults to false, and `useDefineForClassFields` defaults to true with ES2022 target.
-
-#### 5. Build Results:
-- ✅ Build successful with standard decorators
-- ✅ Tests passing (7/8 - same as before migration)
-- ✅ No bundle size changes reported
-- ✅ All components working correctly
-
-#### 6. Files Modified:
-- 69 component files with decorator updates
-- 16 files with optional property fixes
-- 3 files with @query decorator removals
-- tsconfig.json configuration update
-
-### Why This Migration:
-
-According to Lit's documentation (https://lit.dev/docs/components/decorators/#decorator-versions):
-- TC39 standard decorators are the future-proof approach
-- Provides better TypeScript integration
-- Aligns with JavaScript specification
-- While bundle sizes are slightly larger, the standardization benefits outweigh this
-
-### Testing:
-- All unit tests passing
-- Manual testing of key components verified
-- No regressions detected
-- Focus management and interactions working correctly
-
-## Enhanced AppUI API (2025-12-08)
-
-The `dees-appui` component has been enhanced with a unified configuration API for building real-world applications.
-
-### New Modules:
-
-1. **ViewRegistry** (`view.registry.ts`)
-   - Manages view definitions and their lifecycle
-   - Supports tag names, element classes, and template functions as view content
-   - Methods: register, get, renderView, findByRoute
-
-2. **AppRouter** (`app.router.ts`)
-   - Built-in routing with hash or history mode
-   - External router support for framework integration
-   - Methods: navigate, back, forward, onRouteChange
-
-3. **StateManager** (`state.manager.ts`)
-   - Persists UI state (collapsed menus, selections, current view)
-   - Supports localStorage, sessionStorage, or memory storage
-   - Methods: save, load, update, clear
-
-### New Interfaces (in `interfaces/appconfig.ts`):
-
-```typescript
-interface IAppConfig {
-  branding?: { logoIcon?: string; logoText?: string };
-  appBar?: IAppBarConfig;
-  views: IViewDefinition[];
-  mainMenu?: IMainMenuConfig;
-  routing?: IRoutingConfig;
-  statePersistence?: IStatePersistenceConfig;
-  onViewChange?: (viewId: string, view: IViewDefinition) => void;
-}
-
-interface IViewDefinition {
-  id: string;
-  name: string;
-  iconName?: string;
-  content: string | (new () => HTMLElement) | (() => TemplateResult);
-  secondaryMenu?: ISecondaryMenuGroup[];
-  contentTabs?: ITab[];
-  route?: string;
-}
-
-interface IRoutingConfig {
-  mode: 'hash' | 'history' | 'external' | 'none';
-  basePath?: string;
-  defaultView?: string;
-  syncUrl?: boolean;
-}
-```
-
-### New Public Methods on DeesAppui:
-
-```typescript
-// Configure with unified config
-configure(config: IAppConfig): void
-
-// Navigation
-navigateToView(viewId: string): boolean
-getCurrentView(): IViewDefinition | undefined
-
-// State management
-getUIState(): IAppUIState
-restoreUIState(state: IAppUIState): void
-saveState(): void
-loadState(): boolean
-
-// Access internals
-getViewRegistry(): ViewRegistry
-getRouter(): AppRouter | null
-```
-
-### Usage Example (New Unified Config API):
-
-```typescript
-import type { IAppConfig } from '@design.estate/dees-catalog';
-
-const config: IAppConfig = {
-  branding: { logoIcon: 'lucide:box', logoText: 'My App' },
-  views: [
-    { id: 'dashboard', name: 'Dashboard', iconName: 'lucide:home', content: 'my-dashboard' },
-    { id: 'settings', name: 'Settings', iconName: 'lucide:settings', content: 'my-settings' },
-  ],
-  mainMenu: {
-    sections: [{ views: ['dashboard'] }],
-    bottomItems: ['settings'],
-  },
-  routing: { mode: 'hash', defaultView: 'dashboard' },
-  statePersistence: { enabled: true, storage: 'localStorage' },
-};
-
-html`<dees-appui .config=${config}></dees-appui>`;
-```
-
-### Backward Compatibility:
-
-The existing property-based API still works:
-
-```typescript
-html`
-  <dees-appui
-    .mainmenuGroups=${groups}
-    .secondarymenuGroups=${secondaryGroups}
-    @mainmenu-tab-select=${handler}
-  >
-    <div slot="maincontent">...</div>
-  </dees-appui>
-`;
-```
-
-### Key Features:
-
-- **Declarative View Registry**: Map menu items to view components
-- **Built-in Routing**: Hash or history mode with URL synchronization
-- **External Router Support**: Integrate with Angular Router or other frameworks
-- **State Persistence**: Save/restore collapsed menus, selections, and current view
-- **View-specific Menus**: Each view can define its own secondary menu and tabs
-- **Full Backward Compatibility**: Existing code continues to work
-
-## AppUI Bottom Bar (2026-01-03)
-
-Added a new `dees-appui-bottombar` component similar to `dees-workspace-bottombar`, providing a 24px fixed-height status bar at the bottom of the app shell.
-
-### Features:
-- **Generic status widgets**: Configurable widgets with icon, label, status colors, loading spinner
-- **App-specific actions**: Quick action buttons with icons and tooltips
-- **Always visible**: Fixed 24px height at the bottom of the app
-- **Status colors**: idle, active (blue), success (green), warning (yellow), error (red)
-- **Context menus**: Widgets can have right-click context menus
-
-### New Interfaces (in `interfaces/appconfig.ts`):
-
-```typescript
-interface IBottomBarWidget {
-  id: string;
-  iconName?: string;
-  label?: string;
-  status?: 'idle' | 'active' | 'success' | 'warning' | 'error';
-  tooltip?: string;
-  loading?: boolean;
-  onClick?: () => void;
-  contextMenuItems?: IBottomBarContextMenuItem[];
-  position?: 'left' | 'right';
-  order?: number;
-}
-
-interface IBottomBarAction {
-  id: string;
-  iconName: string;
-  tooltip?: string;
-  onClick: () => void | Promise<void>;
-  disabled?: boolean;
-  position?: 'left' | 'right';
-}
-
-interface IBottomBarConfig {
-  visible?: boolean;
-  widgets?: IBottomBarWidget[];
-  actions?: IBottomBarAction[];
-}
-```
-
-### Usage via configure():
-
-```typescript
-const config: IAppConfig = {
-  // ... other config
-  bottomBar: {
-    visible: true,
-    widgets: [
-      {
-        id: 'status',
-        iconName: 'lucide:activity',
-        label: 'System Online',
-        status: 'success',
-        tooltip: 'All systems operational',
-        onClick: () => console.log('Status clicked'),
-      },
-      {
-        id: 'notifications',
-        iconName: 'lucide:bell',
-        label: '3 notifications',
-        status: 'warning',
-        position: 'left',
-      },
-      {
-        id: 'version',
-        iconName: 'lucide:gitBranch',
-        label: 'v1.2.3',
-        position: 'right',
-      },
-    ],
-    actions: [
-      {
-        id: 'terminal',
-        iconName: 'lucide:terminal',
-        tooltip: 'Open Terminal',
-        position: 'right',
-        onClick: () => console.log('Terminal clicked'),
-      },
-    ],
-  },
-};
-```
-
-### Programmatic API:
-
-```typescript
-// Add/update/remove widgets
-appui.bottomBar.addWidget({ id: 'status', ... });
-appui.bottomBar.updateWidget('status', { status: 'error', label: 'Error!' });
-appui.bottomBar.removeWidget('status');
-appui.bottomBar.clearWidgets();
-
-// Add/remove actions
-appui.bottomBar.addAction({ id: 'refresh', iconName: 'lucide:refreshCw', ... });
-appui.bottomBar.removeAction('refresh');
-appui.bottomBar.clearActions();
-
-// Visibility control
-appui.setBottomBarVisible(false);
-appui.getBottomBarVisible();
-```
-
-### Files:
-- `ts_web/elements/00group-appui/dees-appui-bottombar/dees-appui-bottombar.ts` - Main component
-- `ts_web/elements/00group-appui/dees-appui-bottombar/dees-appui-bottombar.demo.ts` - Demo
-- `ts_web/elements/interfaces/appconfig.ts` - New interfaces added
-
-## Media Components (2026-01-26)
-
-New media viewer components and a unified preview composite component.
-
-### Directory: `ts_web/elements/00group-media/`
-
-#### dees-image-viewer
-- Image display with zoom, pan, fit, and download controls
-- Properties: `src`, `alt`, `fit` ('contain'|'cover'|'actual'), `showToolbar`
-- Features: mouse wheel zoom, click-drag pan, double-click toggle, checkerboard transparency background
-- Toolbar matches PDF viewer pattern (48px height, 32px buttons, 16px icons, 6px border-radius)
-
-#### dees-audio-viewer
-- Audio player with waveform visualization via Web Audio API
-- Properties: `src`, `title`, `artist`, `showWaveform`, `autoplay`, `loop`
-- Features: canvas waveform rendering, play/pause, seek, volume control, mute toggle, loop toggle
-- Uses `HTMLAudioElement` for playback, `AudioContext.decodeAudioData` for waveform data
-
-#### dees-video-viewer
-- Video player with custom overlay controls
-- Properties: `src`, `poster`, `showControls`, `autoplay`, `loop`, `muted`
-- Features: custom controls bar with gradient, seekbar, volume slider, fullscreen toggle, auto-hide controls, 16:9 aspect ratio
-
-### dees-preview (Composite Component)
-- Auto-detects content type and delegates to the appropriate viewer
-- Directory: `ts_web/elements/00group-media/dees-preview/`
-- Properties: `url`, `file` (File object), `base64`, `textContent`, `contentType` (override), `language`, `mimeType`, `filename`, `showToolbar`, `showFilename`
-- Content type detection priority: explicit override → MIME type → file extension → fallback
-- Renders: image→DeesImageViewer, pdf→DeesPdfViewer, code→DeesDataviewCodebox, audio→DeesAudioViewer, video→DeesVideoViewer, text→pre, unknown→placeholder
-- Header bar with file type icon, filename, and type badge
-
-### dees-dataview-codebox modification
-- Removed `<dees-windowcontrols>` elements from the appbar (Step 1 of the plan)
-- Now shows clean centered filename title bar without fake window buttons
-
-### Icon Sizing Convention
-- All `dees-icon` elements in buttons need explicit `font-size: 16px` CSS rule
-- Toolbar buttons: 32px × 32px, border-radius: 6px
-- Placeholder/error icons: `font-size: 32px`
-- Pattern: `.button-class dees-icon { font-size: 16px; }`
-
-## Thumbnail Component System (2026-01-27)
-
-A family of 200×260px content preview cards with a shared abstract base class. All tiles support lazy loading (IntersectionObserver with 200px margin), hover lift effect, click events, loading/error states, and three sizes (small: 150×195, default: 200×260, large: 250×325).
-
-### Architecture
-
-- **DeesThumbnailBase** (`dees-thumbnail-shared/DeesThumbnailBase.ts`) — Abstract base class extending DeesElement
-  - Common properties: `clickable`, `loading`, `error`, `size`, `label`
-  - IntersectionObserver lazy loading via `onBecameVisible()` hook
-  - Click dispatch via `tile-click` CustomEvent (detail from `getTileClickDetail()`)
-  - Subclasses implement `renderTileContent(): TemplateResult`
-
-### Components
-
-| Tag | Class | Description |
-|-----|-------|-------------|
-| `dees-thumbnail-pdf` | `DeesThumbnailPdf` | PDF page thumbnail with hover-to-browse pages. Canvas-rendered via PDF.js/CanvasPool. |
-| `dees-thumbnail-image` | `DeesThumbnailImage` | Image thumbnail with `object-fit: cover`, dimension detection on load |
-| `dees-thumbnail-audio` | `DeesThumbnailAudio` | Music icon + mini waveform (AudioContext decode), duration badge |
-| `dees-thumbnail-video` | `DeesThumbnailVideo` | Auto-captured first frame, duration badge, hover muted auto-preview |
-| `dees-thumbnail-note` | `DeesThumbnailNote` | First ~12 lines of text in monospace, gradient fade, optional language badge |
-| `dees-thumbnail-folder` | `DeesThumbnailFolder` | 2×2 grid of mini-previews (thumbnails or type icons), item count badge |
-
-### Removed Legacy Names
-
-- `dees-pdf-preview`, `dees-pdf`, and `dees-tile-pdf` are removed and have no compatibility wrappers.
-- Use `dees-pdf-viewer` for full documents and `dees-thumbnail-pdf` for grid previews.
-
-### File Structure
-
-All thumbnail components live in `ts_web/elements/00group-media/dees-thumbnail-*/`:
-- `component.ts` — Main component class
-- `demo.ts` — Demo function
-- `index.ts` — Re-export
-- `styles.ts` — (PDF thumbnail only) Component-specific styles
-- Shared base: `dees-thumbnail-shared/{DeesThumbnailBase,styles,index}.ts`
-
-### Interface: IThumbnailFolderItem
-```typescript
-interface IThumbnailFolderItem {
-  type: 'pdf' | 'image' | 'audio' | 'video' | 'note' | 'folder' | 'unknown';
-  thumbnailSrc?: string;
-  name: string;
-}
-```
-
-## StatsGrid Enhancements (2026-01-12)
-
-### Column Spanning
-
-Tiles can now span multiple columns using the `columnSpan` property. This is useful for wider visualizations like the CPU cores tile.
-
-```typescript
-const tile: IStatsTile = {
-  id: 'wide-tile',
-  title: 'Wide Tile',
-  value: 100,
-  type: 'cpuCores',
-  columnSpan: 2,  // Spans 2 columns
-  coresData: [...]
-};
-```
-
-Note: On smaller screens where only 1 column fits, tiles will automatically fall back to single column width.
-
-### CPU Cores Tile Type
-
-New tile type `cpuCores` for visualizing multi-core CPU usage with vertical bars:
-
-```typescript
-interface ICpuCore {
-  id: string | number;
-  usage: number;  // 0-100
-  label?: string;
-}
-
-const cpuTile: IStatsTile = {
-  id: 'cpu-cores',
-  title: 'CPU Cores',
-  value: 0,  // Not used, avg is calculated from coresData
-  type: 'cpuCores',
-  icon: 'lucide:cpu',
-  columnSpan: 2,  // Recommended for 8+ cores
-  coresData: [
-    { id: 0, usage: 45, label: '0' },
-    { id: 1, usage: 72, label: '1' },
-    // ... more cores
-  ],
-  description: 'Intel i7 - 8 cores'
-};
-```
-
-Features:
-- Vertical bars showing individual core usage
-- Color-coded: green (<50%), yellow (50-80%), red (>80%)
-- Shows average usage in header
-- Core labels shown for 16 or fewer cores
-- Tooltips show exact usage per core
-- Responsive: bars flex to fill available width
-
-### Available Tile Types:
-- `number` - Simple numeric display
-- `gauge` - Semi-circular gauge with thresholds
-- `percentage` - Progress bar (0-100%)
-- `trend` - Sparkline with recent data
-- `text` - Text value display
-- `multiPercentage` - Multiple progress bars
-- `cpuCores` - Vertical bar visualization for CPU cores
-
-## Component Group Taxonomy (2026-01-27)
-
-All components are organized into `00group-*` directories with 14 groups visible in the wcctools sidebar. The `demoGroups` property (plural, `string[]`) replaces the old `demoGroup` (singular). Components can belong to multiple groups.
-
-### Group Directories
-| Directory | Group Name | Count |
-|-----------|-----------|-------|
-| `00group-appui` | App UI | 10 |
-| `00group-button` | Button | 3 |
-| `00group-chart` | Chart | 2 |
-| `00group-dataview` | Data View | 4 |
-| `00group-feedback` | Feedback | 6 |
-| `00group-form` | Form | 2 |
-| `00group-input` | Input | 18 |
-| `00group-layout` | Layout | 7 |
-| `00group-media` | Media | 11 (viewers + PDF + thumbnails) |
-| `00group-overlay` | Overlay | 4 |
-| `00group-simple` | Simple | 3 |
-| `00group-utility` | Utility | 5 |
-| `00group-workspace` | Workspace | 9 |
-| `00group-runtime` | (internal) | - |
-
-### Multi-Group Components
-Some components appear in multiple groups via `demoGroups = ['Primary', 'Secondary']`:
-- `dees-chart-log`: Chart, Workspace
-- `dees-dataview-codebox`: Data View, Workspace
-- `dees-input-code`: Input, Workspace
-- `dees-input-wysiwyg`: Input, Workspace
-- `dees-form-submit`: Form, Button
-- `dees-preview`: Media, Data View
-- `dees-pdf-viewer` / `dees-thumbnail-pdf`: Media, PDF
-- `dees-stepper`: Layout, Form
-- `dees-label`: Layout, Input
-- `dees-toast`: Feedback, Overlay
-- `dees-actionbar`: Feedback, Overlay
-
-### Import Conventions
-- Within same group: `import '../sibling-component/file.js'`
-- Cross-group (from depth-2): `import '../../00group-X/component/file.js'`
-- Shared utilities: `import '../../00plugins.js'`, `import '../../00theme.js'`, etc.
-
-### Key Notes
-- The old `demoGroup` property (singular, string) is fully removed
-- All 79 components with demos use `demoGroups` (plural, string[])
-- `00group-pdf` no longer exists; PDF components are in `00group-media`
-- `dees-search` and `dees-tooltip` remain standalone (no demos)
-## Harness group decisions (2026-07)
-
-- Markdown in `00group-harness` uses `domtools.plugins.smartmarkdown` (GFM, sanitized remark pipeline) — zero new dependencies, same path as dees-speechbubble and dees-workspace-markdown. `HarnessMarkdown` singleton adds an LRU cache (200 entries) and rewrites links to `target="_blank" rel="noopener noreferrer"`. Fenced code gets lazy highlight.js via `DeesServiceLibLoader` after the final (non-streaming) parse only.
-- Tool cards resolve their kind through `DeesHarnessToolRegistry.default` (open set + `kind` override), so consumers register custom tools without forking components; `server__tool` names auto-classify as MCP with annotation badges. Optional descriptor `layout` metadata controls compact, full-row, or subtask-only grid packing and defaults to compact.
-- The syntax palette moved to the shared `ts_web/elements/00syntax.ts` (`syntaxPaletteStyles` + `syntaxScopeStyles`); codebox and harness markdown consume it — don't re-declare `--syntax-*`/hljs scope colors per component.
-- `dees-dataview-codebox` diff mode: set `codeBefore` (against `codeToDisplay`) or a pre-computed `unifiedDiff` patch; `diffView` uses exported `TDiffView = 'inline' | 'split'`. The app-bar toggle emits bubbling/composed `diff-view-change` with `IDiffViewChangeDetail`; split mode has one shared vertical owner with independently scrolling horizontal panes. Use `showDiffLineNumbers=false` for unpositioned snippets. Engine lives dependency-free in `codebox.diff.ts` (LCS + intraline segments + context folding + `toUnifiedDiff`). Tool cards use it for file-write bodies via `diffBlock(before, after, { language, filename, view, unifiedDiff, showLineNumbers })`, preserve numeric patch hunks, hide unknown gutters, and retain the selected view for the current call.
-- Terminal tool cards keep their capped body pinned to live output until the user scrolls up. Pointer leave schedules a five-second repin, pointer enter cancels it, and the inner log surface stays black in both themes.
-
-## dees-simple-login multi-method rework (2026-07)
-
-- **The catalog owns no WebAuthn protocol.** A passkey ceremony needs server-issued options and server-side verification, so `@simplewebauthn/browser` is deliberately *not* a dependency. Two mutually exclusive plug-in modes: no handler set → the component dispatches `passkey-login` / `passkey-register` / `provider-login` and stops; handler set (`passkeyLoginHandler` etc.) → the component awaits it, owns the busy state, turns a rejection into that method's error, and does **not** dispatch the request event. Suppressing the event in handler mode is what makes a double-started ceremony impossible — two concurrent `navigator.credentials.get()` calls reject each other.
-- **`login` is the one exception**: it is a notification, not a request, and always fires with dees-form's detail verbatim (`{ data: { username, password } }`) because cloudly, dcrouter and gitops depend on it.
-- **Configuration decides availability, `methodOrder` only reorders.** `passkey` (false), `providers` ([]), `password` (true) decide *whether* a method renders; `methodOrder` decides the sequence and appends anything it omits, so an incomplete order can never silently hide a configured method. Default therefore resolves to `['password']`, so the zero-configuration card is the same username/password form with the same API surface. It is **not** pixel-identical to the pre-rework component: three deliberate visual changes ship with it — the submit button is now card-width (the pre-existing `dees-tile dees-form-submit { width: 100% }` never worked because the host is `inline-block`), `.subheader` moved from `--dees-color-text-muted` (0.30 alpha, ~2:1) to `--dees-color-text-secondary`, and `.loginContainer` gained `box-sizing`, `padding` and `overflow-y: auto` so a tall multi-method card scrolls instead of clipping.
-- **Shadow-DOM reach-in is a real contract.** All three consumers do `shadowRoot.querySelector('dees-form')` then `form.setStatus()` / `form.reset()`, and cloudly's `switchToLoginContent()` hand-reverses the inline styles `switchToSlottedContent()` sets. So: `.loginContainer` / `.login` / `.slotContainer` must keep their names and inline-style choreography, the password `dees-form` must stay the first and only form in shadow order, and the `formData` listener is bound declaratively (`@formData`) because the form is now conditionally rendered and a one-shot `firstUpdated` hook-up would silently stop firing.
-- **Do not bind `.text` on the credentials `dees-form-submit`.** `dees-form.setStatus(state, text)` writes that property imperatively, and `dees-form.reset()` ends with `setStatus('normal', 'Submit')`. A Lit property binding would clobber a consumer's status text on the next render, so the label is slotted instead — which also means `labels.passwordSubmit` is read at first render only.
-- The credentials form is wrapped in `dees-tile` **only when password is the sole method**. Once the column holds other methods the column is the card, and a nested tile would inset the fields 24px against full-width buttons and read as a stray box.
-- Additive primitive gaps closed on the way: `dees-button.fullWidth` (`full-width` attribute — the host being `inline-block` meant `width: 100%` never stretched the `inline-flex` face; the opt-in path also adds `min-width: 0` + label ellipsis), the same forwarded on `dees-form-submit`, `dees-input-text.autocomplete` (needed for `username webauthn` conditional mediation), and `--dees-spinner-color` on `dees-spinner` (it hard-coded `--dees-color-text-primary`, painting a near-black arc on an accent button face in bright theme).
-- **Never mark a pending `dees-button` disabled** — `.button.disabled { opacity: 0.5 }` washes out the spinner. Guard re-entry in the handler instead; only *sibling* buttons get `disabled`.
-- Known pre-existing gaps this rework did **not** change: `--dees-color-text-secondary` is 3.44:1 in bright theme (sub-AA for 13px copy); `--dees-color-accent-primary` with white text is 3.65–4.02:1; `dees-tile`'s 16px heading padding vs the 24px content padding this component sets leaves an 8px misalignment; `dees-spinner`'s success/error faces still hard-code `--dees-color-text-primary`.
-
-## dees-button keyboard operability (2026-07)
-
-`dees-button` renders its face as a `<div class="button">`, so it had no keyboard affordance at all — nothing built on it (including every action in `dees-simple-login`) was reachable by Tab. Fixed in the primitive rather than per consumer.
-
-- The face carries `role="button"`, `tabindex` (`0`, or `-1` when `disabled`), `aria-disabled`, and `aria-busy` while `status === 'pending'`. A pending button stays focusable on purpose — pulling focus mid-ceremony strands the user.
-- **Enter activates on keydown, Space on keyup**, matching native buttons. Space keydown is swallowed so the page cannot scroll under a focused button. Verified with real CDP key events: Space activates without moving a scrollable ancestor's `scrollTop`.
-- **Keyboard activation goes through a real `click()` on the face, not a direct `clicked` dispatch.** `dees-workspace-diff-editor` (5 call sites) and `profilepicture.modal` (2) bind plain `@click` on `dees-button` rather than `@clicked`; only a real click drives both. `pointer-events: none` does not block a programmatic `click()`, so inertness is enforced in `activateFromKeyboard()` — refusing `disabled` *and* any non-`normal` status, because the status faces already set `pointer-events: none` for the mouse.
-- `DeesButton.focus()` / `.blur()` forward to the face; without that, `host.focus()` is a silent no-op.
-- **`dees-form-submit.focus()` is NOT a focus method — it submits.** `dees-form.addBehaviours()` calls `getSubmitButton()?.focus()` to implement "Enter in the last field submits the form". An earlier attempt to make it forward focus properly broke that; it must stay as-is. Keyboard focus reaches the submit through the inner `dees-button` face instead. Pinned by a test.
-- The `:focus-visible` ring uses the **opaque** `--dees-color-accent-primary`, not `--dees-color-focus-ring`. That shared token is a 0.45/0.55 alpha and composites to 1.85:1 (bright) / 2.31:1 (dark) against the surface behind the button — under the 3:1 WCAG 2.2 SC 1.4.11 wants, and a navy hairline on a dark canvas. Raising the alpha on the token itself would fix every other control too and is the wider change.
-### Focus containment across the login/app crossfade
-
-Both halves of `dees-simple-login` live in the DOM permanently, stacked and cross-faded with `opacity` + `pointer-events`. That was sufficient only while nothing inside them could hold focus. Once `dees-button` faces became focusable, `pointer-events: none` stopped containing anything — it does not remove a tab stop, and keyboard activation deliberately bypasses it — so the hidden half became reachable in both directions: Tab out of the password form into the invisible app shell, or Tab back into the invisible login card after signing in and start a passkey ceremony there.
-
-`inert` is the only thing that removes a hidden-but-rendered subtree from focus and the accessibility tree. It is derived from each container's effective `pointer-events` via a `MutationObserver` on the inline styles, **not** from an internal flag, because consumers reverse the transition by hand: cloudly's `switchToLoginContent()` writes `.login` / `.loginContainer` / `.slotContainer` inline styles directly and knows nothing about `inert`. Keying off a flag it cannot reset would leave its login card permanently inert after a session expiry. Observe only `attributeFilter: ['style']` — `inert` reflects to its own attribute and would otherwise re-trigger the observer.
-
-### Open follow-ups from this change (separate decisions, deliberately not done here)
-
-- **`--dees-color-focus-ring` is still sub-3:1 for every control other than `dees-button`.** Inputs, dropdowns and the rest still use the shared token at 0.45/0.55 alpha, which composites to 1.85:1 (bright) / 2.31:1 (dark). `dees-button` was fixed locally by switching its ring to the opaque accent, so the catalog is now *inconsistent*: one control has a compliant focus indicator and the others do not. Raising the token's alpha is the wider fix and needs its own review across every control that reads it.
-- **`dees-button-exit` is unaudited and very likely has the same keyboard defect.** It renders a decorative X glyph (`.maincontainer` + two line divs) with no click handler, no `role` and no `tabindex`; consumers wire clicks on the host. It is not a `dees-button` consumer, so the keyboard fix does not reach it.
-
-- Consumer audit: 16 non-demo components use `dees-button`. None wrap it in a `role="menu"/"listbox"/"option"/"tab"` container, none attach keyboard handlers to the button or an ancestor of it (`dees-harness-composer` and `dees-harness-question-card` bind keydown on their own `textarea`/`input`), `dees-modal` has no focus trap, `dees-button-group` only slots, and no component binds both `@click` and `@clicked` on the same button — so no double activation and no nested-role reporting change.
-
-
-## Shared workspace controls and chart formatting
-
-- `dees-input-multitoggle` owns segmented view/mode selectors. `dees-button-group`
-  only arranges actions; radio groups own radio-style form choices. Start with
-  the task chooser and exact tag index in `readme.md` before adding custom markup.
-- Run `node scripts/check-component-docs.cjs` to check registered tag coverage,
-  source links and section anchors. Use `--write-index` after adding components
-  or API sections; update the task chooser and examples manually.
-- Multitoggle `change` means a changed value; `option-activate` also reports
-  reselecting the current value. Codebox uses activation to pin an automatic
-  Inline/Split layout, while composer keeps its Shift+Tab mode shortcut.
-- Lightweight Charts asks the price formatter to format fractional scale values
-  even for integer samples. Bound precision in `yAxisFormatter`; otherwise the
-  engine can reserve most of a narrow chart for potential long labels. The
-  workspace demo uses rounded thousands, and the default Mbps formatter uses
-  at most two decimal places.
-- App UI caches inactive views with `display:none`; scope browser locators to
-  the active view. Chart startup can wait until the component enters the viewport.
-  After watch rebuilds, verify the new behavior before capturing screenshots.
-
-## Simple family composition and motion
-
-- The Simple catalog group contains `dees-simple-login`, `dees-simple-appdash`
-  and `dees-shopping-productcard`. Their demos use shared theme wrappers and
-  actual input/button/table primitives; see the README task chooser first.
-- Login's `.loginContainer`, `.login`, `.slotContainer`, password form keys and
-  externally managed submit status are shipped consumer contracts. Keep the
-  password-only tile handle even when flattening its visual parts. The brand
-  slot is separate from authenticated content. Move focus through public input
-  and button `focus()` methods; a dees-button face currently has `role=button`
-  on a div, so querying a native `button` silently misses it.
-- `changeSubject` is an RxJS subject, not a DOM event. Quantity controls emit
-  `newValue` for user increments/decrements; product cards translate it to
-  `quantityChange`. Their checkbox independently emits `selectionChange`.
-- Dashboard notices live in normal flow above the content. The terminal mounts
-  in the content wrapper, forwards a consumer-owned runtime, and uses a request
-  counter to cancel pending creation during rapid toggles or disconnect.
-- Preserve the subtle sidebar motion: submenu grid reveal, chevron rotation,
-  hover fades, and transform/opacity on rail contents. Resizing the main grid
-  every animation frame causes unnecessary content reflow. Closed submenus
-  become inert immediately; reduced-motion disables the visual transitions.
-- `test.dees-simple-components.chromium.ts` covers navigation, dynamic views,
-  notice synchronization, narrow layout, terminal cancellation and independent
-  selection/quantity events. Existing login and button tests cover the retained
-  authentication and keyboard contracts.
-## Workspace composition
-
-- `dees-workspace.demo.ts` owns Studio Notes, a real WebContainer project with dependency-free Node scripts. Do not gate the catalog behind package installation or substitute fake terminal output. The workspace shows connection errors in its existing shell.
-- Documents and terminal sessions use `dees-appui-tabs`; use its `appearance="sidebar"` for flat lists and `--dees-tabs-font-size` for compact controls. Preserve item badges for dirty documents and process results. Terminal sessions move beneath the terminal on narrow containers.
-- `dees-input-multitoggle` owns segmented selections across the catalog. Small controls use 28px geometry, a quiet rail, concentric corners, and the shared motion tokens. Keep string/keyed/boolean events, wrapping, and reduced motion intact.
-- File-tree selection reveals ancestors. Resize handles support pointer cancellation and keyboard resizing. Save All marks only successfully written, still-current contents clean; external conflicts do not auto-discard a draft after a timeout.
-- Use `DeesModal.prompt` for name dialogs: Enter, IME, cancellation, validation, and async errors belong there. Never query private modal wrapper classes to recover form values. The former `.modal .content` selector silently prevented file creation after the modal redesign.
-- Terminal labels use the existing manager's rename operation through shared `IMenuItem.onRename`; preserve session IDs, processes, and scrollback. File and terminal selections share `--dees-color-sidebar-selection` with primary text: use a raised neutral fill with a slight tint, not the saturated text-selection blue. The collapsed explorer's plus action reuses file-tree creation and opens the new document.