jsgui3-server 0.0.145 → 0.0.146

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`.

package/docs/jsgui3-sass-patterns-book/08-examples.md

@@ -0,0 +1,62 @@
+# Small examples
+
+These examples are minimal and focus on how Sass can be placed near controls, extended, and overridden per server.
+
+## Example 1: control-local Sass
+
+```javascript
+class Toast_Notice extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'toast_notice';
+        super(spec);
+        this.add_class('toast-notice');
+    }
+}
+
+Toast_Notice.scss = `
+.toast-notice {
+  background: var(--theme-surface, #1f1f1f);
+  color: var(--theme-on-surface, #ffffff);
+  padding: 8px 12px;
+}
+`;
+```
+
+## Example 2: extending a control with new Sass
+
+```javascript
+class Window_Compact extends Window {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'window_compact';
+        super(spec);
+        this.add_class('window-compact');
+    }
+}
+
+Window_Compact.scss = `
+.window-compact .title-bar {
+  font-size: 0.85em;
+}
+`;
+```
+
+## Example 3: workspace override via server config
+
+```javascript
+Server.serve({
+    Ctrl: Demo_UI,
+    style: {
+        load_paths: ['styles/themes'],
+        scss_sources: [
+            "@use 'obsidian_theme' as *;",
+            ":root { --theme-surface: $obsidian_surface; }"
+        ]
+    }
+});
+```
+
+## Where to implement
+
+- Control-local Sass: `jsgui3-html` control files or app-specific controls.
+- Workspace overrides: `jsgui3-server` configuration for the host app.
+- Theme tokens: a theme package consumed via `load_paths`.

package/docs/jsgui3-sass-patterns-book/09-testing-and-adoption.md

@@ -0,0 +1,27 @@
+# Testing and adoption plan
+
+This chapter proposes how to validate Sass behavior and phase it into new workspaces.
+
+## Testing suggestions
+
+- Add control-level Sass tests to confirm extraction order and compilation.
+- Add theme override tests that validate token overrides in bundled CSS.
+- Add sourcemap tests when a single compilation pass is used.
+
+Relevant test locations:
+
+- `tests/sass-controls.e2e.test.js`
+- `tests/bundlers.test.js`
+
+## Incremental adoption plan
+
+1. Define token vocabulary in `jsgui3-html` control CSS.
+2. Introduce a theme package with token overrides.
+3. Add server-level `scss_sources` for the theme in examples.
+4. Expand theme package usage in additional workspaces.
+
+## Where to implement
+
+- Test coverage: `jsgui3-server/tests`.
+- Token vocabulary: `jsgui3-html` controls and docs.
+- Theme package: new repo, consumed via `style.load_paths`.

package/docs/jsgui3-sass-patterns-book/README.md

@@ -0,0 +1,23 @@
+# JSGUI3 Sass Patterns Book
+
+This book is a set of proposals for how Sass and CSS can be used across the JSGUI3 stack. It focuses on co-locating styles with controls, supporting project-wide theming, and allowing workspace-level overrides without losing default styles.
+
+The intent is to document patterns and where they could be implemented, not to prescribe a single build system. Each chapter includes a short "Where to implement" section that points at the relevant layer.
+
+## Table of contents
+
+1. Vision and goals - `01-vision-and-goals.md`
+2. Stack map - `02-stack-map.md`
+3. Control-local Sass patterns - `03-control-local-sass.md`
+4. Extending controls and variants - `04-extension-and-variants.md`
+5. Theme tokens and runtime theming - `05-theming-and-tokens.md`
+6. Workspace overrides and shared themes - `06-workspace-overrides.md`
+7. Resource pipeline and bundling - `07-resource-and-bundling.md`
+8. Small examples - `08-examples.md`
+9. Testing and adoption plan - `09-testing-and-adoption.md`
+
+## Scope notes
+
+- These are implementation suggestions that build on existing JSGUI3 behavior.
+- The Sass compiler is already in use in the server pipeline, so patterns lean on that capability.
+- Examples are minimal and designed to be adapted into other workspaces.

package/docs/troubleshooting.md

@@ -743,8 +743,48 @@ controls.MinimalControl = MinimalControl;
 module.exports = jsgui;
 ```
 
-This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
-
----
-
+This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
+
+---
+
+## Bundling and Test Failures
+
+### `waiting for wp_publisher ready` or Publisher Ready Timeout
+
+**Symptoms:**
+- Tests hang while starting servers
+- Logs show `waiting for wp_publisher ready`
+- Tests time out without a clear stack trace
+
+**Likely cause:** the JS/CSS bundler failed before emitting `ready`.
+
+**What to check:**
+1. Look earlier in the log for bundler errors (esbuild, Sass, file resolution).
+2. Confirm `sass` is installed if you are running Sass tests.
+3. Validate the client entry path passed to `src_path_client_js`.
+
+### esbuild platform mismatch (Windows vs WSL)
+
+**Symptoms:**
+- Error: `You installed esbuild for another platform than the one you're currently using`
+
+**Cause:** `node_modules` was installed on a different OS and reused in this environment.
+
+**Fix:**
+1. Remove the existing `node_modules` from the current workspace.
+2. Reinstall dependencies in the current environment:
+   ```bash
+   npm install
+   ```
+3. If you prefer to keep the lockfile untouched, use:
+   ```bash
+   npm ci
+   ```
+4. As a fast workaround, you can try:
+   ```bash
+   npm rebuild esbuild
+   ```
+
+---
+
 Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.

package/examples/controls/14) window, canvas/client.js

@@ -181,7 +181,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [480, 400];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14b) window, canvas (improved renderer)/client.js

@@ -329,7 +329,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [480, 400];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14d) window, canvas globe/client.js

@@ -23,7 +23,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [1300, 1300];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14e) window, canvas multithreaded/client.js

@@ -877,7 +877,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [1000, 1000];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14f) window, canvas polyglobe/client.js

@@ -515,7 +515,7 @@ class Demo_UI extends Active_HTML_Document {
       });
       windowCtrl.size = [1000, 1000];
 
-      const canvas = new controls.canvas({ context });
+      const canvas = new controls.Canvas({ context });
       canvas.dom.attributes.id = 'globeCanvas';
       canvas.size = [900, 900];