jsgui3-server 0.0.134 → 0.0.136

package/AGENTS.md

@@ -0,0 +1,6 @@
+# Agent Guidelines
+
+- Use `snake_case` for variables, functions, and helper utilities introduced by agents.
+- Use `Snake_Case` (PascalCase) for classes and constructors.
+- Update existing agent-authored code to match these conventions when you make changes.
+- If you must diverge from this convention, document the reason directly in the relevant file.

package/README.md

@@ -1,6 +1,66 @@
 # Jsgui3 Server
 
-JSGUI3 Server is a comprehensive Node.js-based application server designed to serve modern JavaScript GUI applications to web clients. It provides a complete runtime environment for delivering dynamic, component-based user interfaces with integrated data binding, event handling, and real-time synchronization.
+JSGUI3 Server is a Node.js-based application server for serving modern JavaScript GUI applications to web clients. It provides a complete runtime environment for delivering dynamic, component-based user interfaces with integrated data binding, event handling, and automatic CSS/JS bundling.
+
+## Quick Start
+
+### Simplest Possible Server
+
+```javascript
+// server.js
+const Server = require('jsgui3-server');
+const { MyControl } = require('./client').controls;
+
+Server.serve(MyControl);
+// Server runs at http://localhost:8080
+```
+
+### With Port Configuration
+
+```javascript
+Server.serve(MyControl, { port: 3000 });
+```
+
+### Single Page with Metadata
+
+```javascript
+Server.serve({
+    page: {
+        content: MyControl,
+        title: 'My Awesome App',
+        description: 'A jsgui3 application'
+    },
+    port: 3000
+});
+```
+
+### Multiple Pages
+
+```javascript
+Server.serve({
+    pages: {
+        '/': { content: HomeControl, title: 'Home' },
+        '/about': { content: AboutControl, title: 'About' },
+        '/contact': { content: ContactControl, title: 'Contact' }
+    },
+    port: 3000
+});
+```
+
+### With API Endpoints
+
+```javascript
+Server.serve({
+    page: { content: DashboardControl, title: 'Dashboard' },
+    api: {
+        'metrics': () => ({ users: 1234, revenue: 56789 }),
+        'data': async ({ range }) => await fetchAnalytics(range)
+    },
+    port: 3000
+});
+```
+
+> **Note:** The new `Server.serve()` API is the recommended approach for most use cases. See [Simple Server API Design](docs/simple-server-api-design.md) for complete documentation and advanced features.
 
 ## Architecture Overview
 
@@ -10,6 +70,7 @@ The server operates as a bridge between server-side JavaScript applications and
 - **Data Model Management:** Handles shared data objects and real-time synchronization between multiple UI controls
 - **CSS Bundling:** Dynamically compiles and serves CSS from component definitions
 - **Event Coordination:** Manages client-server event communication and state synchronization
+- **Convention Over Configuration:** Smart defaults with auto-discovery of client files
 
 ## Core Components
 
@@ -88,22 +149,30 @@ Controls in JSGUI3 follow a strict composition pattern:
 
 ```javascript
 // Basic control creation pattern
-const control = new controls.ControlType({
-    context: context,          // Required runtime context
+# Jsgui3 Server
+JSGUI3 Server is a Node.js-based server for hosting JSGUI3 controls and example apps in the browser. It serves HTML/JS/CSS generated by controls and publishers. Some features are evolving; see Status for scope.
+
+## Quick start
+
+- Show help: `node cli.js --help`
+- Run a server: `node cli.js serve --port 8080`
+- NPM scripts: `npm run cli`, `npm run serve`, `npm test`
+- Examples: many apps under `examples/controls/` include their own `server.js`; run those directly with Node.
     // ... other properties
 });
-
-// Container pattern
-container.inner.add(childControl);  // Adding to containers
-this.body.add(topLevelControl);     // Adding to document body
+## Architecture overview
+The server provides:
+- **Component serving:** Serves JSGUI3 controls and example apps to browsers
+- **Routing and publishers:** HTTP route handling via the resource pool and publishers
+- **CSS handling:** Collects/serves control CSS where provided by publishers
 ```
 
-**Key Control Types:**
+Configuration is performed in code within this repo; there is no separate `server.config.js` by default.
 - **Window:** Top-level container with title bar, positioning, and dragging capabilities
 - **Tabbed_Panel:** Container organizing content into tabs, supports both string labels and [label, control] pairs
-- **Date_Picker:** Input control for date selection with data model binding
-- **Checkbox:** Boolean input with label support
-- **Month_View:** Calendar display widget
+3. **Request handling:**
+  - Serves HTML/JS/CSS using publishers
+  - Injects/collects CSS from control definitions where applicable
 
 ### Data Model System Details
 
@@ -119,16 +188,43 @@ The data binding system is built on observable patterns:
 2. **Control Binding:**
    ```javascript
    const control = new SomeControl({
+```
+jsgui3-server/
+├── examples/
+│   └── controls/                 # Many runnable control demos
+├── controls/
+│   └── Active_HTML_Document.js   # Base control/document class
+├── publishers/                   # HTTP publishers (website, webpage, function, assets)
+├── resources/                    # Resource implementations
+├── website/                      # Website-related classes
+├── server.js                     # Server class
+└── cli.js                        # Minimal CLI (serve/help/version)
+```
        context,
-       data: { model: sharedDataModel }
-   });
-   ```
+### CSS bundling
+
+CSS may be collected from control classes and served alongside pages by publishers. Exact bundling/minification behavior depends on the website/webpage publisher and is subject to change.
+
+## CLI usage
+
+- Help: `node cli.js --help`
+- Version: `node cli.js --version`
+- Serve: `node cli.js serve --port 8080 [--host 127.0.0.1]`
+
+NPM scripts:
+
+- `npm run cli` — runs the CLI
+- `npm run serve` — starts the server via the CLI
+- `npm test` — runs a small CLI test suite
+
+VS Code task:
+
+- “Test: CLI” task is available for easy test runs.
 
-3. **Change Handler Management:**
-   - Controls automatically register change handlers on their data models
-   - `assign_data_model_value_change_handler()` method reestablishes bindings
-   - Multiple controls can share the same model for synchronized updates
+## Status
 
+- Active work-in-progress. Some features are incomplete or evolving.
+- A default holding page and streamlined admin experience are planned; see `TODO.md` and `roadmap.md`.
 ### File Structure and Conventions
 
 ```

package/TODO.md

@@ -0,0 +1,81 @@
+# TODO
+
+A living list of near-term work. PRs welcome.
+
+## Now
+- CLI wiring (no bin yet):
+  - File: `cli.js` at repo root.
+  - Commands:
+    - `node cli.js serve [--port <n>] [--host <name>] [--root <path>]`
+    - `node cli.js --help`
+    - `node cli.js --version`
+  - Behavior:
+    - Starts the HTTP server using `server.js` exports.
+    - Reads env overrides: `PORT`, `HOST`, `ROOT`.
+  - NPM scripts:
+    - "serve": `node cli.js serve`
+    - "cli": `node cli.js`
+- Add basic CLI tests with Node child_process. Cover `--help`, `--version`, and `serve --port 0` (ephemeral port) smoke.
+  - VS Code Task: "Test: CLI" added to enable Always Allow.
+
+- Controls suite (server-admin and general UI):
+  - Stabilize and complete core controls for HTML documents:
+    - Window (drag, z-order, resize), Panel, Tabbed_Panel
+    - Inputs: Text_Input, Checkbox, Select, Date_Picker, Month_View
+    - Menus: Menu, Menu_Button, Context_Menu
+    - Layout primitives: Grid/Stack/Flex helpers
+  - Patterns to standardize:
+    - Constructor/activate lifecycle, context registration, data model binding
+    - CSS as static property; shared themes; dark/light tokens
+    - Accessibility: keyboard focus, ARIA attributes for inputs/menus
+  - Documentation and demos:
+    - Refresh `/examples/controls/*` to cover each control
+    - Add an index demo page linking to all examples
+  - Testing:
+    - Minimal DOM-less unit tests for control logic (state transitions)
+    - Screenshot smoke tests for a few controls (optional later)
+
+- Server startup reliability:
+  - Default holding page: serve a simple HTML page when no website content configured
+  - Website publisher wiring: resolve "Possibly missing website publishing code." path in `publishers/http-website-publisher.js`
+  - Emit clear ready signal from server (single "Server ready") once listeners are bound
+  - Bind default host: prefer 127.0.0.1 unless `--host` provided; option to bind all IPv4
+  - Ensure `/admin` route available by default with basic status panel
+
+## Next
+- Add watch/dev: `node cli.js dev` to run a website in watch mode (if applicable).
+- Add config file support: jsgui.config.{js,json} and `--config`.
+- Add logging levels: `--verbose`, `--quiet`.
+- Add graceful shutdown: handle SIGINT/SIGTERM; print URL.
+- Document options in README.
+
+- Tests robustness (Windows):
+  - Make CLI serve smoke tolerant to process termination exit codes on Windows (child.kill may yield code 1)
+  - Prefer asserting on explicit "Server ready" line once implemented, and remove fallback matches
+
+- Admin app and file manager:
+  - Default admin UI available at `/admin` (protected later)
+  - Status panel: routes, publishers, website pages, resource pool summary
+  - File manager (local FS resource) to browse/serve a selected directory
+  - Quick start flow: pick a folder to serve; set index file; hot reload optional
+
+- CSS bundling tidy-up:
+  - Ensure CSS is bundled once from all control classes
+  - Fix legacy bundle paths; remove dead code (see NYI markers)
+
+## Later
+- Package as a real CLI (bin) when UX is stable.
+- E2E tests with a sample website directory fixture.
+- Optional: Windows service or PM2 integration for production.
+
+- Deployment workflows:
+  - `jsgui3-website` deploy function; multi-target hosting options
+  - Wizard for first-time deployment
+
+## Implementation notes
+- Keep CLI self-contained and dependency-free.
+- Parse argv manually to avoid adding libs.
+- Respect Windows PowerShell usage; scripts should run on Windows/macOS/Linux.
+- Expose a tiny contract from `server.js`:
+  - Prefer a function `startServer(opts): { server, url, stop() }`.
+  - If absent, require and invoke existing start method.

package/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// Minimal CLI wiring without a bin entry. No external deps.
+// Commands:
+//   node cli.js --help | --version
+//   node cli.js serve [--port <n>] [--host <addr>] [--root <path>]
+
+const fs = require('fs');
+const path = require('path');
+
+function readPkg() {
+  try {
+    const pkgPath = path.join(__dirname, 'package.json');
+    const txt = fs.readFileSync(pkgPath, 'utf8');
+    return JSON.parse(txt);
+  } catch (e) {
+    return { name: 'jsgui3-server', version: '0.0.0' };
+  }
+}
+
+function printHelp() {
+  const pkg = readPkg();
+  const name = pkg.name || 'jsgui3-server';
+  console.log(`${name} ${pkg.version || ''}`.trim());
+  console.log('');
+  console.log('Usage:');
+  console.log('  node cli.js --help');
+  console.log('  node cli.js --version');
+  console.log('  node cli.js serve [--port <n>] [--host <addr>] [--root <path>]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --port <n>    Port number (default 8080; 0 = ephemeral)');
+  console.log('  --host <addr> Bind to specific IPv4 address (eg 127.0.0.1)');
+  console.log('  --root <path> Project root (reserved; not yet wired)');
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--version' || a === '-v') out.version = true;
+    else if (a === '--port') { out.port = Number(argv[++i]); }
+    else if (a === '--host') { out.host = argv[++i]; }
+    else if (a === '--root') { out.root = argv[++i]; }
+    else if (!a.startsWith('-')) out._.push(a);
+    else {
+      console.error('Unknown option:', a);
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+  const cmd = args._[0];
+
+  if (args.help || (!cmd && !args.version)) {
+    printHelp();
+    process.exit(0);
+    return;
+  }
+
+  if (args.version) {
+    const pkg = readPkg();
+    console.log(pkg.version || '0.0.0');
+    process.exit(0);
+    return;
+  }
+
+  if (cmd === 'serve') {
+    const JSGUI_Server = require('./server');
+    const port = Number.isFinite(args.port) ? args.port : undefined;
+    const host = args.host || undefined;
+    const options = {
+      name: 'jsgui3 server (cli)',
+      port,
+      host,
+      root: args.root || process.cwd()
+    };
+
+    JSGUI_Server.serve(options).catch(err => {
+      console.error('Failed to start server:', err);
+      process.exit(1);
+    });
+    return;
+  }
+
+  console.error('Unknown command:', cmd);
+  printHelp();
+  process.exit(1);
+}
+
+if (require.main === module) main();