@webqit/webflo 0.20.12-next.0 → 0.20.13-next.0

package/package.json

@@ -12,7 +12,7 @@
     "vanila-javascript"
   ],
   "homepage": "https://webqit.io/tooling/webflo",
-  "version": "0.20.12-next.0",
+  "version": "0.20.13-next.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/site/docs/concepts/realtime.md

@@ -8,7 +8,7 @@ Webflo apps work this way by default.
 They're powered by a rich set of APIs designed for every use case:
 
 ```js
-return new LiveResponse(data, { done: false });
+return new LiveResponse({ progress: 10 }, { done: false });
 ```
 
 ```js
@@ -16,6 +16,7 @@ event.respondWith({ progress: 10 }, { done: false });
 ```
 
 ```js
+event.waitUntil(promise);
 event.waitUntilNavigate();
 ```
 
@@ -153,7 +154,7 @@ Typical Port B clients in Webflo are:
 
 ::: info LiveResponse
 `LiveResponse` is the "live" version of the standard `Response` API.
-It extends the native `Response` object with a live body, headers, and status — all of which can be mutated in-place.
+It extends the native `Response` object to support mutable response – with a live body, headers, and status that can be mutated in-place.
 :::
 
 #### The App UI
@@ -192,8 +193,13 @@ The background connection comes along with the upstream response obtained via `n
 export default async function (event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
+  // Since next.stepname is falsey, this next() call falls through to the server. Response is thus a normal HTTP response from the server
   const response = await next();
+
+  // LiveResponse.from() converts the response to a live response using the connection details embedded in the original response
   const liveResponse = await LiveResponse.from(response);
+
+  // The background port is then used to listen to messages from the upstream
   liveResponse.background.addEventListener("message", (message) => {
     console.log(message);
   });
@@ -209,13 +215,13 @@ 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 `await LiveResponse.from(await fetch('https://api.example.com/data'))`.
+While not explicitly mentioned, external Webflo servers – like Webflo-based API backends – are just as accessible and interactive as the local Webflo instance. A server-to-server request, for example, supports the same live interaction as a normal client-server request. It is just a matter of `await LiveResponse.from(await fetch('https://api.example.com/data'))`.
 :::
 
 ## Entering Background Mode
 
 A handler **enters background mode** when it responds to a request interactively as any of the below scenarios.
-Webflo automatically upgrades the connection to a realtime connection — initiating the _handshake sequence_ with the client and keeping the communication open until _termination_ is triggered — as in [the Realtime Lifecycle](#appendix-a-–-the-realtime-lifecycle).
+Webflo automatically upgrades the connection to a realtime connection — initiating the _handshake sequence_ with the client and keeping the communication open until _termination_ is triggered — as detailed in [the Realtime Lifecycle](#appendix-a-–-the-realtime-lifecycle).
 
 ### _Handler sends a message at any point in its lifecycle_
 
@@ -227,12 +233,14 @@ A handler may send a message at any point in its lifecycle by either:
 event.client.postMessage({ progress: 10 });
 ```
 
-2. or achieving the same through higher-level APIs like `event.user.confirm()`:
+2. or doing the equivalent via higher-level APIs like `event.user.confirm()`:
 
 ```js
 const result = await event.user.confirm({ message: "Are you sure?" });
 ```
 
+The handler automatically enters background mode.
+
 ### _Handler returns a response and explicitly marks it **not done**_
 
 A handler may return a response and explicitly mark it **not done** by calling `event.respondWith()` (or returning `LiveResponse`) with `{ done: false }`:
@@ -245,6 +253,8 @@ event.respondWith(data, { done: false });
 return new LiveResponse(data, { done: false });
 ```
 
+The handler automatically enters background mode.
+
 ### _Handler holds down the event lifecycle via promises_
 
 A handler may hold down the event lifecycle via promises by either:
@@ -252,12 +262,12 @@ A handler may hold down the event lifecycle via promises by either:
 1. explicitly calling `event.waitUntil()` or `event.waitUntilNavigate()` before returning a response:
 
 ```js
-event.waitUntilNavigate();
+event.waitUntil(new Promise(() => {}));
 event.respondWith(data);
 ```
 
 ```js
-event.waitUntil(new Promise(() => {}));
+event.waitUntilNavigate();
 return data;
 ```
 
@@ -284,6 +294,8 @@ event.respondWith(data, async ($data /* reactive copy of data */) => {
 });
 ```
 
+The handler automatically enters background mode.
+
 ### _Handler returns a `Generator` object_
 
 A handler may return a `Generator` object by either:
@@ -310,12 +322,16 @@ export default async function (event) {
 }
 ```
 
-### _Handler returns a `State` object_
+The handler automatically enters background mode.
 
-A handler may return a `State` object by declaring a `live` function:
+### _Handler returns a `LiveProgramHandle` object_
+
+A handler may return a `LiveProgramHandle` object by being a ["live" function](https://github.com/webqit/use-live):
 
 ```js
-export default async live function(event) {
+export default async function(event) {
+    "use live";
+
     const data = { progress: 0 };
 
     setInterval(() => {
@@ -326,7 +342,7 @@ export default async live function(event) {
 }
 ```
 
-The `live` keyword is a shorthand for defining a quantum function that returns a `State` object.
+The handler automatically enters background mode.
 
 ---
 
@@ -359,7 +375,7 @@ import { LiveResponse } from '@webqit/webflo/apis';
 export async function GET(event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
 
-  const res = await LiveResponse.from({ step: 1 }, { done: false });
+  const res = new LiveResponse({ step: 1 }, { done: false });
   setTimeout(() => res.replaceWith({ step: 2 }), 200); // [!code highlight]
 
   return res;
@@ -368,7 +384,7 @@ export async function GET(event, next) {
 
 #### Example — Mutate state in place
 
-This handler returns a skeleton object immediately for fast page load and then builds the object tree progressively as data arrives; the UI reflects every step of the object's construction.
+This handler returns a skeleton object immediately for fast page load and then builds the object tree progressively as it fetches data from the relevant sources; the UI reflects every step of the object's construction.
 
 **_Result_:** The UI renders a skeleton first, then progressively fills in as the object tree is built from the server.
 
@@ -483,7 +499,7 @@ export async function DELETE(event, next) {
 
 The Webflo UI client shows the dialog (native `confirm()/prompt()` or custom UI if configured) and returns the user's response.
 
-Customization is as simple as intercepting these via `preventDefault()` to render your own modals.
+The prompt UI that the user sees can be customized in as simple as intercepting these via `app.background.addEventListener("prompt", ...)` to render your own modals.
 
 ```javascript
 // Intercept at window.webqit.app.background
@@ -504,6 +520,8 @@ These handlers establish a chat channel and broadcast messages to all participan
 
 **_Result_:** Messages appear in the chat trail every few seconds; incoming vs outgoing messages are styled differently.
 
+On the server:
+
 ```js
 export async function GET(event, next) {
   if (next.stepname) return await next(); // The conventional delegation line
@@ -524,7 +542,7 @@ export async function GET(event, next) {
 }
 ```
 
-Then on the client:
+On the client:
 
 ```js
 export default async function (event, next) {

package/site/docs/concepts/routing.md

@@ -73,7 +73,7 @@ Use these for conditional delegation, or per-segment rules.
 ### Your First Handler (Again)
 
 Your application's routes may be designed with as many or as few handlers as desired.<br>
-In fact, if it calls for it, the contextual parameters `next.stepname` and `next.pathname` totally make it possible to fit routing logic into a single handler.
+In fact, if it calls for it, it is possible to fit routing logic for multiple routes into a single handler – using the contextual parameters `next.stepname` and `next.pathname` for conditional branching.
 
 ```js
 export default function(event, next) {
@@ -142,7 +142,7 @@ export default async function () {
 ```
 
 * The request enters at the top level (`app/handler.server.js`).
-* Each handler may perform logic and either return a response or call `next()`.
+* Each handler performs logic and either return a response or call `next()`.
 * `next()` advances the request to the next directory level in the URL.
 * Delegation stops when there are no further segments (`next.stepname` is falsy).
 
@@ -152,7 +152,7 @@ export default async function () {
 Beyond the default parent-child flow, a handler can explicitly **reroute** a request to another path within the app by calling `next({ redirect: path })`, or `next(path)`, for short.
 
 This is simulated below for a URL like `/products/stickers`.<br>
-Here, the root handler conditionally reroutes the request to `/api/inventory`, all within the same app.
+Here, the root handler conditionally reroutes the request to `/api/inventory`, as an internal call.
 
 ```js
 // app/handler.server.js
@@ -236,9 +236,9 @@ Through this mechanism, Webflo lets handlers **reshape requests or responses inl
 
 ## The Client-Server Flow
 
-In addition to the handler-to-handler model, Webflo also has the **client-server flow** which represents the _vertical_ flow of the same request through the application stack (client → server).
+In addition to the handler-to-handler model, Webflo also has the **client-server flow** as the request travels through the application stack – from the client to the server.
 
-Webflo follows a model that supports request handling and routing at all three layers in this stack: the browser window layer (**client**), the service worker layer (**worker**), the server layer (**server**).
+Webflo lets you do routing at all three layers in this flow: in the browser window (**client**), in the service worker (**worker**), and on the server (**server**).
 
 Handlers fit into this stack by their filename suffix:
 
@@ -251,7 +251,7 @@ handler.js        → Executes anywhere (default handler)
 
 Together, these form a vertical routing pipeline.
 
-Below is a conceptual diagram of how a navigation request flows donw the layers:
+Below is a conceptual diagram of how a navigation request flows down the routing layers:
 
 ```js
 ┌─────────────┐   │   ┌─────────────────────────────────┐
@@ -265,17 +265,16 @@ Below is a conceptual diagram of how a navigation request flows donw the layers:
                   ▼   └─────────────────────────────────┘
 ```
 
-Handlers across this vertical stack are optional; if a layer-specific file doesn’t exist, Webflo automatically falls back to the unsuffixed one `handler.js`,
-if defined. Otherwise, the request continues to the next layer. Each request gets a graceful path from local logic to remote fulfillment.
+Routing in any of these layers is optional; if a layer-specific handler does not exist, Webflo checks for the unsuffixed one `handler.js`,
+if defined. Otherwise, the request continues to the next layer until reaching the server.
 
-As with the horizontal flow, each layer may intercept, fulfill, or delegate down the request.<br>
-Handlers at higher layers (like the browser) are able to respond instantly or hand the request down the stack.
+Handlers at higher routing layers (like the browser) are able to respond instantly or hand the request down the stack.
 
 This model grants profound flexibility — enabling progressive enhancement, offline support, and universal routing, all through the same `next()` interface.
 
 ### Layer Semantics
 
-These layers are differentiated by various factors and use cases.
+These routing layers are differentiated by their scope and use cases.
 
 | Scope                  | Purpose                                        | Typical Usage                               |
 | :--------------------- | :--------------------------------------------- | :------------------------------------------ |
@@ -286,7 +285,7 @@ These layers are differentiated by various factors and use cases.
 
 #### Client-Side Handlers
 
-Client handlers intercept navigations directly in the browser — the first layer that sees user-initiated requests.
+Client-side route handlers intercept user navigations directly in the browser — the first layer that sees user-initiated requests.
 
 ```js
 // app/handler.client.js
@@ -305,13 +304,13 @@ export default async function (event, next) {
 * Optionally calls `next()` to delegate the request
 
 ::: info Handler Lifecycle
-- Client handlers begin their lifecycle *after* the initial page load.
+- Client-side handlers begin their lifecycle *after* the initial page load.
 - They therefore cannot intercept the first page load or page reloads.
 :::
 
 #### Worker-Side Handlers
 
-Worker handlers run in the Service Worker context, bridging offline and network behavior.
+Worker-side route handlers run in the Service Worker context, bridging offline and network behavior.
 They are the connective tissue between local interactivity and remote resources.
 
 ```js
@@ -335,14 +334,14 @@ export default async function (event, next) {
 * Can delegates to the server when offline handling isn’t possible
 
 ::: info Handler Lifecycle
-- Worker handlers start intercepting once the app’s Service Worker is installed and activated.
+- Worker-side handlers start intercepting once the app’s Service Worker is installed and activated.
 - They therefore cannot intercept the very first page load that installs the app.
 - They continue working even when the page isn’t open, making them ideal for offline logic.
 :::
 
 #### Server-Side Handlers
 
-Server handlers perform the heavy lifting — database queries, integrations, etc.
+Server-side route handlers perform the heavy lifting — database queries, integrations, etc.
 They represent the final dynamic layer before static content resolution.
 
 ```js
@@ -362,7 +361,7 @@ export default async function (event, next) {
 
 #### Universal Handlers
 
-Universal handlers (`handler.js`) are handlers declared without any layer binding. They represent the default handler for a route. And they imply logic that can run anywhere in the client-server stack.
+Universal route handlers (`handler.js`) are handlers declared without any layer binding. They represent the default handler for a route. And they imply logic that can run anywhere in the client-server stack.
 They execute wherever no layer-specific handler exists for the current layer, making them perfect for universal logic.
 
 ```js
@@ -543,7 +542,8 @@ export default async function (event, next) {
 export default async function (event, next) {
     // Using event.user.isSignedIn() to check authentication
     if (!await event.user.isSignedIn()) {
-        return new Response(null, { status: 302, headers: { Location: '/login' } });
+        await event.redirect('/login');
+        return;
     }
     return next();
 }