@webqit/webflo 0.20.4-next.1 → 0.20.4-next.3

package/package.json

@@ -12,7 +12,7 @@
     "vanila-javascript"
   ],
   "homepage": "https://webqit.io/tooling/webflo",
-  "version": "0.20.4-next.1",
+  "version": "0.20.4-next.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -33,6 +33,9 @@
     "site:build": "vitepress build site",
     "site:preview": "vitepress preview site --port 4173"
   },
+  "exports": {
+    "./apis": "./src/runtime-pi/apis.js"
+  },
   "bin": {
     "webflo": "src/webflo-cli.js",
     "webflo-certbot-http-auth-hook": "src/services-pi/cert/http-auth-hook.js",
@@ -73,23 +76,5 @@
   "maintainers": [
     "Oxford Harrison <oxharris.dev@gmail.com>"
   ],
-  "contributors": [],
-  "funding": {
-    "type": "patreon",
-    "url": "https://patreon.com/ox_harris"
-  },
-  "badges": {
-    "list": [
-      "npmversion",
-      "npmdownloads",
-      "patreon"
-    ],
-    "config": {
-      "patreonUsername": "ox_harris",
-      "githubUsername": "webqit",
-      "githubRepository": "webflo",
-      "githubSlug": "webqit/webflo",
-      "npmPackageName": "@webqit/webflo"
-    }
-  }
+  "contributors": []
 }

package/site/.vitepress/config.ts

@@ -46,7 +46,7 @@ const config = {
                         { text: 'Rendering', link: '/docs/concepts/rendering' },
                         { text: 'Templates', link: '/docs/concepts/templates' },
                         { text: 'State Management', link: '/docs/concepts/state' },
-                        { text: 'Request/Response Lifecycle', link: '/docs/concepts/request-response' },
+                        { text: 'Requests & Responses', link: '/docs/concepts/requests-responses' },
                         { text: 'Webflo Realtime', link: '/docs/concepts/realtime' },
                     ]
                 },

package/site/docs/concepts/realtime.md

@@ -20,17 +20,17 @@ event.waitUntilNavigate();
 ```
 
 ```js
-event.client.addEventListener('message', handle);
-event.client.postMessage({ message: 'You seem to be typing something.' });
+event.client.addEventListener("message", handle);
+event.client.postMessage({ message: "You seem to be typing something." });
 ```
 
 ```js
-const result = await event.user.confirm({ message: 'Should we proceed?' });
-const result = await event.user.prompt({ message: 'What is your name?' });
+const result = await event.user.confirm({ message: "Should we proceed?" });
+const result = await event.user.prompt({ message: "What is your name?" });
 ```
 
 ```js
-const { channel, leave } = event.client.enterChannel('test-channel');
+const { channel, leave } = event.client.enterChannel("test-channel");
 ```
 
 ## The Traditional Setup
@@ -124,7 +124,7 @@ The **primary** realtime API here is `event.client` — a Webflo `MessagePort` s
 
 ```js
 export default async function (event) {
-  event.client.postMessage({ hello: 'world' });
+  event.client.postMessage({ hello: "world" });
 }
 ```
 
@@ -138,10 +138,10 @@ These HTTP clients or handlers are the _Port B_.
 The primary realtime API here is `liveResponse.background` — the same Webflo `MessagePort` interface as `event.client`, supporting things like: `.postMessage()`, `.addEventListener()`, etc.
 
 ```js
-const response = await fetch('https://api.example.com/data');
-const liveResponse = LiveResponse.from(response);
+const response = await fetch("https://api.example.com/data");
+const liveResponse = await LiveResponse.from(response);
 
-liveResponse.background.addEventListener('message', (message) => {
+liveResponse.background.addEventListener("message", (message) => {
   console.log(message);
 });
 ```
@@ -172,7 +172,7 @@ The `app.background` port is also a _multi-port_ hub housing all _active_ backgr
 Every interaction on this API is thus an interaction over all active realtime conversations.
 
 ```js
-app.background.addEventListener('message', (message) => {
+app.background.addEventListener("message", (message) => {
   console.log(message);
 });
 ```
@@ -193,8 +193,8 @@ export default async function (event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
   const response = await next();
-  const liveResponse = LiveResponse.from(response);
-  liveResponse.background.addEventListener('message', (message) => {
+  const liveResponse = await LiveResponse.from(response);
+  liveResponse.background.addEventListener("message", (message) => {
     console.log(message);
   });
 
@@ -209,7 +209,7 @@ The handler’s own `event.client` port remains its own _Port A_ for communicati
 ---
 
 ::: tip
-While not explicitly mentioned, external Webflo servers are just as accessible and interactive as the local server. A server-to-server interaction, for example, is just a matter of `LiveResponse.from(await fetch('https://api.example.com/data'))`.
+While not explicitly mentioned, external Webflo servers are just as accessible and interactive as the local server. A server-to-server interaction, for example, is just a matter of `await LiveResponse.from(await fetch('https://api.example.com/data'))`.
 :::
 
 ## Entering Background Mode
@@ -230,7 +230,7 @@ event.client.postMessage({ progress: 10 });
 2. or achieving the same through higher-level APIs like `event.user.confirm()`:
 
 ```js
-const result = await event.user.confirm({ message: 'Are you sure?' });
+const result = await event.user.confirm({ message: "Are you sure?" });
 ```
 
 ### _Handler returns a response and explicitly marks it **not done**_
@@ -278,9 +278,9 @@ event.respondWith(
 ```js
 event.respondWith(data, async ($data /* reactive copy of data */) => {
   await new Promise((resolve) => setTimeout(resolve, 1000));
-  $data.someProp = 'someValue';
+  $data.someProp = "someValue";
   await new Promise((resolve) => setTimeout(resolve, 1000));
-  $data.someProp = 'someOtherValue';
+  $data.someProp = "someOtherValue";
 });
 ```
 
@@ -294,7 +294,7 @@ A handler may return a `Generator` object by either:
 export default async function* (event) {
   yield data1;
   yield new Response(data2);
-  yield new LiveResponse(null, { headers: { Location: '/' } });
+  yield new LiveResponse(null, { headers: { Location: "/" } });
 }
 ```
 
@@ -339,7 +339,9 @@ Webflo knows to switch the connection to background mode in all the above cases.
 - **Webflo simply fulfills the intent of however a handler works**.
   :::
 
-## Real-world Examples
+## Real-World Examples
+
+Below are some examples of how Webflo's realtime features work in action.
 
 ### Live Responses
 
@@ -350,14 +352,14 @@ This handler returns a `LiveResponse` whose body starts as `{ step: 1 }` and is
 **_Result_:** The page first renders step: 1, then updates to step: 2 after ~200ms.
 
 ```js
-import { LiveResponse } from '@webqit/webflo';
+import { LiveResponse } from '@webqit/webflo/apis';
 ```
 
 ```js
 export async function GET(event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
-  const res = LiveResponse.from({ step: 1 }, { done: false });
+  const res = await LiveResponse.from({ step: 1 }, { done: false });
   setTimeout(() => res.replaceWith({ step: 2 }), 200); // [!code highlight]
 
   return res;
@@ -371,7 +373,7 @@ This handler returns a skeleton object immediately for fast page load and then b
 **_Result_:** The UI renders a skeleton first, then progressively fills in as the object tree is built from the server.
 
 ```js
-import { Observer } from '@webqit/observer';
+import { Observer } from '@webqit/webflo/apis';
 ```
 
 ```js
@@ -380,30 +382,30 @@ export async function GET(event, next) {
 
   const data = {
     menu: [
-      { name: 'Home', href: '/' },
-      { name: 'About', href: '/about' },
-      { name: 'Contact', href: '/contact' },
+      { name: "Home", href: "/" },
+      { name: "About", href: "/about" },
+      { name: "Contact", href: "/contact" },
     ],
     content: {
-      header: 'Loading...',
+      header: "Loading...",
       body: [],
     },
   };
 
   event.waitUntil(
     new Promise(async (resolve) => {
-      const someData = await fetch('https://api.example.com/data');
-      Observer.set(data.content, 'header', someData.header);
+      const someData = await fetch("https://api.example.com/data");
+      Observer.set(data.content, "header", someData.header);
 
       Observer.proxy(data.content.body).push(
-        { text: 'Inventory 1:' + someData.items[0] },
-        { text: 'Inventory 2:' + someData.items[1] }
+        { text: "Inventory 1:" + someData.items[0] },
+        { text: "Inventory 2:" + someData.items[1] }
       );
 
-      const someData2 = await fetch('https://api.example.com/data2');
+      const someData2 = await fetch("https://api.example.com/data2");
       Observer.proxy(data.content.body).push(
-        { text: 'Inventory 3:' + someData2.items[0] },
-        { text: 'Inventory 4:' + someData2.items[1] }
+        { text: "Inventory 3:" + someData2.items[0] },
+        { text: "Inventory 4:" + someData2.items[1] }
       );
 
       resolve();
@@ -448,12 +450,12 @@ export async function POST(event, next) {
   // Initiate response
   event.respondWith({ step: 1 }, { done: false });
   // Make API call
-  await fetch('https://api.example.com/data');
+  await fetch("https://api.example.com/data");
   // Update response
   event.respondWith({ step: 2 }, { done: false });
 
   // Redirect
-  event.respondWith(null, { status: 302, headers: { Location: '/done' } }); // [!code highlight]
+  event.respondWith(null, { status: 302, headers: { Location: "/done" } }); // [!code highlight]
 }
 ```
 
@@ -469,7 +471,7 @@ This handler pauses request processing to interact with the user before proceedi
 export async function DELETE(event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
-  const message = 'This item will be permanently deleted. Are you sure?';
+  const message = "This item will be permanently deleted. Are you sure?";
   const answer = await event.user.confirm({ message }); // [!code highlight]
   if (answer?.data === true) {
     // proceed
@@ -485,7 +487,7 @@ Customization is as simple as intercepting these via `preventDefault()` to rende
 
 ```javascript
 // Intercept at window.webqit.app.background
-window.webqit.app.background.addEventListener('prompt', (e) => {
+window.webqit.app.background.addEventListener("prompt", (e) => {
   e.preventDefault(); // [!code highlight]
   customDialog(e.data.message).then((result) => {
     // Reply to the request on the provided port
@@ -507,17 +509,17 @@ export async function GET(event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
   // Channel ID - must tally with the client-side ID
-  const channelID = 'test-channel';
+  const channelID = "test-channel";
 
   const { channel, leave } = event.client.enterChannel(channelID, {
     // Optionally annotate user's messages with user's name
-    resolveData: (message) => ({ ...message, user: 'sample name' }),
+    resolveData: (message) => ({ ...message, user: "sample name" }),
   });
 
   event.waitUntilNavigate(); // keep open
-  event.client.addEventListener('close', (e) => {
+  event.client.addEventListener("close", (e) => {
     //e.preventDefault();
-    console.log('Chat closed');
+    console.log("Chat closed");
   });
 }
 ```
@@ -529,15 +531,15 @@ export default async function (event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
   // Initialize states
-  const data = { messageTrail: [{ message: 'Beginning of chat...' }] };
+  const data = { messageTrail: [{ message: "Beginning of chat..." }] };
   await event.respondWith(data, { done: false }); // [!code highlight]
 
   // The messaging part
   const response = await next(); // Call server
-  const chatPort = LiveResponse.from(response).background;
+  const chatPort = (await LiveResponse.from(response)).background;
 
   // Channel ID - must tally with the server-side ID
-  const channelID = 'test-channel';
+  const channelID = "test-channel";
 
   // Listen to upstream messages - from others in the same channel
   chatPort.addEventListener(`${channelID}:message`, (e) => {
@@ -604,17 +606,19 @@ export default async function (event, next) {
 
 ## Appendix A – The Realtime Lifecycle
 
+The realtime lifecycle — from handshake to termination — can be summarized as follows. Note that this is the model between any two ports — Port A and Port B, not just between the client and the server, as that's only typical.
+
 ```mermaid
 sequenceDiagram
-  participant Browser
-  participant Handler
-  Browser->>Handler: HTTP request
-  Handler-->>Browser: Initial Response (or a Temporary 202 Accepted) <br>+ X-Background-Messaging-Port
-  Browser-->>Handler: Connect (WebSocket / Broadcast / MessageChannel)
-  Note over Browser,Handler: Background mode established
-  Handler-->>Browser: Messages, updates, dialogs, etc.
-  Browser-->>Handler: Replies, requests, etc.
-  Browser<<-->>Handler: Termination
+  participant Port A
+  participant Port B
+  Port A->>Port B: HTTP request
+  Port B-->>Port A: Initial Response (or a Temporary 202 Accepted) <br>+ X-Background-Messaging-Port
+  Port A-->>Port B: Connect (WebSocket / Broadcast / MessageChannel)
+  Note over Port A,Port B: Background mode established
+  Port B-->>Port A: Messages, updates, dialogs, etc.
+  Port A-->>Port B: Replies, requests, etc.
+  Port A<<-->>Port B: Termination
 ```
 
 ### The Handshake
@@ -622,7 +626,7 @@ sequenceDiagram
 On entering background mode, Webflo initiates a handshake sequence as follows:
 
 1. Webflo gives the initial response a unique `X-Background-Messaging-Port` header that tells the client to connect in the background after rendering the initial response.
-   > If the scenario is case `1.` above happening _before_ yielding a response, Webflo sends a temporary `202 Accepted` response to the client carrying this header.
+   > If the scenario is that the handler tiggers `event.client` messaging _before_ yielding a response, Webflo sends a temporary `202 Accepted` response to the client carrying this header.
 2. The client reads that header and opens the background channel.
    > If the client fails to connect within the handshake window, Webflo abandons the wait and concludes the request normally.
 3. On connecting, both sides resume the same request context — now in live mode.

package/site/docs/concepts/{request-response.md → requests-responses.md}

@@ -1,4 +1,4 @@
-# Request/Response Lifecycle
+# Requests & Responses
 
 This page explains how Webflo orchestrates each interaction from request to response, and how you can hook into various stages, including realtime.
 

package/site/docs/concepts/state.md

@@ -1,4 +1,4 @@
-# State Management
+# State, Mutation, & Reactivity
 
 Webflo’s approach to state is refreshingly simple: your UI state is just a plain JavaScript object. When your server handler returns data, it becomes available as `document.bindings.data` for your templates and UI. No special syntax, no framework-specific magic—just JavaScript you already know.
 

package/site/docs/getting-started.md

@@ -22,23 +22,23 @@ This documentation is a work in progress. Please expect some rough edges, missin
 
 ## Installation
 
-### Option 1: Global Installation (Recommended)
+### Option 1: Local Installation (Recommended)
 
-Install Webflo globally to use the CLI from anywhere:
+Install Webflo as a dependency in your project:
 
 ```bash
-npm install -g @webqit/webflo
+npm install @webqit/webflo
 ```
 
-### Option 2: Local Installation
+### Option 2: Global Installation
 
-Install Webflo as a dependency in your project:
+Install Webflo globally to use the CLI from anywhere:
 
 ```bash
-npm install @webqit/webflo
+npm install -g @webqit/webflo
 ```
 
-The scope you choose will determine how you run Webflo commands. The Webflo commands in the rest of this page will show in both `global` and `local` styles.
+The scope you choose will determine how you run Webflo commands. The Webflo commands in the rest of this page will show in both `local` and `global` styles.
 
 ## Creating a New Project
 
@@ -46,14 +46,14 @@ Webflo provides a CLI command to scaffold new projects:
 
 ::: code-group
 
-```bash [global]
-webflo init my-webflo-app
-```
-
 ```bash [local]
 npx webflo init my-webflo-app
 ```
 
+```bash [global]
+webflo init my-webflo-app
+```
+
 :::
 
 This will create a new directory called `my-webflo-app` with a basic Webflo project structure.
@@ -70,28 +70,28 @@ The above command could take a project title and project description too:
 
 ::: code-group
 
-```bash [global]
-webflo init my-webflo-app "My Webflo App" "My first ever Webflo app"
-```
-
 ```bash [local]
 npx webflo init my-webflo-app "My Webflo App" "My first ever Webflo app"
 ```
 
+```bash [global]
+webflo init my-webflo-app "My Webflo App" "My first ever Webflo app"
+```
+
 :::
 
 And you can specify a template to use:
 
 ::: code-group
 
-```bash [global]
-webflo init my-webflo-app --template=web
-```
-
 ```bash [local]
 npx webflo init my-webflo-app --template=web
 ```
 
+```bash [global]
+webflo init my-webflo-app --template=web
+```
+
 :::
 
 The default is: `web`.
@@ -151,11 +151,11 @@ The generated `package.json` for your project will include scripts like `dev`, `
   "scripts": {
     // Builds HTML templates and client bundles into public/assets
     "build:html": "oohtml bundle --recursive --outdir=public/assets --auto-embed=app",
-    "build:js": "webflo generate::client --recursive --outdir=public/assets --auto-embed",
+    "build:js": "webflo build --client --worker --server --recursive --outdir=public/assets --auto-embed",
     // Production build: runs both steps
     "build": "npm run build:html && npm run build:js",
     // Development server with auto-rebuilds and fine-grained HMR
-    "dev": "webflo start --dev --build-sensitivity=2",
+    "dev": "webflo start --dev --build-sensitivity=1",
     // Production server
     "start": "webflo start"
   },
@@ -181,7 +181,7 @@ You can customize as necessary.
 ::: info Scripts & customization
 - You can customize `build:html` or `build:js` scripts if you need finer control
 - Add a `build:css` script if your CSS requires a build step; it'll be called in dev mode as necessary on CSS file changes
-- Adjust dev mode's rebuild frequency for assets with `--build-sensitivity` (e.g., `--build-sensitivity=2` — to defer rebuild until page reload; `0` — to turn off)
+- Adjust dev mode's rebuild frequency for assets with `--build-sensitivity` (e.g., `--build-sensitivity=1` — to defer rebuild until page reload; `0` — to turn off)
 :::
 
 ## Running Your Application
@@ -194,14 +194,14 @@ Start the development server:
 
 ::: code-group
 
-```bash [global]
-webflo start --dev
-```
-
 ```bash [npm]
 npm run dev
 ```
 
+```bash [global]
+webflo start --dev
+```
+
 :::
 
 The server starts on `http://localhost:3000` by default.
@@ -220,14 +220,14 @@ The server starts on `http://localhost:3000` by default.
 
 ::: code-group
 
-```bash [global]
-webflo start --dev --open --port 8080
-```
-
 ```bash [npm]
 npm run dev -- --open --port 8080
 ```
 
+```bash [global]
+webflo start --dev --open --port 8080
+```
+
 :::
 
 ### Webflo Build
@@ -254,14 +254,14 @@ Start the production server when ready:
 
 ::: code-group
 
-```bash [global]
-webflo start
-```
-
 ```bash [npm]
 npm start
 ```
 
+```bash [global]
+webflo start
+```
+
 Your app runs in production mode. Production can be in any filesystem-enabled JavaScript runtime.
 
 ::: warning Production differences
@@ -354,22 +354,22 @@ You’ve:
 
 ```bash
 # Initialize a new project
-webflo init <project-name>
+npx webflo init <project-name>
 
 # Start development server
-webflo start --dev
+npx webflo start --dev
 
 # Start production server
-webflo start
+npx webflo start
 
 # Build for production
-webflo build
+npx webflo build
 
 # Configure Webflo
-webflo config
+npx webflo config
 
 # View help
-webflo --help
+npx webflo --help
 ```
 
 </details>

package/src/{Context.js → CLIContext.js}

@@ -1,4 +1,4 @@
-export class Context {
+export class CLIContext {
 
     constructor(dict, CD = null) {
         // dict can be plain object or some Context instance itself
@@ -14,15 +14,16 @@ export class Context {
         }
     }
 
-    get name() {
-        return 'webflo';
-    }
-
     // create
     static create(...args) {
         return new this(...args);
     }
 
+    // name
+    get name() {
+        return 'webflo';
+    }
+
     // CWD
     get CWD() {
         return this.dict.CWD || '';
@@ -33,7 +34,7 @@ export class Context {
         return this.dict.meta || {};
     }
 
-    // app
+    // appMeta
     get appMeta() {
         return this.dict.appMeta || {};
     }
@@ -63,10 +64,10 @@ export class Context {
 
     // logger
     get logger() {
-        return this.dict.logger;
+        return this.dict.logger || console;
     }
 
     set logger(value) {
         Object.defineProperty(this.dict, 'logger', { value } );
     }
-}
+}

package/src/build-pi/esbuild-plugin-livejs-transform.js

@@ -0,0 +1,35 @@
+import Fs from 'fs/promises';
+//import { transformQuantum } from '@webqit/quantum-js';
+
+export function LiveJSTransform() {
+    return {
+        name: 'livejs-transform',
+        setup(build) {
+            build.onLoad({ filter: /\.(js|mjs|ts|jsx|tsx)$/ }, async (args) => {
+                let code = await Fs.readFile(args.path, 'utf8');
+
+                //console.log('LiveJS -- transform:', args);
+
+                // super dirty detection
+                if (!/\bquantum\s+function\b/.test(code) &&
+                    !/\basync\s+quantum\s+function\b/.test(code)) {
+                    return { contents: code, loader: 'default' };
+                }
+
+                
+                console.log('LiveJS transform:', args.path);
+
+                return { contents: code, loader: 'default' };
+                const result = await transformQuantum(code, {
+                    filename: args.path,
+                    sourceMaps: true
+                });
+
+                return {
+                    contents: result.code,
+                    loader: 'js' // or 'ts' if you want esbuild TS transform after
+                };
+            });
+        }
+    };
+}