@qbix/q.js 1.0.1 → 1.0.5

package/README.md

@@ -6,8 +6,8 @@ Size: ~40KB (Minified + GZipped), [compare to other frameworks](https://gist.git
 How to use: copy contents of `dist` into your project, and then include it like this:
 | File Type | Code to Use |
 |------------|-------------|
-|`.html` files| `<script type="module">import { Q } from 'https://unpkg.com/@qbixplatform/q.js@1.0.16/dist/Q.js</script>`|
-|`.js` or `.ts` files|`import Q from 'https://unpkg.com/@qbixplatform/q.js@1.0.17/dist/Q.js';`
+|`.html` files| `<script type="module" src="https://unpkg.com/@qbix/q.js@1.0.2/dist/Q.min.js">`|
+|`.js` or `.ts` files|`import Q from 'https://unpkg.com/@qbix/q.js@1.0.2/dist/Q.min.js';`
 |<img src="https://github.com/user-attachments/assets/ba3df93e-0cd8-4189-93fc-11947b63b684" alt="Description" width="100" height="87"> | Full documentation here: https://qbix.com/platform/guide/javascript |
 
 This is part of the much larger full-stack [Qbix Platform](https://github.com/Qbix/Platform) that contains many pre-built reusable tools, plugins, and requires PHP and Node.js on the back-end. If you want to build an entire full-stack social network like Facebook you're well-advised to go with that. But if you just want to use the lightweight front-end core, with your own back-end and other frameworks, then start with this framework here.
@@ -648,3 +648,31 @@ In it, you will define the tools, methods, and other things. Here is an example:
 
 ```
 
+
+# 📊 Metrics.js — Standalone Telemetry
+
+This repo also includes **Metrics.js** — a standalone telemetry library that tracks scroll depth, section engagement, and video/audio playback across 9 embed providers. No dependencies, no build step, works on any website.
+
+```html
+<script src="https://unpkg.com/@qbix/q.js/dist/Metrics.js"></script>
+<script>
+Metrics.init({ endpoint: '/telemetry', page: document.title });
+Metrics.ScrollTracker.init({ sections: 'h2[id]' });
+Metrics.MediaTracker.init(); // auto-discovers YouTube, Vimeo, SoundCloud, Wistia, JW Player, Dailymotion, Spotify, Twitch, Muse.ai
+</script>
+```
+
+Unique features:
+- **Watched seconds** — tracks unique seconds of video/audio covered, not just total playback. Seeking back and replaying doesn't inflate the number.
+- **Section engagement** — knows which heading the user is actually reading, not just how far they scrolled.
+- **Persistent visitor ID** — `localStorage` with `sessionStorage` fallback. ITP-safe because it's first-party storage.
+- **9 media providers** — auto-detected, APIs loaded on demand, no configuration needed.
+- **Zero Q.js dependency** — works completely standalone. But if Q.js is loaded, Metrics automatically gains CSRF tokens, `Q.Page` SPA tracking, `Q/tabs` and `Q/columns` auto-hooks, and debounced server-side state updates.
+
+👉 **[Full Metrics.js documentation →](Metrics.md)**
+
+## From Metrics.js to the Qbix Platform
+
+Metrics.js is the lightweight entry point. For the full server-side stack — visit attribution, referral chain walking, multi-level commissions, real-time WebSocket updates, and per-component Merkle-tree cache invalidation — install the [Qbix Platform](https://github.com/Qbix/Platform) with the Metrics plugin.
+
+The platform includes a high-performance [webserver](https://github.com/Qbix/webserver) (Cosmopolitan C binary) that maintains a Merkle tree of rendered component hashes. When data changes, only the affected components re-render — not the whole page. Combined with static site generation for CDN caching and `Streams/check` for per-stream change detection over WebSocket, you get sub-second updates with near-zero server load. No PHP required for serving — the webserver handles everything.