@thebase/ui 1.1.0 → 1.1.2

package/dist/baseui.pwa.esm.js

@@ -0,0 +1,53 @@
+var u=[{src:"/icons/icon-192.png",sizes:"192x192",type:"image/png",purpose:"any"},{src:"/icons/icon-512.png",sizes:"512x512",type:"image/png",purpose:"any"},{src:"/icons/icon-512.png",sizes:"512x512",type:"image/png",purpose:"maskable"}],f=["/","/manifest.webmanifest","/favicon.svg"];function d(n){let{name:t,shortName:s=t,description:c="",startUrl:r="/",scope:e="/",display:a="standalone",orientation:i="portrait-primary",backgroundColor:o="#ffffff",themeColor:h="#0f172a",lang:l="en",icons:p=u}=n;return{name:t,short_name:s,description:c,start_url:r,scope:e,display:a,orientation:i,background_color:o,theme_color:h,lang:l,icons:p}}function m(n){let{cacheName:t,cdnVersion:s,appFiles:c=[],extraPrecacheUrls:r=[]}=n,e=`https://cdn.jsdelivr.net/npm/@thebase/ui@${s}/dist/`,a=[...f,...c,...r,`${e}baseui.min.css`,`${e}baseui.esm.js`,`${e}baseui.templates.xml`];return`const CACHE_NAME = ${JSON.stringify(t)};
+const BASEUI_CDN = ${JSON.stringify(e)};
+
+const PRECACHE_URLS = ${JSON.stringify(a,null,2)};
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS)).then(() => self.skipWaiting())
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))))
+      .then(() => self.clients.claim())
+  );
+});
+
+async function fromCdnCache(request) {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(request);
+  if (cached) return cached;
+  const response = await fetch(request);
+  if (response.ok) cache.put(request, response.clone());
+  return response;
+}
+
+self.addEventListener("fetch", (event) => {
+  const { request } = event;
+  if (request.method !== "GET") return;
+  if (request.url.startsWith(BASEUI_CDN)) {
+    event.respondWith(fromCdnCache(request));
+    return;
+  }
+  if (new URL(request.url).origin !== self.location.origin) return;
+
+  event.respondWith(
+    caches.open(CACHE_NAME).then(async (cache) => {
+      try {
+        const response = await fetch(request);
+        if (response.ok) cache.put(request, response.clone());
+        return response;
+      } catch {
+        const cached = await cache.match(request);
+        if (cached) return cached;
+        throw new Error(\`No cached response for \${request.url} and network unavailable\`);
+      }
+    })
+  );
+});
+`}export{d as buildManifest,m as buildServiceWorker};

package/dist/baseui.registry.json

@@ -1662,13 +1662,13 @@
   "integrity": {
     "baseui.min.css": "sha384-hYFwlV6T/ONYzawtDGDFUoruqgNwYl9AVvLDHx24IWgKSMXqwACo/nX04I3gnyT9",
     "bootstrap.bundle.min.js": "sha384-RMbllTJcplkCRnELNTOc5Kz/3AvFDE/rNlJqWqfgmRWruobClBdfwvl10akQZkR1",
-    "baseui.min.js": "sha384-jzPn6U5dm/0jM9kcSMnDNOiDWLfdN4h28z+YRNYU/IbGmMf4nFTSVsTn6siJ+UHH",
-    "baseui.esm.js": "sha384-I61E5GCJymEsiX5xmIe5Ufd498zcuzGIWwu79WfKg1IKbtACkeC3LG1QXbIq/5cT",
+    "baseui.min.js": "sha384-Qv1lpDLXQ3+gI0MGXGSdeOmq7tX+Hn6/TcsSsnWikLXQhi7BTAIKNWPUeIXP1LxF",
+    "baseui.esm.js": "sha384-IkUDqUsC56aiRgXggGe2XGZM2chM148CB837Gh/mWPtjqUEq5qH9ve5eG5texJPT",
     "baseui.icons.esm.js": "sha384-hj39VMhzcFvmYnjob2hlioMOAqwAXCURGreF6s9RitXFp/iYi7rUdqtfCI+ICQeS",
     "baseui.templates.xml": "sha384-XkqmfurKcEF6WuIQHWAbnZfW6oz19n7SDVRDU3g0hc3qOr4kPd/qfNGcTmcDDIgQ",
     "baseui.block-viewer.esm.js": "sha384-XlIb3jDxt6Q75dbC4rLctTdPU6u0vJFcbxp9Gl6VKOkhjpz3wRBe0E3dWd80425L",
-    "baseui.analytics.esm.js": "sha384-M7jEmmio32O8iquXxQjhCbfEAqZAkHG+a1+Wt6sajMFCubQDzEx7QQMMpek0QxY6",
-    "baseui.analytics.min.js": "sha384-aD3A1qm15yTTviPHRscI2enlOIHp7SaIdr+KBCBTgjChn23ZfEsOvY7izOB+hUZe",
+    "baseui.analytics.esm.js": "sha384-M6TVmchmceTvpSzgI+DNA6zAn9xmz9a+YEexCLslSo/Ngxyp2kmzs9fm+PxWy+Da",
+    "baseui.analytics.min.js": "sha384-B0hBkVDbT7gmDmUMazlN4Nc1KnYGSpL+IcW2hd8840knx73HGImPgGs84MvS3hKE",
     "icons/lucide.json": "sha384-mc5mzpmq9eOgZVa2IcjrL33Ty4nMXE8aoZMfy+lgkC/jMQ4aYnk2S58mFsSGFnW1",
     "themes/baseui-light.css": "sha384-/TosvycgVJ5aZ7EOWd4cr8Zen4nayAC/iA9BgGdXKH0LuHSnZk4guDaWM5WPC7yy",
     "themes/baseui-dark.css": "sha384-zF9Rhfjpv90sxuJ2WK7GBPCltN6mkebzK1w9EzQGY9DYHiX3eIX/fcE7fXzfIZVF"

package/dist/types/analytics.d.ts

@@ -6,6 +6,16 @@ export interface BaseUIAnalytics {
   track(eventName: string, options?: BaseUIAnalyticsEventOptions): void;
   /** File types tracked by default when `fileDownloads` is enabled. */
   DEFAULT_FILE_TYPES: string[];
+  /** Coarse visitor setup (timezone, language, screen bucket); pass as `customProperties`. */
+  visitorContext(): BaseUIVisitorContext;
+}
+export interface BaseUIVisitorContext {
+  /** IANA timezone, e.g. "Europe/Paris" (browsers may report legacy aliases like "Asia/Saigon"). */
+  tz: string;
+  /** `navigator.language`, e.g. "vi-VN". */
+  lang: string;
+  /** Viewport width bucket: < 576, < 992, < 1440, otherwise Desktop. */
+  screen: "Mobile" | "Tablet" | "Laptop" | "Desktop";
 }
 
 export interface BaseUIAnalyticsConfig {
@@ -63,3 +73,4 @@ export type BaseUIAnalyticsPayload = {
 export const DEFAULT_FILE_TYPES: string[];
 export function init(config: BaseUIAnalyticsConfig): void;
 export function track(eventName: string, options?: BaseUIAnalyticsEventOptions): void;
+export function visitorContext(): BaseUIVisitorContext;

package/dist/types/pwa.d.ts

@@ -0,0 +1,37 @@
+/** Optional PWA toolkit: builds manifest.webmanifest/sw.js content from a config object. */
+export interface BaseUIManifestConfig {
+  name: string;
+  /** Defaults to `name`. */
+  shortName?: string;
+  description?: string;
+  /** Defaults to "/". */
+  startUrl?: string;
+  /** Defaults to "/". */
+  scope?: string;
+  /** Defaults to "standalone". */
+  display?: string;
+  /** Defaults to "portrait-primary". */
+  orientation?: string;
+  /** Defaults to "#ffffff". */
+  backgroundColor?: string;
+  /** Defaults to "#0f172a". */
+  themeColor?: string;
+  /** Defaults to "en". */
+  lang?: string;
+  /** Defaults to a 192/512 `/icons/icon-*.png` set. */
+  icons?: Array<{ src: string; sizes: string; type: string; purpose?: string }>;
+}
+
+export interface BaseUIServiceWorkerConfig {
+  /** Cache bucket name, e.g. "my-app-cache-v1" — bump the suffix to invalidate old caches. */
+  cacheName: string;
+  /** Pinned `@thebase/ui` version the generated sw.js precaches/serves from jsdelivr. */
+  cdnVersion: string;
+  /** Same-origin app-shell paths to precache (JS/CSS/XML/icons/etc). */
+  appFiles?: string[];
+  /** Extra same-origin or cross-origin URLs to precache alongside `appFiles`. */
+  extraPrecacheUrls?: string[];
+}
+
+export function buildManifest(config: BaseUIManifestConfig): Record<string, unknown>;
+export function buildServiceWorker(config: BaseUIServiceWorkerConfig): string;

package/docs/analytics.md

@@ -13,12 +13,12 @@ init({ backendUrl: "https://stats.example.com" });
 ```html
 <!-- ES module from the CDN (or map it as "@base/analytics" in an import map) -->
 <script type="module">
-  import { init } from "https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.0/dist/baseui.analytics.esm.js";
+  import { init } from "https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.1/dist/baseui.analytics.esm.js";
   init({ backendUrl: "https://stats.example.com" });
 </script>
 
 <!-- Classic script tag: sets window.thebase.analytics (load order vs dist/baseui.min.js doesn't matter) -->
-<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.0/dist/baseui.analytics.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.1/dist/baseui.analytics.min.js"></script>
 <script>
   thebase.analytics.init({ backendUrl: "https://stats.example.com" });
 </script>
@@ -68,6 +68,24 @@ Or tag markup with classes — no JavaScript needed:
 
 `+` in a class value becomes a space; `thebase-revenue-amount=10 thebase-revenue-currency=USD` attaches revenue.
 
+## Visitor context
+
+`visitorContext()` returns coarse facts about the visitor's setup. Pass it as `customProperties` to attach them to every event (available from 1.1.1):
+
+```js
+import { init, visitorContext } from "@thebase/ui/analytics";
+init({ backendUrl: "https://stats.example.com", customProperties: visitorContext });
+// every event's props now include { tz: "Asia/Ho_Chi_Minh", lang: "vi-VN", screen: "Mobile" }
+```
+
+| Prop | Value |
+| --- | --- |
+| `tz` | `Intl.DateTimeFormat().resolvedOptions().timeZone`. Some browsers report legacy aliases (Chromium sends `Asia/Saigon`), so backends should canonicalize. |
+| `lang` | `navigator.language`, e.g. `vi-VN`. |
+| `screen` | Viewport width bucket: `Mobile` (< 576 px), `Tablet` (< 992), `Laptop` (< 1440), `Desktop`. |
+
+The values are deliberately coarse: no exact pixels, nothing persistent. Backends can treat `tz`, `lang` and `screen` as visit dimensions instead of event props. To combine it with your own props, call it inside your function: `customProperties: (name) => ({ ...visitorContext(), plan: "pro" })`. Don't use `tz`, `lang` or `screen` as your own event prop names: event props override custom properties with the same key, so the visitor's value would be lost. Use something like `uiLang` instead. The IP address and user agent never appear in the payload; the server reads them from the HTTP request (see [Receiving events](#receiving-events-backend)).
+
 ## Engagement
 
 After each pageview the service measures time on screen and maximum scroll depth, and sends an `engagement` event (`e` = ms, `sd` = %) when the tab is hidden, loses focus, or navigates — only if the visitor scrolled further or spent at least 3 seconds since the last report.
@@ -75,3 +93,175 @@ After each pageview the service measures time on screen and maximum scroll depth
 ## Ignored visits
 
 Events are dropped (and `callback()` gets `undefined`) on localhost unless `captureOnLocalhost` is set, in automated browsers (`navigator.webdriver`, Cypress, PhantomJS, Nightmare — unless `window.__thebase` is set), or when `localStorage.thebase_ignore === "true"` (set that on your own devices to exclude them).
+
+## Receiving events (backend)
+
+Any HTTP server can collect events. It needs one route — `POST <backendUrl><apiPath>` (default `/api/event`) — that:
+
+1. Reads the **raw body** as JSON. The tracker sends `Content-Type: text/plain` to avoid a CORS preflight, so framework helpers that only parse `application/json` bodies won't decode it.
+2. Rejects bodies missing `n`, `u` or `d`, and caps the body size (events are well under 1 KB).
+3. Answers quickly (`202 Accepted`, no body) with `Access-Control-Allow-Origin` for your site. Store or queue the event after you reply, or send it to a queue, so the visitor's browser never waits on the database.
+
+### Payload
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `n` | string | Event name: `pageview`, `engagement`, or a custom name (`Signup`, `Outbound Link: Click`, `File Download`, `Form: Submission`, …). |
+| `u` | string | Page URL. |
+| `d` | string | Site `domain`. |
+| `r` | string \| null | `document.referrer` (pageviews and custom events). |
+| `p` | object | Custom properties (`props` + `customProperties`); values are usually strings. |
+| `$` | object | Revenue, e.g. `{ "amount": 10, "currency": "USD" }` (`amount` is a string when it comes from a class tag). |
+| `i` | `false` | Present only for non-interactive events (excluded from bounce rate). |
+| `h` | `1` | Present only with `hashBasedRouting`. |
+| `sd` | number | `engagement` only: max scroll depth, %. |
+| `e` | number | `engagement` only: engaged time, ms. |
+| `v` | number | Tracker version (currently `36`). |
+
+The payload carries no visitor ID or cookie. To count unique visitors, derive one on the server, e.g. `sha256(dailySalt + domain + clientIP + userAgent)`. Rotate the salt every day and never store the raw IP. If the server sits behind a proxy or load balancer, configure it to trust the proxy's `X-Forwarded-For` header so it sees the visitor's IP instead of the proxy's.
+
+### Go — Fiber v3
+
+Requires Go 1.25+ and `go get github.com/gofiber/fiber/v3` (tested with v3.5.0).
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"log"
+
+	"github.com/gofiber/fiber/v3"
+	"github.com/gofiber/fiber/v3/middleware/cors"
+)
+
+// Event is the compact payload POSTed by @thebase/ui/analytics.
+type Event struct {
+	Name        string         `json:"n"`
+	URL         string         `json:"u"`
+	Domain      string         `json:"d"`
+	Referrer    *string        `json:"r"`
+	Props       map[string]any `json:"p"`
+	Revenue     map[string]any `json:"$"`
+	Interactive *bool          `json:"i"`
+	HashRouting int            `json:"h"`
+	ScrollDepth *int           `json:"sd"`
+	EngagedMs   *int64         `json:"e"`
+	Version     int            `json:"v"`
+}
+
+func main() {
+	app := fiber.New(fiber.Config{BodyLimit: 16 * 1024})
+	app.Use(cors.New(cors.Config{AllowOrigins: []string{"https://www.example.com"}}))
+
+	app.Post("/api/event", func(c fiber.Ctx) error {
+		// Body is text/plain, so decode it directly instead of c.Bind().JSON().
+		var ev Event
+		if err := json.Unmarshal(c.Body(), &ev); err != nil || ev.Name == "" || ev.URL == "" || ev.Domain == "" {
+			return c.SendStatus(fiber.StatusBadRequest)
+		}
+		log.Printf("%s %s %s ip=%s ua=%q", ev.Domain, ev.Name, ev.URL, c.IP(), c.Get(fiber.HeaderUserAgent))
+		// TODO: enqueue/store ev.
+		return c.SendStatus(fiber.StatusAccepted)
+	})
+
+	log.Fatal(app.Listen(":8080"))
+}
+```
+
+### Python — FastAPI
+
+Requires Python 3.10+ and `pip install "fastapi[standard]"` (tested with FastAPI 0.142.2 / Pydantic 2.13). Run with `fastapi run main.py`.
+
+```python
+from typing import Any
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field, ValidationError
+
+app = FastAPI()
+app.add_middleware(CORSMiddleware, allow_origins=["https://www.example.com"], allow_methods=["POST"])
+
+
+class Event(BaseModel):
+    """Compact payload POSTed by @thebase/ui/analytics."""
+
+    name: str = Field(alias="n", min_length=1)
+    url: str = Field(alias="u", min_length=1)
+    domain: str = Field(alias="d", min_length=1)
+    referrer: str | None = Field(None, alias="r")
+    props: dict[str, Any] | None = Field(None, alias="p")
+    revenue: dict[str, Any] | None = Field(None, alias="$")
+    interactive: bool | None = Field(None, alias="i")
+    hash_routing: int | None = Field(None, alias="h")
+    scroll_depth: int | None = Field(None, alias="sd")
+    engaged_ms: int | None = Field(None, alias="e")
+    version: int = Field(alias="v")
+
+
+@app.post("/api/event", status_code=202)
+async def collect(request: Request) -> Response:
+    # Body is text/plain, so parse the raw bytes instead of declaring `event: Event` as a parameter.
+    body = await request.body()
+    if len(body) > 16 * 1024:
+        return Response(status_code=413)
+    try:
+        event = Event.model_validate_json(body)
+    except ValidationError:
+        return Response(status_code=400)
+    ip = request.client.host if request.client else None
+    print(event.domain, event.name, event.url, ip, request.headers.get("user-agent"))
+    # TODO: enqueue/store event.
+    return Response(status_code=202)
+```
+
+Point the tracker at either server with `init({ backendUrl: "https://stats.example.com" })`. To smoke-test the server, run:
+
+```sh
+curl -i -X POST http://localhost:8080/api/event -H 'Content-Type: text/plain' \
+  -d '{"n":"pageview","v":36,"u":"https://www.example.com/","d":"www.example.com","r":null}'
+# HTTP/1.1 202 Accepted
+```
+
+## Sample dashboard
+
+[`examples/analytics/`](../examples/analytics/dashboard/?backend=http://localhost:8080) contains a working dashboard plus two complete sample backends: [`server-go`](../examples/analytics/server-go/main.go) (Fiber v3) and [`server-fastapi`](../examples/analytics/server-fastapi/main.py). Each one extends the receivers above with an in-memory store, a daily-salted cookieless visitor hash, a `GET /api/stats` endpoint, and static hosting for the dashboard.
+
+The dashboard ([`dashboard/`](../examples/analytics/dashboard/?backend=http://localhost:8080)) is a pure Owl app that loads `@thebase/ui@1.1.1` from jsDelivr: KPI `Card`s, an area `Chart`, top pages/sources/events `Table`s, site and period `NativeSelect`s, and a `ThemeButton`. It refreshes every 30 s and tracks its own visits through `@thebase/ui/analytics`, so a fresh backend has data straight away.
+
+```sh
+# Go (1.25+)
+cd examples/analytics/server-go && DEMO_SEED=1 go run .
+
+# or Python (3.10+)
+cd examples/analytics/server-fastapi && pip install -r requirements.txt && DEMO_SEED=1 fastapi run main.py --port 8080
+```
+
+Open <http://localhost:8080/>, the backend serves the dashboard itself. If you are browsing these docs from `npm run dev` (port 5173), the [dashboard link](../examples/analytics/dashboard/?backend=http://localhost:8080) also works once a backend is running on port 8080; until then it shows a "Can't load stats" message. `DEMO_SEED=1` preloads 30 days of synthetic traffic for `demo.example.com`. Other environment variables:
+- `ADDR`: the Go listen address.
+- `ALLOWED_ORIGINS`: a comma-separated CORS allow-list (default `*`).
+- `DASHBOARD_DIR`: the folder served at `/`.
+
+To serve the dashboard from somewhere else, open it with `?backend=https://stats.example.com`.
+
+`GET /api/stats?domain=<site>&days=<1..90>` (default: the busiest site, 7 days, UTC) returns:
+
+```json
+{
+  "domain": "demo.example.com",
+  "domains": ["demo.example.com", "www.example.com"],
+  "days": 7,
+  "totals": { "visitors": 643, "pageviews": 1582, "events": 124, "avgTimeSec": 62.7, "avgScrollDepth": 63.4 },
+  "timeseries": [{ "date": "2026-09-28", "visitors": 105, "pageviews": 261 }],
+  "topPages":   [{ "name": "/pricing", "visitors": 296, "count": 373 }],
+  "topSources": [{ "name": "google.com", "visitors": 186, "count": 186 }],
+  "topEvents":  [{ "name": "Signup", "visitors": 40, "count": 40 }]
+}
+```
+
+The sample servers are demos, not production stores:
+- Events live in memory only and are lost on restart.
+- `/api/stats` has no authentication.
+
+Before going live, persist events (e.g. PostgreSQL or ClickHouse), put `/api/stats` behind auth, and restrict `ALLOWED_ORIGINS`.

package/docs/blocks.md

@@ -13,7 +13,7 @@ Blocks are not standalone runtime components. Paste the markup and load the norm
 <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Blocks are static markup, so they only need the static `b-ui` runtime above — see [Usage Guide](usage-guide.md) if the surrounding page is itself an Owl app and you'd rather compose the equivalent layout from [Pure Owl Components](owl-components.md).
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Blocks are static markup, so they only need the static `b-ui` runtime above — see [Usage Guide](usage-guide.md) if the surrounding page is itself an Owl app and you'd rather compose the equivalent layout from [Pure Owl Components](owl-components.md).
 
 Use `b-block` to select the block style:
 

package/docs/icons.md

@@ -22,7 +22,7 @@ Load the normal BaseUI assets. No separate icon script is required.
 <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Owl `Icon` component](components/icon.md) — the recommended API in an Owl app; the classic script above is for pages using the static `b-ui` API.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Owl `Icon` component](components/icon.md) — the recommended API in an Owl app; the classic script above is for pages using the static `b-ui` API.
 
 The build publishes every Lucide SVG to `dist/icons/lucide/` and writes the generated icon manifest to `dist/icons/lucide.json`.
 

package/docs/installation.md

@@ -4,7 +4,7 @@ See the [Usage Guide](usage-guide.md) for the end-to-end integration path (choos
 
 BaseUI is distributed as one CSS file and one JavaScript file for browser use. `dist/baseui.min.js` is fully self-contained: Bootstrap's JS bundle (Popper.js included) and the Owl runtime are embedded ahead of BaseUI's own code, in load order (Bootstrap, then Owl, then BaseUI) — nothing else needs to load first. Both install paths below load this same file; the pure Owl component API is the recommended way to consume BaseUI in an Owl app, with the static `b-ui` markup API available as a lighter-weight alternative for non-Owl pages.
 
-The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
+The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
 
 ## Pure Owl component install (recommended)
 
@@ -43,7 +43,7 @@ For static HTML, a server-rendered page, or a Base HUB website page that has no
 
 Bootstrap 5 is the bundled baseline CSS framework, and its JS bundle now drives BaseUI's interactive components directly.
 
-`@thebase/ui` is published on npm, so [unpkg](https://unpkg.com/@thebase/ui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/@thebase/ui@latest/dist/baseui.min.css` / `baseui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`@thebase/ui` is published on npm, so [unpkg](https://unpkg.com/@thebase/ui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/@thebase/ui@latest/dist/baseui.min.css` / `baseui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 For npm/self-hosted usage:
 

package/docs/theming.md

@@ -38,7 +38,7 @@ For a reusable theme toggle with persistence, URL override, button-label sync, a
 </script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `@thebase/ui`.
+`https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `@thebase/ui`.
 
 For a ready-made icon button, use the BaseUI component instead of wiring your own click handler:
 

package/docs/usage-guide.md

@@ -32,7 +32,7 @@ Save this as an `.html` file and open it — no build step, no server required.
 </html>
 ```
 
-`https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/...` is the real jsDelivr URL for the published `@thebase/ui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
+`https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/...` is the real jsDelivr URL for the published `@thebase/ui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
 
 The static bundle calls `thebase.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `thebase.mountAll(root)` yourself only after injecting new markup or when mounting a specific fragment. If the consumer is itself an Owl app, use [step 2](#2-install-pure-owl-api--recommended) instead — that's the recommended path.
 
@@ -63,7 +63,7 @@ Both APIs come from the same package and the same CSS file, and can be mixed on
 </script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 ```html
 <script type="module">
@@ -103,7 +103,7 @@ Two rules that account for most integration failures — see [Pure Owl Component
 <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 **Option B — npm (bundler-based apps: Vite, webpack, etc.):**
 
@@ -120,7 +120,7 @@ import "@thebase/ui"; // side-effect import: registers window.thebase and auto-m
 
 Rule that applies to both options:
 
-- Production pages must use a pinned version (e.g. `@thebase/ui@1.1.0` or `@thebase/ui@1`), never `@latest`.
+- Production pages must use a pinned version (e.g. `@thebase/ui@1.1.1` or `@thebase/ui@1`), never `@latest`.
 
 Mount markup:
 
@@ -200,6 +200,42 @@ Full token list and the shadcn-aligned default palette: [Theming](theming.md).
 
 Icons ship with the normal BaseUI assets — no separate script tag, and every Lucide icon name is available by kebab-case (`panel-left`), camelCase, or snake_case. Sizing, color, accessibility rules, and self-hosting: [Built-in Icons](icons.md).
 
+## 5b. PWA toolkit (optional) — generate manifest.webmanifest + sw.js
+
+Any BaseUI app can become an installable PWA without hand-writing a service worker. `@thebase/ui/pwa`
+exports two pure functions, `buildManifest(config)` and `buildServiceWorker(config)`, that turn a
+config object into the exact manifest JSON and service-worker source a hand-written PWA needs
+(precache the app shell, network-first for same-origin requests, cache-first for the pinned CDN
+build). Define the variables once, regenerate the files whenever they change:
+
+```js
+// baseui.pwa.config.js
+export default {
+  manifest: {
+    name: "My App",
+    shortName: "MyApp",
+    description: "One sentence about the app.",
+    themeColor: "#0f172a",
+  },
+  serviceWorker: {
+    cacheName: "my-app-cache-v1",
+    cdnVersion: "1.1.1", // pin to match the importmap in index.html
+    appFiles: ["/app.css", "/app.js", "/app.xml", "/favicon.svg", "/icons/icon-192.png", "/icons/icon-512.png"],
+  },
+};
+```
+
+```sh
+npx create-baseui-app pwa . --config baseui.pwa.config.js
+# writes ./manifest.webmanifest and ./sw.js
+```
+
+Re-run the command whenever `appFiles`, the CDN pin, or manifest fields change — both output files are
+fully regenerated, never hand-patched. Only `manifest.name`, `serviceWorker.cacheName`, and
+`serviceWorker.cdnVersion` are required; everything else (icons, theme/background color, display
+mode, extra precache URLs) has the same defaults the `qr-page` example ships with. See
+`dist/types/pwa.d.ts` for the full config shape.
+
 ## 6. Copy a block instead of assembling from primitives
 
 For common layouts (dashboard shells, sidebars, login/signup forms, charts), copy a ready-made block from the gallery instead of composing primitives by hand: [Blocks](blocks.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebase/ui",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "CDN-installable Owl and Bootstrap 5 UI component library.",
   "type": "module",
   "main": "./dist/baseui.min.js",
@@ -25,6 +25,10 @@
       "import": "./dist/baseui.analytics.esm.js",
       "default": "./dist/baseui.analytics.min.js"
     },
+    "./pwa": {
+      "types": "./dist/types/pwa.d.ts",
+      "import": "./dist/baseui.pwa.esm.js"
+    },
     "./dist/baseui.templates.xml": "./dist/baseui.templates.xml"
   },
   "files": [
@@ -35,6 +39,7 @@
     "dist/baseui.icons.esm.js",
     "dist/baseui.analytics.esm.js",
     "dist/baseui.analytics.min.js",
+    "dist/baseui.pwa.esm.js",
     "dist/baseui.templates.xml",
     "dist/icons",
     "dist/baseui.registry.json",