elit 3.4.9 → 3.5.1

package/README.md

@@ -9,7 +9,7 @@ The package is split by runtime. Browser-facing APIs live in `elit` and the clie
 If you are generating or editing code for Elit, follow these rules first:
 
 - Use `elit` or the client subpaths for browser UI code.
-- Use `elit/server` for HTTP routes, middleware, dev server, preview server, and server-side shared state.
+- Use `elit/server` for HTTP routes, WebSocket endpoints, middleware, dev server, preview server, and server-side shared state.
 - Use `elit/desktop` only inside `elit desktop ...` runtime. Those APIs are injected by the native desktop runtime and are not normal browser globals.
 - Use `elit/build` for programmatic bundling.
 - Use `elit/database` for the VM-backed file database helpers.
@@ -62,7 +62,7 @@ Use this table as the import map for generated code.
 | `elit/state` | Reactive state and render helpers | `createState`, `computed`, `reactive`, `text`, `bindValue`, `bindChecked`, `createSharedState` |
 | `elit/style` | CSS generation and injection | `CreateStyle`, `styles`, `renderStyle`, `injectStyle`, `addClass`, `addTag` |
 | `elit/router` | Client-side routing | `createRouter`, `createRouterView`, `routerLink` |
-| `elit/server` | HTTP router, dev server, middleware, shared server state | `ServerRouter`, `createDevServer`, `cors`, `logger`, `rateLimit`, `compress`, `security`, `StateManager` |
+| `elit/server` | HTTP router, dev server, middleware, WebSocket endpoints, shared server state | `ServerRouter`, `createDevServer`, `cors`, `logger`, `rateLimit`, `compress`, `security`, `StateManager` |
 | `elit/build` | Programmatic build API | `build` |
 | `elit/desktop` | Native desktop window APIs | `createWindow`, `createWindowServer`, `onMessage`, `windowQuit`, `windowSetTitle`, `windowEval` |
 | `elit/database` | VM-backed file database | `Database`, `create`, `read`, `save`, `update`, `rename`, `remove` |
@@ -255,12 +255,14 @@ Useful flags:
 - `elit native generate android ./src/native-screen.ts --name HomeScreen --package com.example.app`
 - `elit native generate ios ./src/native-screen.ts --out ./ios/HomeScreen.swift --no-preview`
 - `elit native generate ir ./src/native-screen.ts --platform android --export screen`
+- `elit wapk pack . --password-env WAPK_PASSWORD`
 - `elit wapk ./app.wapk --runtime node|bun|deno`
-- `elit wapk run ./app.wapk --sync-interval 100 --watcher`
+- `elit wapk run ./app.wapk --password-env WAPK_PASSWORD --sync-interval 100 --watcher`
 - `elit wapk pack . --include-deps`
-- `elit wapk inspect ./app.wapk`
+- `elit wapk inspect ./app.wapk --password-env WAPK_PASSWORD`
 - `elit wapk extract ./app.wapk`
 - `elit desktop wapk ./app.wapk --runtime node|bun|deno --watcher`
+- `elit desktop wapk run ./app.wapk --runtime bun --password-env WAPK_PASSWORD`
 
 Desktop mode notes:
 
@@ -306,8 +308,12 @@ WAPK mode notes:
 - `elit desktop wapk <file.wapk>` and `elit desktop wapk run <file.wapk>` run packaged apps in desktop mode.
 - During run, the archive is expanded into a temporary work directory and changes are synced back to the same `.wapk` file.
 - Use `--sync-interval <ms>` for polling mode, or `--watcher` / `--use-watcher` for event-driven sync.
-- Configure package metadata in `elit.config.*` under `wapk`.
-- See the full example app at `examples/wapk-example`.
+- Use `--password` or, preferably, `--password-env` when packing, inspecting, extracting, or running a locked archive.
+- `inspect` without credentials still reports whether the archive is locked, but it does not print the archive contents.
+- Locked archives stay encrypted when live sync writes changes back into the same `.wapk` file.
+- Configure package metadata in `elit.config.*` under `wapk`, and use `wapk.lock` when you want password-protected archives by default.
+- WAPK stays unlocked by default unless `wapk.lock.password`, `wapk.lock.passwordEnv`, `--password`, or `--password-env` is provided.
+- See [docs/wapk.md](docs/wapk.md) for the full archive guide and `examples/wapk-example` for an end-to-end sample.
 
 ## Config File
 
@@ -380,6 +386,10 @@ The config shape is:
     port?: number;
     env?: Record<string, string | number | boolean>;
     desktop?: Record<string, unknown>;
+    lock?: {
+      password?: string;
+      passwordEnv?: string;
+    };
   };
 }
 ```
@@ -402,6 +412,17 @@ export default {
         basePath: '',
         ssr: () => documentShell,
         api,
+        ws: [
+          {
+            path: '/ws',
+            handler: ({ ws, query }) => {
+              ws.send(JSON.stringify({ type: 'connected', room: query.room || 'general' }));
+              ws.on('message', (message) => {
+                ws.send(message.toString());
+              });
+            },
+          },
+        ],
       },
     ],
   },
@@ -421,6 +442,14 @@ export default {
     root: './dist',
     index: './index.html',
     port: 4173,
+    ws: [
+      {
+        path: '/ws',
+        handler: ({ ws }) => {
+          ws.on('message', (message) => ws.send(message.toString()));
+        },
+      },
+    ],
   },
   test: {
     include: ['testing/unit/**/*.test.ts'],
@@ -460,10 +489,19 @@ export default {
     env: {
       NODE_ENV: 'production',
     },
+    lock: {
+      passwordEnv: 'WAPK_PASSWORD',
+    },
   },
 };
 ```
 
+Notes:
+
+- `dev.ws` and `preview.ws` register global WebSocket endpoints.
+- `clients[].ws` registers client-specific endpoints and prefixes each path with that client's `basePath`.
+- The internal Elit HMR and shared-state socket uses `/__elit_ws`, so do not reuse that path for custom endpoints.
+
 Important details:
 
 - `build` may be a single object or an array. If it is an array, all builds run sequentially.
@@ -473,6 +511,7 @@ Important details:
 - `desktop` config provides defaults for `elit desktop`, `elit desktop run`, `elit desktop build`, and `elit desktop wapk`. Use `desktop.entry` for hybrid defaults, `desktop.native.entry` for native defaults, and `desktop.mode` to choose which one runs by default.
 - `mobile` config provides defaults for `elit mobile init|sync|open|run|build`.
 - `wapk` config is loaded from `elit.config.*`, then package metadata is used as fallback.
+- `wapk.lock.passwordEnv` is the safest reusable way to protect archives without putting the password directly into shell history or committed config.
 - `wapk run` and `desktop wapk run` sync runtime file changes back into the same `.wapk` archive.
 
 ## Browser Patterns
@@ -606,6 +645,49 @@ const server = createDevServer({
 console.log(server.url);
 ```
 
+### Custom WebSocket Endpoints
+
+Server:
+
+```ts
+import { createDevServer } from 'elit/server';
+
+const server = createDevServer({
+  root: '.',
+  open: false,
+  ws: [
+    {
+      path: '/ws',
+      handler: ({ ws, query }) => {
+        ws.send(JSON.stringify({ type: 'connected', room: query.room || 'general' }));
+
+        ws.on('message', (message) => {
+          ws.send(message.toString());
+        });
+      },
+    },
+  ],
+});
+```
+
+Client:
+
+```ts
+const socket = new WebSocket(`ws://${location.host}/ws?room=general`);
+
+socket.addEventListener('message', (event) => {
+  console.log(event.data);
+});
+
+socket.send('hello');
+```
+
+Notes:
+
+- Use `dev.ws` or `preview.ws` for global endpoints.
+- Use `clients[].ws` when each client should expose its own endpoint under its `basePath`.
+- Do not use `/__elit_ws`; Elit reserves that path for internal HMR and shared-state traffic.
+
 ### Shared State Between Server and Client
 
 Client:
@@ -787,6 +869,16 @@ npx elit test --coverage --coverage-reporter text,html
 
 The package also exports `elit/test`, `elit/test-runtime`, and `elit/test-reporter` for advanced use, but most users should stay on the CLI.
 
+## Changelog
+
+Latest release notes live in [CHANGELOG.md](CHANGELOG.md).
+
+Highlights in `v3.5.1`:
+
+- Added first-class custom WebSocket endpoints for `dev`, `preview`, and `clients[]` config.
+- Moved internal HMR and shared-state traffic to `/__elit_ws` so custom endpoints do not collide with Elit internals.
+- Tightened cross-runtime WebSocket path matching so root endpoints no longer swallow every upgrade request.
+
 ## Good Defaults For Generated Code
 
 When writing new Elit code, these defaults are usually correct:

package/dist/build.d.mts

@@ -1,4 +1,4 @@
-import { B as BuildOptions, a as BuildResult } from './server-DpnTyF7I.mjs';
+import { B as BuildOptions, a as BuildResult } from './server--YFoC6ln.mjs';
 import './http.mjs';
 import 'node:events';
 import './ws.mjs';