jsgui3-server 0.0.148 → 0.0.150

package/docs/api-reference.md

@@ -32,13 +32,30 @@ Server.serve(options?: ServerOptions): Promise<Server>
 - `DiscoveryError`: Cannot find client files or controls
 - `BindingError`: Cannot bind to specified host/port
 
-**Example:**
-```javascript
-const server = await Server.serve({
-    port: 3000,
-    ctrl: MyControl
-});
-```
+**Example:**
+```javascript
+const server = await Server.serve({
+    port: 3000,
+    ctrl: MyControl,
+    resources: {
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true
+});
+```
+
+**Serve-specific options:**
+- `resources`: Registers managed resources (in-process resource objects, local process resources, remote HTTP process resources).
+- `events`: Enables built-in SSE publisher for resource lifecycle events (`/events` by default).
 
 ### Server Constructor
 
@@ -54,12 +71,27 @@ new Server(options?: ServerOptions)
 
 **Returns:** Server instance
 
-**Events:**
-- `'ready'`: Emitted when bundling is complete
-- `'started'`: Emitted when HTTP server is listening
-- `'error'`: Emitted on server errors
-
-## Server Instance Methods
+**Events:**
+- `'ready'`: Emitted when bundling is complete
+- `'started'`: Emitted when HTTP server is listening
+- `'error'`: Emitted on server errors
+
+### Module Exports
+
+```javascript
+const jsgui = require('jsgui3-server');
+
+// Top-level exports
+jsgui.Process_Resource;
+jsgui.Remote_Process_Resource;
+jsgui.HTTP_SSE_Publisher;
+
+// Resource namespace aliases
+jsgui.Resource.Process;
+jsgui.Resource.Remote_Process;
+```
+
+## Server Instance Methods
 
 ### server.start(port, callback)
 
@@ -74,7 +106,7 @@ server.start(port?: number, callback?: (err?: Error) => void): void
 - `port` (number, optional): Port to listen on (default: 8080)
 - `callback` (function, optional): Called when server starts or fails
 
-### server.publish(route, handler)
+### server.publish(route, handler)
 
 Adds an API endpoint (legacy API).
 
@@ -83,13 +115,45 @@ Adds an API endpoint (legacy API).
 server.publish(route: string, handler: Function): void
 ```
 
-**Parameters:**
-- `route` (string): Route path (automatically prefixed with `/api/`)
-- `handler` (Function): Request handler function
-
-### server.use(middleware)
-
-Adds middleware to the server.
+**Parameters:**
+- `route` (string): Route path (automatically prefixed with `/api/`)
+- `handler` (Function): Request handler function
+
+### server.publish_observable(route, observable, options)
+
+Adds an observable-backed SSE endpoint.
+
+**Signature:**
+```javascript
+server.publish_observable(route: string, observable: Observable, options?: object): HTTP_Observable_Publisher
+```
+
+**Parameters:**
+- `route` (string): Route path. If it does not start with `/`, it is prefixed with `/api/`.
+- `observable` (Observable): Source observable stream.
+- `options` (object, optional): Publisher options.
+
+**Returns:** `HTTP_Observable_Publisher` instance.
+
+**Alias:** `server.publishObservable(route, observable, options)`
+
+### server.close(callback)
+
+Stops managed resources and closes all bound HTTP servers.
+
+**Signature:**
+```javascript
+server.close(callback?: (err?: Error | null) => void): void
+```
+
+**Behavior:**
+- Calls `resource_pool.stop()` when available
+- Stops `sse_publisher` when present
+- Closes all HTTP listeners
+
+### server.use(middleware)
+
+Adds middleware to the server.
 
 **Signature:**
 ```javascript
@@ -443,7 +507,7 @@ Serves CSS files.
 serve(request: IncomingMessage, response: ServerResponse): Promise<void>
 ```
 
-### HTTP_API_Publisher
+### HTTP_API_Publisher
 
 Handles API endpoints.
 
@@ -461,13 +525,162 @@ new HTTP_API_Publisher(spec?: PublisherSpec)
 Handles API requests.
 
 **Signature:**
-```javascript
-serve(request: IncomingMessage, response: ServerResponse): Promise<void>
-```
-
-## Resource Classes
-
-### File_System_Resource
+```javascript
+serve(request: IncomingMessage, response: ServerResponse): Promise<void>
+```
+
+### HTTP_SSE_Publisher
+
+General-purpose SSE publisher for explicit event fan-out.
+
+**Extends:** `HTTP_Publisher`
+
+**Constructor:**
+```javascript
+new HTTP_SSE_Publisher(spec?: {
+    name?: string,
+    keepaliveIntervalMs?: number,
+    maxClients?: number,
+    eventHistorySize?: number
+})
+```
+
+**Methods:**
+- `handle_http(req, res)`
+- `broadcast(event_name, data_value)`
+- `send(client_id, event_name, data_value)`
+- `stop(callback?)`
+
+**Properties:**
+- `client_count` (number)
+
+## Resource Classes
+
+### Process_Resource
+
+Represents a local process as a resource with a unified lifecycle API.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Process_Resource(spec?: {
+    name?: string,
+    command?: string,
+    args?: string[],
+    cwd?: string,
+    env?: object,
+    autoRestart?: boolean,
+    maxRestarts?: number,
+    processManager?: 'direct' | {
+        type: 'direct' | 'pm2',
+        pm2Path?: string,
+        ecosystem?: string
+    },
+    healthCheck?: {
+        type: 'http' | 'tcp' | 'custom',
+        url?: string,
+        host?: string,
+        port?: number,
+        fn?: Function,
+        intervalMs?: number,
+        timeoutMs?: number,
+        failuresBeforeUnhealthy?: number
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:**
+```javascript
+{
+    state: 'stopped' | 'starting' | 'running' | 'stopping' | 'restarting' | 'crashed',
+    pid: number | null,
+    uptime: number,
+    restartCount: number,
+    lastHealthCheck: object | null,
+    memoryUsage: object | null,
+    processManager: { type: 'direct' | 'pm2' }
+}
+```
+
+**Events:**
+- `state_change`
+- `stdout`
+- `stderr`
+- `exit`
+- `health_check`
+- `unhealthy`
+- `crashed`
+
+### Remote_Process_Resource
+
+Represents a remote HTTP-controlled process using the same lifecycle-oriented API style as `Process_Resource`.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Remote_Process_Resource(spec?: {
+    name?: string,
+    host: string,
+    port: number,
+    protocol?: 'http' | 'https',
+    pollIntervalMs?: number,
+    httpTimeoutMs?: number,
+    historySize?: number,
+    unreachableFailuresBeforeEvent?: number,
+    endpoints?: {
+        status?: string,
+        start?: string,
+        stop?: string,
+        health?: string
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:** Includes `state`, `pid`, `uptime`, `restartCount`, `lastHealthCheck`, `memoryUsage`, and `processManager: { type: 'remote' }`.
+
+**Events:**
+- `state_change`
+- `unreachable`
+- `recovered`
+
+### Server_Resource_Pool
+
+Server-specific resource pool with lifecycle orchestration and event forwarding.
+
+**Extends:** `Resource_Pool`
+
+**Methods:**
+- `add(resource)`
+- `remove(name, callback?)`
+- `start(callback?)`
+- `stop(callback?)`
+- `get_resources_by_type(type)`
+
+**Properties:**
+- `summary`: Aggregated state summary grouped by resource type.
+
+**Forwarded Events:**
+- `resource_state_change`
+- `crashed`
+- `unhealthy`
+- `unreachable`
+- `recovered`
+
+### File_System_Resource
 
 Provides access to local file system.
 
@@ -699,10 +912,10 @@ ensure_route_leading_slash(route: string): string
 ### ServerOptions
 
 ```typescript
-interface ServerOptions {
-  ctrl?: Function;
-  Ctrl?: Function;
-  src_path_client_js?: string;
+interface ServerOptions {
+  ctrl?: Function;
+  Ctrl?: Function;
+  src_path_client_js?: string;
   port?: number;
   host?: string;
   debug?: boolean;
@@ -715,15 +928,60 @@ interface ServerOptions {
   api?: Record<string, Function>;
   static?: Record<string, string>;
 
-  // Advanced options
-  cors?: CorsConfig;
-  https?: HttpsConfig;
-  middleware?: Function[];
-  publishers?: Record<string, Publisher>;
-  resources?: Record<string, Resource>;
-  bundler?: BundlerConfig;
-}
-```
+  // Advanced options
+  cors?: CorsConfig;
+  https?: HttpsConfig;
+  middleware?: Function[];
+  publishers?: Record<string, Publisher>;
+  resources?: ResourceEntries;
+  events?: boolean | EventsOptions;
+  bundler?: BundlerConfig;
+}
+```
+
+```typescript
+type ResourceEntries = Record<string, ResourceEntry> | ResourceEntry[];
+
+type ResourceEntry =
+  | Resource
+  | {
+      type?: 'process' | 'local';
+      command?: string;
+      args?: string[];
+      processManager?: 'direct' | {
+        type?: 'direct' | 'pm2';
+        pm2Path?: string;
+        ecosystem?: string;
+      };
+      [key: string]: any;
+    }
+  | {
+      type?: 'remote' | 'http';
+      host?: string;
+      port?: number;
+      protocol?: 'http' | 'https';
+      endpoints?: Record<string, string>;
+      [key: string]: any;
+    }
+  | {
+      type?: 'resource' | 'in_process' | 'in-process';
+      instance?: Resource;
+      resource?: Resource;
+      class?: new (spec?: any) => Resource;
+      Ctor?: new (spec?: any) => Resource;
+      constructor_fn?: new (spec?: any) => Resource;
+      spec?: Record<string, any>;
+      [key: string]: any;
+    };
+
+interface EventsOptions {
+  route?: string;
+  name?: string;
+  keepaliveIntervalMs?: number;
+  maxClients?: number;
+  eventHistorySize?: number;
+}
+```
 
 ### PageConfig
 
@@ -1029,4 +1287,4 @@ const server = await Server.serve({
 
 ---
 
-This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.
+This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.

package/docs/books/adaptive-control-improvements/01-control-candidate-matrix.md

@@ -0,0 +1,122 @@
+# Chapter 1 — Control Candidate Matrix and Findings
+
+## Purpose
+
+Prioritize the control catalog for adaptive upgrades based on real impact:
+
+- Structural risk on phone/tablet/orientation change
+- Data density and interaction complexity
+- Existing gap between desktop and touch behavior
+- Reuse value as a pattern for other controls
+
+## Evidence Snapshot
+
+Recent source-level review identified these concrete issues in key controls:
+
+- `master_detail.js`: fixed two-column grid (`minmax(180px, 240px) 1fr`) with no layout-mode branch.
+- `tabbed-panel.js`: horizontal tab strip is vulnerable to overflow in narrow widths.
+- `split_pane.js`: pointer-oriented resize interaction with no touch-first fallback.
+- `data_table.js`: large data surface with no responsive column-priority/card transformation strategy.
+- `sidebar_nav.js`: manual collapse exists, but no environment-driven auto-collapse/morph.
+- `Toolbar.js`: no overflow strategy for narrow widths.
+- `modal.js`: static size variants only; no automatic phone full-screen mode.
+- `form_container.js`: no adaptive multi-column to single-column strategy.
+- `status_dashboard.js`: strongest baseline due to grid auto-fit, but no explicit density/layout-mode policy.
+
+## Tiering Criteria
+
+### Impact score (1-5)
+
+- 5: Breaks or heavily degrades on common phone/tablet layouts
+- 4: Usable but substantially reduced usability on touch/narrow layouts
+- 3: Mostly usable; quality or accessibility debt
+- 2: Minor adaptive polish only
+- 1: Already adaptive enough through existing composition/tokens
+
+### Effort score (1-5)
+
+- 5: Significant API and behavior changes across composition + interaction + tests
+- 4: Medium-high code and test work
+- 3: Moderate scoped update
+- 2: Small targeted update
+- 1: Minimal changes
+
+## Candidate Matrix
+
+| Control | Impact | Effort | Priority | Why now |
+|---|---:|---:|---|---|
+| Master_Detail | 5 | 3 | Tier 1 | Canonical two-pane pattern; immediate phone pain; good first pattern anchor |
+| Tabbed_Panel | 5 | 4 | Tier 1 | High usage + overflow + keyboard/touch adaptation needs |
+| Split_Pane | 5 | 4 | Tier 1 | Pointer-first behavior conflicts with touch/mobile |
+| Data_Table | 5 | 5 | Tier 1 | Highest value for admin UIs; biggest adaptation gap |
+| Sidebar_Nav | 4 | 3 | Tier 2 | Shell-level navigation needs auto morphing |
+| Form_Container | 4 | 3 | Tier 2 | Forms must adapt cleanly across orientation and width |
+| Modal | 4 | 2 | Tier 2 | Quick high-value upgrade for phone usability |
+| Toolbar | 4 | 3 | Tier 2 | Navigation/action density requires overflow strategy |
+| Window / Window_Manager | 3 | 4 | Tier 3 | Desktop metaphor must degrade predictably on touch |
+| Wizard | 3 | 2 | Tier 3 | Stepper strip and nav controls need mobile pattern |
+| Status_Dashboard | 2 | 2 | Tier 4 | Mostly good; needs explicit density/mode tuning |
+| Drawer | 2 | 2 | Tier 4 | Good baseline; mostly environment integration and polish |
+
+## Top Discoveries
+
+### Discovery A — the highest-value pattern is the two-pane morph
+
+`Master_Detail`, `Split_Pane`, and many app-level shells all need the same adaptive morph:
+
+- Desktop: dual pane
+- Tablet portrait: primary + secondary as revealable overlay
+- Phone: stacked flow or drawer/sheet secondary
+
+This should be implemented once as a reusable adaptive region pattern and reused.
+
+### Discovery B — navigation controls need shared overflow/morph infrastructure
+
+`Tabbed_Panel`, `Sidebar_Nav`, and `Toolbar` all face narrow-width overflow and touch navigation constraints.
+
+Without shared helpers, each control will reinvent:
+
+- overflow detection
+- “more” bucket behavior
+- focus order and ARIA preservation across morphs
+
+### Discovery C — Data_Table is both a control and a mode family
+
+Treat `Data_Table` as a multi-mode control family:
+
+- Desktop mode: full grid
+- Tablet mode: reduced columns + optional detail pane
+- Phone mode: list/card mode with row expansion
+
+Trying to keep a single static grid shape across all modes will keep mobile quality low.
+
+## Layer Analysis (A/B/C/D)
+
+Applying the four-layer model:
+
+- Layer A (Domain): mostly unaffected; business data stays stable.
+- Layer B (View Composition): major work in Tier 1 and Tier 2 controls.
+- Layer C (Adaptive Resolution): requires consistent environment service usage.
+- Layer D (Concrete Render): token/mode-attribute CSS work across most controls.
+
+## Model Placement Rules for This Program
+
+For all upgrades in this book:
+
+- `data.model`: business entities, user-intent preferences that are device-agnostic.
+- `view.data.model`: resolved adaptive state (layout_mode, visible_columns, region presentation state).
+- `view.model`: transient interaction state (open/closed, active tab index, temporary scroll/focus state).
+
+Never persist runtime viewport-derived values as domain data.
+
+## Success Criteria for Candidate Selection
+
+A control is ready for implementation when:
+
+1. Target mode behavior is specified for phone, tablet, desktop.
+2. State placement is mapped to model layers.
+3. CSS mode-attribute strategy is identified.
+4. P0/P1/P2 viewport assertions are defined.
+5. Regression impact on existing desktop behavior is bounded.
+
+Next: Tier 1 playbooks with concrete upgrade recipes.