jsgui3-server 0.0.144 → 0.0.146

package/docs/jsgui3-html-improvement-ideas.md

@@ -0,0 +1,162 @@
+# JSGUI3-HTML Improvement Ideas
+
+This document outlines improvement opportunities for `jsgui3-html` controls based on inspecting the current control catalog under `node_modules/jsgui3-html/controls`.
+
+## Control Inventory Snapshot (Observed)
+
+Source: `node_modules/jsgui3-html/controls/controls.js` and `controls/organised/*`.
+
+### Core (0-core)
+
+- 0-basic / 0-native-compositional
+  - button, checkbox, date-picker, dropdown-list, file-upload, icon, radio-button, Select_Options, Text_Input
+- 0-basic / 1-compositional
+  - calendar, combo-box, context-menu, color-grid, color-palette, grid, list, scroll-view, scrollbar
+  - item, item-selector, menu-node, month-view, text-item, Text_Field
+  - toggle-button, plus-minus-toggle-button, radio-button-group, timespan-selector
+  - status indicators: Indicator, Status_Indicator, Validation_Status_Indicator
+- 0-core / 1-advanced
+  - Canvas, login, popup-menu-button, string-span
+
+### Standard (1-standard)
+
+- 0-viewer
+  - array, object, object-kvp, number, string
+- 1-editor
+  - form_field / FormField, PropertyEditor / property_editor, Rich_Text_Editor
+  - array/object/number/string editors
+- 2-misc
+  - left-right-arrows-selector, up-down-arrow-buttons
+- 3-page
+  - standard-web-page, message-web-page
+- 4-data
+  - data-item, data-row, data-filter
+- 5-ui
+  - tree, tree-node, file-tree, file-tree-node
+  - toolbar, toolbox, horizontal-menu, horizontal-slider
+  - line-chart, search-bar, audio-volume, media-scrubber
+- 6-layout
+  - panel, titled-panel, title-bar, window, modal
+  - tabbed-panel, tile-slide, vertical-expander, single-line
+  - app/multi-layout-mode
+
+### Showcase (2-showcase)
+
+- icon-library
+
+### Notes / Legacy
+
+- `controls/connected/data-grid.js` exists but is commented out in `controls.js`.
+- `controls/old/*` contains historical controls (item, item-view).
+- `controls/swaps/notes.md` references progressive enhancement and swapping native controls.
+- Naming duplication: `FormField.js` vs `form_field.js`, `PropertyEditor.js` vs `property_editor.js`.
+
+## Improvement Themes
+
+### 1) Add Missing Core Controls
+
+These should be small, reliable building blocks with strong HTML parity and predictable activation.
+
+- Textarea
+- Password, email, url, tel inputs
+- Number input with stepper (native + stylized)
+- Range slider (native) + stepped slider
+- Progress bar, meter
+- Switch/toggle (native checkbox + styled)
+- Chip/tag input
+- Inline validation message control
+- Breadcrumbs, pagination
+- Tooltip/popover
+- Notification/toast, alert banner
+- Badge/pill
+
+### 2) Data & Collection Controls
+
+The existing data controls are minimal; add richer, reusable data views.
+
+- Data table with sorting, filtering, pagination
+- Virtualized list/grid for large datasets
+- Tree-table hybrid (folders with columns)
+- List reordering (drag-and-drop)
+- Master/detail split view
+- Data grid should reconnect to `controls/connected/data-grid.js` with a modern API
+
+### 3) Layout + Navigation Expansion
+
+The layout set is strong but missing higher-level patterns.
+
+- Split pane / resizable panes
+- Accordion / collapsible sections
+- Sidebar + responsive drawer
+- Tab variants (vertical, icon tabs, overflow)
+- Stepper / wizard layout
+- Layout primitives: stack, cluster, center, grid-with-gap
+
+### 4) Form & Editor Features
+
+Existing editors need feature depth, validation, and accessibility.
+
+- Form container with built-in validation routing
+- Field-level error display + status badges
+- Input masking (date, currency, phone)
+- Autosize text field / textarea
+- Rich text editor improvements: toolbar, markdown, paste sanitization
+- Object editor: expand/collapse, add/remove key-values, schema-driven rendering
+
+### 5) Feature Depth for Existing Controls
+
+Concrete enhancements based on a quick control scan:
+
+- Checkbox: fix `el_radio` typo in change handler, add `checked` sync, keyboard focus state
+- Date picker: add min/max, locale formatting, keyboard navigation, week start configuration
+- Dropdown/list/combobox: async options, filtering, typeahead, ARIA roles
+- Window/panel: snap, dock, maximize, z-index management, resize handles
+- Tree/file tree: lazy loading, multi-select, drag reparent, keyboard navigation
+- Scrollbar/scroll-view: horizontal + vertical sync, scroll inertia
+
+### 6) Accessibility + Semantics
+
+- Standardize ARIA roles, labels, and keyboard handling
+- Focus ring consistency and tab order control
+- High contrast mode + reduced motion theme
+- Screen reader text for icon-only buttons
+
+### 7) Theming + Styling System
+
+- Token-driven theme layer (color, spacing, radius, typography)
+- Control style overrides via theme context
+- Light/dark/system themes with CSS variables
+- CSS layering: base, component, utility
+- Improve `swaps` approach for progressive enhancement of native elements
+
+### 8) Consistency + Packaging
+
+- Normalize naming and case conventions in control filenames
+- Reduce duplicate editor components (FormField vs form_field)
+- Clarify which controls are core vs showcase
+- Provide explicit exports for stable public API
+
+## Suggested Roadmap
+
+### Phase 1: Core and Reliability
+
+- Add missing native inputs (textarea, number, range)
+- Fix known control bugs (checkbox `el_radio` reference)
+- Normalize control naming duplication
+- Basic accessibility pass across core controls
+
+### Phase 2: Data + Forms
+
+- Data table + virtualized list
+- Form container + validation hooks
+- Object editor improvements
+
+### Phase 3: Layout + UX Features
+
+- Split panes, accordion, responsive drawer
+- Enhanced window management
+- Theme system and style tokens
+
+## Visual Summary
+
+See `docs/jsgui3-html-improvement-ideas.svg` for an Industrial Luxury Obsidian themed diagram of these ideas.

package/docs/jsgui3-html-improvement-ideas.svg

@@ -0,0 +1,151 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1000" viewBox="0 0 1600 1000" role="img" aria-label="JSGUI3-HTML improvement ideas diagram">
+  <defs>
+    <linearGradient id="bg_grad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#0a0b0e" />
+      <stop offset="45%" stop-color="#101419" />
+      <stop offset="100%" stop-color="#141a20" />
+    </linearGradient>
+    <radialGradient id="highlight_grad" cx="70%" cy="20%" r="60%">
+      <stop offset="0%" stop-color="#2a2f36" stop-opacity="0.7" />
+      <stop offset="70%" stop-color="#0a0b0e" stop-opacity="0" />
+    </radialGradient>
+    <linearGradient id="gold_grad" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#8f7a3c" />
+      <stop offset="50%" stop-color="#d2b86a" />
+      <stop offset="100%" stop-color="#8f7a3c" />
+    </linearGradient>
+    <linearGradient id="steel_grad" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#1b2127" />
+      <stop offset="100%" stop-color="#11151a" />
+    </linearGradient>
+    <pattern id="grid_pattern" width="40" height="40" patternUnits="userSpaceOnUse">
+      <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1a2026" stroke-width="1" />
+    </pattern>
+    <filter id="soft_glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feDropShadow dx="0" dy="0" stdDeviation="6" flood-color="#c9b26b" flood-opacity="0.4" />
+    </filter>
+    <filter id="panel_shadow" x="-50%" y="-50%" width="200%" height="200%">
+      <feDropShadow dx="0" dy="4" stdDeviation="10" flood-color="#000000" flood-opacity="0.6" />
+    </filter>
+  </defs>
+
+  <rect width="1600" height="1000" fill="url(#bg_grad)" />
+  <rect width="1600" height="1000" fill="url(#grid_pattern)" opacity="0.35" />
+  <rect width="1600" height="1000" fill="url(#highlight_grad)" />
+
+  <!-- Obsidian shards -->
+  <polygon points="120,80 360,40 420,140 180,210" fill="#0e1217" opacity="0.9" />
+  <polygon points="1320,90 1540,60 1580,200 1360,240" fill="#0e1217" opacity="0.85" />
+  <polygon points="420,820 640,760 720,900 480,950" fill="#0d1116" opacity="0.9" />
+  <polygon points="1080,760 1360,700 1460,860 1160,930" fill="#0d1116" opacity="0.85" />
+
+  <!-- Decorative gold rails -->
+  <path d="M 80 120 L 1520 120" stroke="url(#gold_grad)" stroke-width="2" opacity="0.7" />
+  <path d="M 80 900 L 1520 900" stroke="url(#gold_grad)" stroke-width="2" opacity="0.6" />
+  <path d="M 140 150 L 140 870" stroke="#3a3220" stroke-width="1" opacity="0.5" />
+  <path d="M 1460 150 L 1460 870" stroke="#3a3220" stroke-width="1" opacity="0.5" />
+
+  <!-- Title -->
+  <text x="120" y="95" fill="#e5d6a2" font-size="36" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="2">
+    JSGUI3-HTML IMPROVEMENT MAP
+  </text>
+  <text x="120" y="125" fill="#9aa1a8" font-size="16" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    Industrial Luxury Obsidian theme | Control Expansion + Feature Depth
+  </text>
+
+  <!-- Central crest -->
+  <circle cx="800" cy="500" r="120" fill="url(#steel_grad)" stroke="url(#gold_grad)" stroke-width="3" filter="url(#soft_glow)" />
+  <circle cx="800" cy="500" r="90" fill="#0f141a" stroke="#2c3138" stroke-width="2" />
+  <text x="800" y="485" fill="#e5d6a2" font-size="22" font-family="Trebuchet MS, Arial, sans-serif" text-anchor="middle">
+    CONTROL SYSTEMS
+  </text>
+  <text x="800" y="515" fill="#9aa1a8" font-size="14" font-family="Trebuchet MS, Arial, sans-serif" text-anchor="middle">
+    themes | behavior | data
+  </text>
+
+  <!-- Panels -->
+  <g filter="url(#panel_shadow)">
+    <rect x="120" y="180" width="560" height="220" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+    <rect x="920" y="180" width="560" height="220" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+    <rect x="120" y="430" width="560" height="220" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+    <rect x="920" y="430" width="560" height="220" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+    <rect x="120" y="680" width="560" height="200" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+    <rect x="920" y="680" width="560" height="200" rx="18" fill="#11161c" stroke="#2c333b" stroke-width="2" />
+  </g>
+
+  <!-- Panel headings -->
+  <text x="160" y="220" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    CORE CONTROL EXPANSION
+  </text>
+  <text x="960" y="220" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    FORM AND EDITOR DEPTH
+  </text>
+  <text x="160" y="470" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    DATA AND COLLECTION
+  </text>
+  <text x="960" y="470" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    LAYOUT AND NAVIGATION
+  </text>
+  <text x="160" y="720" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    ACCESSIBILITY AND THEME
+  </text>
+  <text x="960" y="720" fill="#e5d6a2" font-size="20" font-family="Trebuchet MS, Arial, sans-serif" letter-spacing="1">
+    INFRA AND DX
+  </text>
+
+  <!-- Panel bullets -->
+  <g fill="#c3c8ce" font-size="14" font-family="Trebuchet MS, Arial, sans-serif">
+    <text x="160" y="252">- textarea, number, range, progress, meter</text>
+    <text x="160" y="274">- switch, badge, tooltip, toast, breadcrumb</text>
+    <text x="160" y="296">- chip input, pagination, notification banner</text>
+    <text x="160" y="318">- standard icon buttons and input masks</text>
+
+    <text x="960" y="252">- form container + validation hooks</text>
+    <text x="960" y="274">- field error display and status badges</text>
+    <text x="960" y="296">- object editor schema rendering</text>
+    <text x="960" y="318">- rich text toolbar + paste sanitization</text>
+
+    <text x="160" y="502">- data table with sort, filter, paginate</text>
+    <text x="160" y="524">- virtual list/grid for large data</text>
+    <text x="160" y="546">- tree-table hybrid + lazy load</text>
+    <text x="160" y="568">- reconnect modern data grid module</text>
+
+    <text x="960" y="502">- split panes + resizable layout</text>
+    <text x="960" y="524">- accordion, drawer, wizard stepper</text>
+    <text x="960" y="546">- tab variants + overflow handling</text>
+    <text x="960" y="568">- window snap, dock, z-order</text>
+
+    <text x="160" y="752">- ARIA roles and focus management</text>
+    <text x="160" y="774">- keyboard navigation standards</text>
+    <text x="160" y="796">- theming tokens + CSS variables</text>
+    <text x="160" y="818">- high contrast + reduced motion</text>
+
+    <text x="960" y="752">- normalize duplicate control names</text>
+    <text x="960" y="774">- stable public API surface</text>
+    <text x="960" y="796">- test harnesses + visual regressions</text>
+    <text x="960" y="818">- structured docs and sample gallery</text>
+  </g>
+
+  <!-- Connectors -->
+  <g stroke="#3b3f46" stroke-width="1" opacity="0.7">
+    <line x1="680" y1="290" x2="720" y2="410" />
+    <line x1="920" y1="290" x2="880" y2="410" />
+    <line x1="680" y1="540" x2="720" y2="540" />
+    <line x1="920" y1="540" x2="880" y2="540" />
+    <line x1="680" y1="790" x2="720" y2="600" />
+    <line x1="920" y1="790" x2="880" y2="600" />
+  </g>
+
+  <!-- Gold accents -->
+  <g stroke="url(#gold_grad)" stroke-width="2" opacity="0.8">
+    <line x1="120" y1="410" x2="680" y2="410" />
+    <line x1="920" y1="410" x2="1480" y2="410" />
+    <line x1="120" y1="660" x2="680" y2="660" />
+    <line x1="920" y1="660" x2="1480" y2="660" />
+  </g>
+
+  <!-- Footer note -->
+  <text x="120" y="950" fill="#7f8790" font-size="13" font-family="Trebuchet MS, Arial, sans-serif">
+    Diagram companion to docs/jsgui3-html-improvement-ideas.md
+  </text>
+</svg>

package/docs/jsgui3-sass-patterns-book/01-vision-and-goals.md

@@ -0,0 +1,31 @@
+# Vision and goals
+
+This chapter frames the goals for Sass in JSGUI3 and the tradeoffs that shape the patterns in later chapters.
+
+## Goals
+
+- Co-locate styles with controls so behavior and styling evolve together.
+- Allow controls to be extended with additional Sass or CSS without editing upstream repos.
+- Support project-wide theming that can override defaults across multiple workspaces.
+- Keep the style pipeline deterministic, with predictable ordering and output.
+- Enable server-specific styling for examples, demos, or host apps.
+
+## Non-goals
+
+- No single theming system must be enforced for all projects.
+- No requirement to use Sass for every control; plain CSS should remain first-class.
+- No requirement to change the client runtime to parse Sass at runtime.
+
+## Suggested outcomes
+
+- A shared pattern for control-local Sass, with explicit layering rules.
+- A theme token vocabulary for controls, backed by CSS variables.
+- Workspace-level overrides that can be injected ahead of or after control styles.
+- A consistent way to configure Sass load paths and shared sources.
+
+## Where to implement
+
+- Control-local styles: `jsgui3-html` control classes.
+- Theme tokens: `jsgui3-html` theme mixins, plus server-provided defaults.
+- Workspace overrides: `jsgui3-server` style configuration and bundlers.
+- Docs and examples: `jsgui3-server/examples` and `jsgui3-html/docs`.

package/docs/jsgui3-sass-patterns-book/02-stack-map.md

@@ -0,0 +1,40 @@
+# Stack map
+
+This map shows how styles flow through the JSGUI3 stack today and where new patterns can attach.
+
+## Current flow (summary)
+
+1. Control classes can define static `css`, `scss`, or `sass` template literals.
+2. The server extracts style segments from the client bundle source.
+3. The style bundler compiles Sass and outputs a single CSS bundle.
+4. The CSS bundle is served via the website CSS resource.
+5. Controls apply theme tokens via CSS variables and `data-theme` attributes.
+
+## Key integration points
+
+- Extraction and ordering
+  - `resources/processors/extractors/js/css_and_js/AST_Node/CSS_And_JS_From_JS_String_Using_AST_Node_Extractor.js`
+  - `style_segments` preserve per-control ordering as they appear in source files.
+
+- Sass compilation and bundling
+  - `resources/processors/bundlers/style-bundler.js`
+  - `resources/processors/compilers/SASS_Compiler.js`
+
+- CSS resource delivery
+  - `resources/website-css-resource.js`
+  - `resources/website-javascript-resource.js`
+
+- Theme tokens
+  - `jsgui3-html/control_mixins/theme.js`
+
+## Suggested additions to the stack
+
+- A theme registry module that can merge theme tokens from multiple packages.
+- A style layering policy that is explicit about ordering (base, component, overrides).
+- A workspace override registry that can be shared across servers.
+
+## Where to implement
+
+- Theme registry: `jsgui3-html` or a new `jsgui3-theme` package.
+- Style layering policy: `jsgui3-server` style bundler plus docs in `jsgui3-html`.
+- Workspace override registry: `jsgui3-server` configuration with reusable defaults.

package/docs/jsgui3-sass-patterns-book/03-control-local-sass.md

@@ -0,0 +1,60 @@
+# Control-local Sass patterns
+
+Control-local Sass keeps styles next to the control that owns them. The key is to scope selectors and define a predictable ordering that survives bundling.
+
+## Pattern: control-local style blocks
+
+- Use `Control_Name.css` for immediate, small styles.
+- Use `Control_Name.scss` for Sass variables, mixins, or nesting.
+- Use `Control_Name.sass` when you prefer indented Sass syntax.
+- Keep selectors scoped to a class or `data-jsgui-type` to avoid global collisions.
+
+Example pattern (conceptual):
+
+```javascript
+class Example_Control extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'example_control';
+        super(spec);
+        this.add_class('example-control');
+    }
+}
+
+Example_Control.scss = `
+$accent_color: #3355aa;
+.example-control {
+  border: 1px solid $accent_color;
+}
+`;
+```
+
+## Pattern: explicit ordering
+
+Ordering is preserved by the extraction pipeline when styles appear in source order. This makes it safe to stack `css`, `scss`, and `sass` in the same file as long as the intent is clear.
+
+Suggested ordering inside a control file:
+
+1. `Control_Name.css` for base layout or reset
+2. `Control_Name.scss` for token-driven styles
+3. `Control_Name.sass` for optional variant overrides
+
+## Pattern: selector scoping
+
+Preferred scoping approaches:
+
+- `.control-class` on the root node
+- `[data-jsgui-type="control_name"]` when the class is not reliable
+- `.control-class .sub-part` for internal elements
+
+Avoid styling generic tags without a parent scope.
+
+## Suggestions for improvement
+
+- Add a documented style layering convention (base, component, override) and enforce it in examples.
+- Add an optional `Control_Name.style_layers = [...]` API so the bundler can order styles even when code files are concatenated.
+
+## Where to implement
+
+- Co-located styles: `jsgui3-html` control classes.
+- Layering API: `jsgui3-server` extractor and style bundler.
+- Documentation updates: `docs/controls-development.md` plus this book.

package/docs/jsgui3-sass-patterns-book/04-extension-and-variants.md

@@ -0,0 +1,76 @@
+# Extending controls and variants
+
+Extensions should allow new styles without editing upstream controls. The pattern is to subclass the base control, add a new CSS class, and attach Sass to the subclass.
+
+## Pattern: subclass with extra Sass
+
+```javascript
+class Window_Tight extends Window {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'window_tight';
+        super(spec);
+        this.add_class('window-tight');
+    }
+}
+
+Window_Tight.scss = `
+.window-tight .title-bar {
+  padding: 4px 8px;
+}
+`;
+```
+
+## Pattern: variants with data attributes
+
+A variant can be toggled by setting a data attribute in the control spec and using a scoped selector:
+
+```javascript
+class Panel_Variant extends Panel {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'panel_variant';
+        super(spec);
+        if (spec.variant) {
+            this.dom.attributes['data-variant'] = String(spec.variant);
+        }
+    }
+}
+
+Panel_Variant.scss = `
+.panel[data-variant="compact"] {
+  gap: 6px;
+}
+`;
+```
+
+## Pattern: compositional wrappers
+
+When subclassing is not practical, wrap the base control and style the wrapper.
+
+```javascript
+class Window_Frame extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'window_frame';
+        super(spec);
+        this.add_class('window-frame');
+        const window_ctrl = new Window({ context: this.context });
+        this.add(window_ctrl);
+    }
+}
+
+Window_Frame.scss = `
+.window-frame {
+  padding: 8px;
+}
+`;
+```
+
+## Suggestions for improvement
+
+- Add a documented override order for base control CSS versus subclass CSS.
+- Add a style namespace helper to reduce selector duplication.
+
+## Where to implement
+
+- Subclassing patterns: `jsgui3-html` controls and examples.
+- Override ordering: `jsgui3-server` style bundler and extractor.
+- Namespace helper: new mixin in `jsgui3-html/control_mixins`.

package/docs/jsgui3-sass-patterns-book/05-theming-and-tokens.md

@@ -0,0 +1,54 @@
+# Theme tokens and runtime theming
+
+Theme tokens let controls share a common vocabulary for color, spacing, and typography. The current JSGUI3 theme mixin can set CSS variables and `data-theme` attributes, which makes CSS variable theming a natural fit.
+
+## Pattern: CSS variables as the public theme API
+
+- Controls should use CSS variables for colors, spacing, radii, and font styles.
+- Sass can define fallback values and combine tokens with calculations.
+- The HTML output should include `data-theme` on a root node when a theme is active.
+
+Example Sass pattern:
+
+```scss
+.window {
+  background: var(--theme-surface, #ffffff);
+  color: var(--theme-text, #1b1b1b);
+  border-color: var(--theme-border, #c0c0c0);
+}
+```
+
+## Pattern: theme token maps
+
+Allow a theme to be provided as a token map:
+
+```javascript
+const theme_tokens = {
+    surface: '#f7f7f7',
+    text: '#1f1f1f',
+    border: '#c7c7c7'
+};
+
+const window_ctrl = new Window({
+    context,
+    theme_tokens
+});
+```
+
+## Suggested token layers
+
+- Global tokens for the design system: `--theme-surface`, `--theme-text`, `--theme-border`.
+- Component tokens for customization: `--window-title-bg`, `--window-title-text`.
+- State tokens for validation or status: `--status-error`, `--status-success`.
+
+## Suggestions for improvement
+
+- Publish a default token catalog in `jsgui3-html` so controls can rely on a stable set of names.
+- Add a theme registry that merges tokens from multiple packages, with a final override layer from the host workspace.
+- Define a `data-theme` selection policy at the document root to avoid per-control configuration.
+
+## Where to implement
+
+- Token catalog and defaults: `jsgui3-html` control CSS and docs.
+- Theme registry: a new `jsgui3-theme` package or a module in `jsgui3-html`.
+- Workspace overrides: `jsgui3-server` config that injects token overrides before bundling.

package/docs/jsgui3-sass-patterns-book/06-workspace-overrides.md

@@ -0,0 +1,45 @@
+# Workspace overrides and shared themes
+
+Workspace overrides allow a server or host app to change the look of upstream controls without editing the upstream repo. The server style configuration already supports extra Sass sources and load paths.
+
+## Pattern: server-injected Sass sources
+
+The server can inject shared Sass sources for a workspace:
+
+```javascript
+Server.serve({
+    Ctrl: Demo_UI,
+    style: {
+        load_paths: ['styles', 'themes'],
+        scss_sources: ["@use 'theme_tokens';"],
+        sass_sources: []
+    }
+});
+```
+
+This pattern lets the workspace override tokens or provide mixins that are available to all control-local Sass.
+
+## Pattern: theme packages
+
+Create a theme package that exports Sass partials and token maps. Suggested structure:
+
+- `themes/<theme_name>/_tokens.scss`
+- `themes/<theme_name>/_components.scss`
+- `themes/<theme_name>/index.scss`
+
+Then add the theme directory to `load_paths` and include it in `scss_sources`.
+
+## Pattern: host-specific CSS
+
+Server-owned CSS can be appended or prepended to the bundle for host-specific layout or typography. This is useful for `examples/` and other demos.
+
+## Suggestions for improvement
+
+- Add a `style.layers` configuration that defines ordering for base styles, theme styles, and overrides.
+- Add a workspace theme manifest format (JSON or JS) that maps theme names to Sass entry points.
+
+## Where to implement
+
+- Workspace injection: `jsgui3-server` style config passed into the bundler.
+- Theme packages: separate repos that can be added to `load_paths`.
+- Examples: `jsgui3-server/examples` with a `styles/` directory and `Demo_UI.scss` overrides.

package/docs/jsgui3-sass-patterns-book/07-resource-and-bundling.md

@@ -0,0 +1,46 @@
+# Resource pipeline and bundling
+
+This chapter proposes ways to make the Sass pipeline predictable and extensible, while building on the current server resources.
+
+## Current entry points
+
+- Style extraction: `resources/processors/extractors/js/css_and_js/AST_Node/CSS_And_JS_From_JS_String_Using_AST_Node_Extractor.js`
+- Sass compilation: `resources/processors/bundlers/style-bundler.js`
+- CSS resource: `resources/website-css-resource.js`
+- JS resource: `resources/website-javascript-resource.js`
+
+## Pattern: deterministic ordering
+
+The extractor already returns `style_segments` in source order. A suggested improvement is to make ordering explicit in the bundler with named layers:
+
+- layer: `base`
+- layer: `component`
+- layer: `override`
+
+This can be implemented by grouping `style_segments` before compilation.
+
+## Pattern: caching and invalidation
+
+Suggested improvements for faster rebuilds:
+
+- Cache compiled Sass output keyed by file hash and style config.
+- Invalidate cache only when control source or theme sources change.
+- Track `load_paths` and `scss_sources` in the cache key.
+
+## Pattern: sourcemap policy
+
+The style config already supports sourcemaps, inline maps, and source content. A suggested policy is:
+
+- Enable inline maps only when a single Sass compilation pass is used.
+- Disable inline maps when mixing `.sass` and `.scss` to avoid inaccurate mappings.
+
+## Suggestions for improvement
+
+- Add a public hook so other workspaces can provide a custom style bundler without forking the server.
+- Add a `style.debug` flag to log the style pipeline steps in a consistent format.
+
+## Where to implement
+
+- Layer ordering and caching: `resources/processors/bundlers/style-bundler.js`.
+- Debug hooks: `resources/website-css-resource.js` and `resources/website-javascript-resource.js`.
+- Custom bundler hook: server configuration and resource factory in `jsgui3-server`.