@webqit/webflo 0.11.61 → 0.20.2-next.0

package/site/docs.md

@@ -0,0 +1,100 @@
+# Webflo <br>— A Web-Native Framework for the Next Gen
+
+_Build the full spectrum of modern apps — backends, frontends, offline-first, and realtime apps — on raw platform power._
+
+Welcome to the docs.
+
+## What is Webflo
+
+Webflo is a web-native framework that lets you build backends, frontends, offline-first, and realtime apps absurdly fast.
+
+"Web-native." The cheatcode, if you caught it.<br>
+Just programming fundamentals and raw platform power, shipped in a framework.
+Modern apps — their sophistication and scale — solved from the foundation up.
+
+## Why Webflo
+
+Webflo shares the same broad use cases as traditional frameworks, but it is designed on an entirely different premise:
+**walk the traditional framework ladder back to programming fundamentals and sheer platform capabilities** — not merely to align with web standards, **but to put the foundations to work in new ways**. From JavaScript to HTML, to the web's transport layer, we took existing fundamentals and built new ones — to give developers less machinery, more leverage.
+
+**An engineer’s tour…**
+
+### Mutation-Based Reactivity
+
+At the foundation is an all-new reactive model: **mutation-based reactivity**, powered by the [Observer API](/docs/tech-stack#the-observer-api). With this model, Webflo anchors itself on JavaScript’s direct mutation semantics and makes it its own engine of reactivity across the whole stack — server, worker, and client. Reactivity just works as program state changes.
+This means:
+
+* **State is just objects and arrays**. With reactivity solved at the object level, no need for stores, hooks, signals, proxies, reducers, or container types. The object you see _is_ the state.
+* **Mutation becomes the shared language of reactivity across the system** — whether on the server, the service worker, or the UI.
+* **With no layers of indirection, mental model stays simple**. At any given time, you're simply either making mutations or observing mutations — exactly as you would without any framework.
+
+This enables **a new generation of apps that entirely avoid the traditional state scaffolding and the inherent cost of forbidding mutability in a mutable world as JavaScript**.
+
+### Realtime Over HTTP
+
+Webflo extends the HTTP request/response model with realtime capabilities that let request handlers opt into an interactive, realtime channel with the client — exposed as `event.client`. Webflo automatically upgrades the underlying transport and manages the request lifecycle.
+You get a capable transport layer that can be used for many things. Webflo builds on that to enable:
+
++ **A multi-stage response model via `LiveResponse`**. Send multiple responses at different stages of request processing: `liveResponse.replaceWith()`, `event.respondWith()`, etc. Clients swap state and rerender accordingly.
++ **Differential, live state over the wire**. Share live state with the client and mutate it in place as you deem fit: `Observer.set(liveResponse.body, name, value)`, `Observer.proxy(liveResponse.body.items).push(item)`, etc. Clients preserve state and reflect diffs. Application state goes fullstack.
++ **Interactive request handling**. Pause request processing to interact with the user as the need may arise: `event.user.confirm()`, `event.user.prompt()`, etc. Clients initiate the corresponding dialog with the user and reply.
+
+Together with the `event.client` API itself, you get a unified surface for many different realtime apps — collaboration, multi-device presence, multiplayer, streaming progress, and more — with no extra wiring or protocols.
+
+### HTML for the Modern UI
+
+Webflo brings HTML into the application authoring equation as its direct UI language — instead of as compile target. It converges on a design that leaves the UI layer entirely in HTML terms — and upgrades the authoring experience via first-class integration with [Object-Oriented HTML (OOHTML)](/docs/tech-stack#oohtml). OOHTML extends HTML with capabilities like **modularity & reusability**, **reactivity & data binding** — **without a build step**. You get:
+
+* **Modular imports and composable templates** (`<template def>` and `<import ref>`) as first-class primitives.
+* **Scoped styles and scripts, and even scoped subtrees** without Shadow DOM complexity (`<script scoped>`, `<style scoped>`, `<div namespace>`).
+* **Reactive bindings without a compile step** — via HTML attributes and HTML comment (`<!--{ title }-->`, `<?{ title }?>`).
+
+This solves for the sophistication of modern UIs in just HTML, without the complexity of a compile step. With that out of the way, you get **edit-in-browser workflows** where the UI directly reflects live DOM manipulation via the browser inspector.
+
+### The Service Worker as an Embedded Edge Runtime
+
+Webflo brings the service worker into the application model as a full routing runtime — extending it beyond its traditional role as a cache script or network proxy.
+The shift lets you bring your application routes into the service worker, with the same routing architecture and request-handling capabilities as the server and client runtimes. This unlocks:
+
+* **Fullstack routing**. Distribute route handlers across, not two, but three runtimes (server, worker, client) as you deem fit. Same routing architecture, same request-handling capabilities.
+* **More performant client-side routing**. Move compute-intensive routing logic into the service worker runtime from the main thread to keep the UI responsive.
+* **Route-based background tasks**. Sync, periodic events, and push notifications map into routes naturally, not into separate worker-only APIs. One routing architecture for many use cases.
+
+The service worker as a new routing site exposes this underutilized layer of the platform as a _standard application surface to build on_ — like an embedded edge runtime — taking the application closer to the heart of the platform’s capabilities than traditional architectures allow.
+
+---
+
+**What this means**: Webflo is an orchestration of programming fundamentals, web platform capabilities, and the web’s communication protocols into an application framework for the next generation of web apps. With just the fundamentals as the entire application stack — _and no extra thing "going on"_ — Webflo achieves a rare level of conceptual and operational simplicity that makes the sophistication of modern apps feel _almost_ trivial.
+
+## What You Can Build
+
+| Category                   | Examples & Notes                                                                                                 |
+| :------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| **Web apps**               | From classic MPAs to rich SPAs, hybrid SSR/CSR experiences, and full PWAs — all built on one unified framework. |
+| **API backends**           | REST endpoints, serverless-style handlers, and webhooks with streaming, partial responses, and live messaging.   |
+| **Static sites**           | Static-first or fully pre-rendered sites that seamlessly upgrade sections to live or interactive behavior.        |
+| **Mobile experiences**     | Installable, offline-capable PWAs with background sync, worker routing, and native-feeling navigation.            |
+| **Realtime & multiplayer** | Chats, presence, dashboards, live docs, notifications — realtime channels and dialogs available out of the box.  |
+| **AI & agents**            | Multi-step AI workflows, background agents, and automation powered by Webflo’s live request lifecycle.           |
+
+## Features
+
+| Feature                               | Description                                                                                         |
+| :------------------------------------ | :-------------------------------------------------------------------------------------------------- |
+| 📁 **Folder-based routing**           | Filesystem routing across client, worker, and server layers, with seamless interception and flow.   |
+| 🌍 **Full-stack routing & lifecycle** | Every request flows through browser, worker, and server layers using the same handler model.         |
+| 🔗 **Internal API composition**        | Reuse your own routes as local function calls via `next(path)` — no extra networking required.       |
+| 🔐 **Sessions & auth**                | Built-in cookie handling, session utilities, and helpers for gated routes and user-aware flows.     |
+| ⚡ **Realtime capabilities**           | Live responses, incremental updates, dialogs, and background channels — no explicit WebSocket setup. |
+| 🧠 **Mutation-based reactivity**       | State is plain objects and arrays; mutations drive reactivity via the Observer API.                 |
+| 🧱 **OOHTML integration**              | HTML-native templates, imports, and composition without a component DSL or build-heavy toolchain.   |
+| 📦 **Offline & worker features**       | Worker-side routing, caching, background sync, and offline-first behaviors built in.                |
+| 🧩 **Dev mode & HMR**                 | Fast development server with fine-grained rebuilds and hot updates for HTML, JS, and CSS.           |
+
+## Get Started
+
+| Path                                         | Focus                                                             |
+| :------------------------------------------- | :---------------------------------------------------------------- |
+| [Getting Started](./docs/getting-started) | Your first route and page in minutes.                             |
+| [Core Concepts](./docs/concepts)          | The mental models behind routing, request/response, and realtime. |
+| [Examples](./examples)                    | Small, focused examples.                                          |

package/site/examples/pwa.md

@@ -0,0 +1,10 @@
+# Example: PWA
+
+Add manifest, service worker, and offline caching.
+
+- `public/manifest.json`
+- Service worker registration
+- Cache-first strategy
+
+Related:
+- [Service Worker Guide](/guides/guide-service-worker)

package/site/examples/web.md

@@ -0,0 +1,11 @@
+# Example: Web App
+
+Conventional web app with server-rendered data and client interactivity.
+
+- Root handler returns data
+- Templates render UI
+- Client enhances interactions
+
+See:
+- [Getting Started](/docs/getting-started)
+- [Rendering](/docs/concepts/rendering)

package/site/examples.md

@@ -0,0 +1,10 @@
+# Examples
+
+Small, focused examples you can copy and adapt.
+
+- [Web Example](/examples/web)
+- [PWA Example](/examples/pwa)
+
+See also:
+- Guides: [/guides](/guides)
+- Recipes: [/recipes/streaming](/recipes/streaming), [/recipes/realtime](/recipes/realtime)

package/site/faq.md

@@ -0,0 +1,13 @@
+# FAQ
+
+- How do I start in dev?
+  - `webflo start --dev` or `npm run dev`
+
+- How do I build for production?
+  - `webflo build` then `webflo start`
+
+- Where do static files live?
+  - `public/`
+
+- Where are routes defined?
+  - `app/` directory with handlers

package/site/guides/guide-auth.md

@@ -0,0 +1,13 @@
+# Guide: Auth
+
+Patterns for session, cookies, and user state.
+
+- Reading/writing cookies via `event.cookies`
+- Session management via `event.session`
+- Protecting routes (check auth, redirect or return 401)
+- Client-side state reflection at `document.bindings.user`
+
+See API:
+- [HttpUser](/api/webflo-routing/HttpUser)
+- [HttpCookies](/api/webflo-routing/HttpCookies)
+- [HttpSession](/api/webflo-routing/HttpSession)

package/site/guides/guide-file-upload.md

@@ -0,0 +1,11 @@
+# Guide: File Upload
+
+Handle form uploads and streaming.
+
+- Use `Request.formData()` or streamed bodies
+- Validate content type and size
+- Store and return URLs
+
+Related:
+- [Request/Response](/docs/concepts/request-response)
+- [fetch](/api/webflo-fetch/fetch)

package/site/guides/guide-service-worker.md

@@ -0,0 +1,10 @@
+# Guide: Service Worker
+
+Integrate a Service Worker for offline and caching.
+
+- Register SW client-side
+- Cache static assets in `public/`
+- Use background channels for sync
+
+See:
+- [Realtime](/docs/concepts/realtime)

package/site/guides/tutorial-1-todo.md

@@ -0,0 +1,24 @@
+# Tutorial: Todo App
+
+Build a minimal Todo app to learn core Webflo flows.
+
+## 1) Scaffold
+```bash
+webflo init webflo-todo --template=web
+cd webflo-todo
+webflo start --dev
+```
+
+## 2) Route handler
+Edit `app/handler.server.js` to return an initial list and handle add/remove.
+
+## 3) Template
+Bind `document.bindings.data` to render and mutate todos.
+
+## 4) Persist
+Add simple storage using `event.session` or a backing store.
+
+Next:
+- [Routing](/docs/concepts/routing)
+- [Rendering](/docs/concepts/rendering)
+- [State](/docs/concepts/state)

package/site/guides.md

@@ -0,0 +1,15 @@
+# Guides
+
+Start with a hands-on tutorial, then dive into focused guides.
+
+## Start Here
+- Tutorial: [Todo App](/guides/tutorial-1-todo)
+
+## Focused Guides
+- [Auth](/guides/guide-auth)
+- [File Upload](/guides/guide-file-upload)
+- [Service Worker](/guides/guide-service-worker)
+
+## Related
+- Recipes: [Streaming](/recipes/streaming), [Realtime Patterns](/recipes/realtime)
+- API: [Handler](/api/webflo-routing/handler), [HttpEvent](/api/webflo-routing/HttpEvent)

package/site/index.md

@@ -0,0 +1,39 @@
+---
+layout: home
+hero:
+  name: Webflo
+  text: Modern Web Application Framework
+  tagline: Build scalable, real-time, and reactive web apps with ease.
+  image:
+    src: /img/brand/logo-670x670.png
+    width: 600px
+    alt: Webflo Logo
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /docs/getting-started
+    - theme: alt
+      text: Star on GitHub
+      link: https://github.com/webqit/webflo
+features:
+  - title: Universal Runtime
+    details: Run seamlessly across client, server, worker, and edge environments with unified APIs and portable logic.
+  - title: Reactive State & Lifecycle
+    details: Deeply integrated reactivity and lifecycle hooks for state, data, and UI updates everywhere.
+  - title: Real-time Messaging & Sync
+    details: Native support for real-time data, events, broadcast channels, and cross-context messaging.
+  - title: Advanced Routing & Context
+    details: Dynamic, nested, and parameterized routing with context-aware navigation, transitions, and guards.
+  - title: SSR, SSG, CSR
+    details: Out-of-the-box support for server-side rendering, static site generation, and client-side hydration for SEO and performance.
+  - title: Modular Architecture
+    details: Compose features with plug-and-play modules, custom plugins, and runtime integrations.
+  - title: Storage, Cookies, Sessions
+    details: Built-in APIs for storage, cookies, sessions, and secure data flows across all environments.
+  - title: Deployment & Config
+    details: Flexible deployment, environment config, origins, proxy, and manifest management.
+  - title: CLI & Dev Tools
+    details: Powerful CLI, hot-reloading, code generation, and rich debugging for rapid development.
+  - title: Security & Isolation
+    details: Context isolation, robust session management, and secure data flows for any environment.
+---

package/site/recipes/realtime.md

@@ -0,0 +1,11 @@
+# Recipe: Realtime Patterns
+
+Keep server and client in sync.
+
+- Long-lived `LiveResponse`
+- Background messaging
+- Reconnect and resume
+
+See:
+- [Realtime Concept](/docs/concepts/realtime)
+- [HttpEvent](/api/webflo-routing/HttpEvent)

package/site/recipes/streaming.md

@@ -0,0 +1,15 @@
+# Recipe: Streaming
+
+Send progressive updates.
+
+```js
+export async function GET(event) {
+  event.respondWith({ step: 1 }, { done: false });
+  await new Promise(r => setTimeout(r, 100));
+  event.respondWith({ step: 2 }); // done
+}
+```
+
+See:
+- [Handler → Return Styles](/api/webflo-routing/handler#return-styles)
+- [Request/Response](/docs/concepts/request-response)

package/site/reference/cli.md

@@ -0,0 +1,11 @@
+# CLI Reference
+
+Webflo provides a CLI for development, build, and config workflows.
+
+## Commands
+- `webflo init <name> [title] [description] [--template=web|pwa]`
+- `webflo start [--dev] [--open] [--port <port>]`
+- `webflo build`
+- `webflo config`
+
+See Getting Started: [/docs/getting-started](/docs/getting-started)

package/site/reference/config.md

@@ -0,0 +1,13 @@
+# Configuration Reference
+
+Most apps work without extra configuration. When needed, configuration lives under `.webflo/` and/or environment variables.
+
+## Common Areas
+- Environment variables via `.env`
+- Origins/proxy
+- Static assets under `public/`
+- Routes under `app/`
+
+See Concepts:
+- [Routing](/docs/concepts/routing)
+- [Request/Response](/docs/concepts/request-response)

package/site/reference/tools.md

@@ -0,0 +1,9 @@
+# Tools
+
+Supporting tools you’ll often use with Webflo.
+
+- OOHTML (templates bundling)
+- Build scripts for HTML/CSS/JS
+- Dev server with HMR
+
+See: [/docs/getting-started](/docs/getting-started)

package/src/Context.js

@@ -1,12 +1,5 @@
+export class Context {
 
-export default class Context {
-
-    /**
-     * Initializes a context.
-     * 
-     * @param Object  dict 
-     * @param String  CD 
-     */
     constructor(dict, CD = null) {
         // dict can be plain object or some Context instance itself
         // Using it as only a prototype protects it from being mutated down here
@@ -41,8 +34,8 @@ export default class Context {
     }
 
     // app
-    get app() {
-        return this.dict.app || {};
+    get appMeta() {
+        return this.dict.appMeta || {};
     }
 
     // config
@@ -76,5 +69,4 @@ export default class Context {
     set logger(value) {
         Object.defineProperty(this.dict, 'logger', { value } );
     }
-
 }

package/src/config-pi/deployment/Env.js

@@ -13,18 +13,13 @@ export default class Env extends Dotfile {
 
     // @desc
     static get ['@desc']() {
-        return 'Environmental variables config.';
-    }
-
-    // isEnv
-    get isEnv() {
-        return true;
+        return 'Environmental variable mappings.';
     }
 
     // Defaults merger
     withDefaults(config) {
         return this.merge({
-            autoload: true,
+            mappings: {}
         }, config, 'patch');
     }
 
@@ -33,13 +28,13 @@ export default class Env extends Dotfile {
         // Questions
         return [
             {
-                name: 'entries',
+                name: 'mappings',
                 type: 'recursive',
                 controls: {
-                    name: 'variable',
+                    name: 'variable mappings',
                     combomode: true,
                 },
-                initial: config.entries,
+                initial: config.mappings,
                 schema: [
                     {
                         name: 'name',
@@ -54,15 +49,7 @@ export default class Env extends Dotfile {
                         validation: ['important'],
                     },
                 ],
-            },
-            {
-                name: 'autoload',
-                type: 'toggle',
-                message: 'Choose whether to autoload variables into "process.env"',
-                active: 'YES',
-                inactive: 'NO',
-                initial: config.autoload,
-            },
+            }
         ];
     }
 }

package/src/config-pi/deployment/Layout.js

@@ -20,9 +20,10 @@ export default class Layout extends Dotfile {
     withDefaults(config) {
         return this.merge({
             PUBLIC_DIR: './public',
-            SERVER_DIR: './server',
-            CLIENT_DIR: './client',
-            WORKER_DIR: './worker',
+            VIEWS_DIR: './app',
+            SERVER_DIR: './app',
+            CLIENT_DIR: './app',
+            WORKER_DIR: './app',
         }, config, 'patch');
     }
 
@@ -37,6 +38,13 @@ export default class Layout extends Dotfile {
                 initial: config.PUBLIC_DIR,
                 validation: ['important'],
             },
+            {
+                name: 'VIEWS_DIR',
+                type: 'text',
+                message: 'Enter the directory for the application\'s view files (templates)',
+                initial: config.VIEWS_DIR,
+                validation: ['important'],
+            },
             {
                 name: 'SERVER_DIR',
                 type: 'text',

package/src/config-pi/runtime/Client.js

@@ -19,36 +19,28 @@ export default class Client extends Dotfile {
     // Defaults merger
     withDefaults(config) {
         return this.merge({
-            bundle_filename: 'bundle.js',
+            filename: 'app.js',
             public_base_url: '/',
+            copy_public_variables: true,
             spa_routing: true,
-            service_worker: {
-                filename: 'worker.js',
-                scope: '/',
-                support_push: false,
-                vapid_key_env: 'VAPID_PUBLIC_KEY',
-                push_registration_url_env: 'PUSH_REGISTRATION_PUBLIC_URL',
+            capabilities: {
+                service_worker: false,
+                webpush: false,
+                custom_install: false,
+                exposed: ['display-mode', 'notifications'],
             },
-            bundle_public_env: false,
         }, config, 'patch');
     }
 
     // Questions generator
     getSchema(config, choices = {}) {
-        // Choices
-        const CHOICES = this.merge({
-            webqit_dependencies: [
-                {value: 'externalize', title: 'Externalize'},
-                {value: 'internalize', title: 'Internalize'},
-            ],
-        }, choices, 'patch');
         // Questions
         return [
             {
-                name: 'bundle_filename',
+                name: 'filename',
                 type: 'text',
                 message: 'Specify the bundle filename',
-                initial: config.bundle_filename,
+                initial: config.filename,
             },
             {
                 name: 'public_base_url',
@@ -58,7 +50,16 @@ export default class Client extends Dotfile {
                 validation: ['important'],
             },
             {
-                name: 'bundle_public_env',
+                name: 'copy_public_variables',
+                type: 'toggle',
+                message: '[copy_public_variables]: Bundle public ENV variables?',
+                active: 'YES',
+                inactive: 'NO',
+                initial: config.copy_public_variables,
+                validation: ['important'],
+            },
+            {
+                name: 'spa_routing',
                 type: 'toggle',
                 message: '[spa_routing]: Enable Single Page Routing Mode',
                 active: 'YES',
@@ -67,50 +68,41 @@ export default class Client extends Dotfile {
                 validation: ['important'],
             },
             {
-                name: 'service_worker',
+                name: 'capabilities',
                 controls: {
-                    name: 'service_worker',
+                    name: 'capabilities',
                 },
-                initial: config.service_worker,
+                initial: config.capabilities,
                 schema: [
                     {
-                        name: 'filename',
-                        type: 'text',
-                        message: 'Specify the Service Worker filename',
-                    },
-                    {
-                        name: 'scope',
-                        type: 'text',
-                        message: 'Specify the Service Worker scope',
+                        name: 'service_worker',
+                        type: 'toggle',
+                        message: 'Enable service worker?',
+                        active: 'YES',
+                        inactive: 'NO',
                     },
                     {
-                        name: 'support_push',
+                        name: 'webpush',
                         type: 'toggle',
                         message: 'Support push-notifications?',
                         active: 'YES',
                         inactive: 'NO',
                     },
                     {
-                        name: 'vapid_key_env',
-                        type: (prev, answers) => answers.support_push ? 'text' : null,
-                        message: 'Enter the VAPID KEY env id for push notification subscription',
+                        name: 'custom_install',
+                        type: 'toggle',
+                        message: 'Enable custom PWA install prompt?',
+                        active: 'YES',
+                        inactive: 'NO',
                     },
                     {
-                        name: 'push_registration_url_env',
-                        type: (prev, answers) => answers.support_push ? 'text' : null,
-                        message: 'Enter the URL for push notification subscription',
-                    },
-                ],
-            },
-            {
-                name: 'bundle_public_env',
-                type: 'toggle',
-                message: '[bundle_public_env]: Bundle public ENV variables?',
-                active: 'YES',
-                inactive: 'NO',
-                initial: config.bundle_public_env,
-                validation: ['important'],
-            },
+                        name: 'exposed',
+                        type: 'list',
+                        message: 'Specify features exposed on capabilities.exposed',
+                        initial: (config.exposed || []).join(', '),
+                    }
+                ]
+            }
         ];
     }
 }