@thebase/ui 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project are documented in this file.
 
+## [Unreleased]
+
+## [v1.1.3] - 2026-10-13
+
+### Added
+- `ApiDoc` component (`b-ui="apidoc"` / pure Owl `ApiDoc`): renders an OpenAPI 3 JSON document as browsable API documentation — grouped sidebar, per-operation parameters, request body, responses, callbacks, a Try It panel with request samples in 17 languages, and an Authorize dialog (API key, HTTP basic, bearer, OpenID Connect, OAuth2 flows). Props include `src`, `spec`, `serverUrl`, `theme`, `themeToggle`, `hash`, `operation`, `tryIt`, `authorize`, `languages`, `language`, `assetBase`, `oauthRedirectUri`, `height`; events `baseui:load`, `baseui:error`, `baseui:navigate`. Built from BaseUI's own `Button`, `Badge`, `Dialog`, `Tabs`, `Breadcrumb`, `Input`, `Textarea`, `NativeSelect` and `Checkbox`. See `docs/components/apidoc.md`.
+- `apidoc-01` block (full-page API reference) and the `examples/apidoc/` demo with a Petstore spec.
+- `Input`: Material-style outlined mode with `label`, `supportingText`, `errorText`, `leadingIcon`/`trailingIcon` and a `maxLength` counter (documented in `docs/components/input.md`).
+- PWA toolkit: default logo and favicon set (`dist/pwa-icons/`: `favicon.ico`, 16/32 px favicons, `apple-touch-icon.png`, `icon-192.png`, `icon-512.png`). `create-baseui-app pwa` copies it into `<path>/icons/` without overwriting existing files, and the default manifest icons and precache list point at it. New optional `iconsBase` (manifest + service worker) and `manifestUrl` (service worker) config keys.
+- Examples: the examples/landing site is now an installable, offline-capable PWA (`examples/pwa/`, generated from `baseui.pwa.config.js`). The service worker is served from `/examples-sw.js`; `deploy_landing.sh` stages it at the site root. New `momo_demo/` static `b-ui` business-admin demo.
+- Build: ApiDoc's language logos are copied to `dist/apidoc/img/` and published (`dist/apidoc` added to `package.json` `files`).
+
+### Changed
+- PWA toolkit: the default precache list no longer includes `/favicon.svg`; it precaches the default icon files instead.
+- `npm run dev` server: serves `.ico` as `image/x-icon` and `.mjs` as JavaScript.
+- Docs and examples: production pin examples now use `@1.1.3`; component counts in `docs/owl-components.md` and `docs/registry.md` now say 74.
+
+## [v1.1.2] - 2026-10-06
+
+Backfilled entry (1.1.2 shipped without release notes).
+
+### Added
+- PWA toolkit: `@thebase/ui/pwa` (`dist/baseui.pwa.esm.js`, types in `dist/types/pwa.d.ts`) exports `buildManifest` and `buildServiceWorker`.
+- `create-baseui-app` CLI: `create`, `init`, `convert` and `pwa` commands to scaffold a BaseUI project and generate `manifest.webmanifest` + `sw.js`. See `docs/usage-guide.md` §5b and `docs/components/pwa.md`.
+- Examples: the landing page shows PWA install and visitor tracking (`examples/tracking.js`).
+
 ## [v1.1.1] - 2026-10-04
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ The Base UI is a CDN-installable UI kit built with Bootstrap 5 styling and Owl-e
 
 Its strong points: **no build step** — every component runs straight from a CDN `<script>`/import map, nothing to compile; **modular component design** — each component is a self-contained unit you import or mark up individually, not a monolith; **vanilla JavaScript/TypeScript** — no framework lock-in, no JSX, no compiler-specific syntax to learn; and this combination makes it well suited to building **WYSIWYG website builders**, where components must mount, unmount, and re-render dynamically from user-driven markup or drag-and-drop edits rather than a fixed build-time component tree.
 
-Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. 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, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
+Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@1.1.3`, or `@1` to take only non-breaking updates) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
@@ -50,7 +50,7 @@ If you have no Owl app, use the static `b-ui` markup adapter instead — one sty
 
 `dist/baseui.min.js`/`baseui.esm.js` are fully self-contained and back both APIs above: Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper are all embedded in load order (Bootstrap, then Owl, then BaseUI) — one file, nothing else to load first. There is no separate `baseui.owl.*`/`baseui.components.esm.js`/`baseui.theme.esm.js`. (`dist/bootstrap.bundle.min.js` still ships standalone, unmodified, for a project that wants vendored Bootstrap JS on its own — BaseUI itself never needs it loaded separately.)
 
-BaseUI exposes every component (73 in the current registry) as a real Owl component class — see [Pure Owl Components](docs/owl-components.md) for the complete API, npm/bundler usage, and mixing with the static adapter.
+BaseUI exposes every component (74 in the current registry) as a real Owl component class — see [Pure Owl Components](docs/owl-components.md) for the complete API, npm/bundler usage, and mixing with the static adapter.
 
 For app-level theme controls, import `createThemeController`/`BaseUITheme` as `@base/theme` in browser import maps (pointing at the same `dist/baseui.esm.js`) or straight from `@thebase/ui` in npm/bundler apps, to create persisted light/dark toggles like the documentation pages use.
 
@@ -70,9 +70,24 @@ BaseUI also ships an optional, cookieless web-analytics service (from 1.1.0). It
 
 From npm, use `import { init, track } from "@thebase/ui/analytics"`; for a classic `<script>` tag, `dist/baseui.analytics.min.js` sets `window.thebase.analytics`. It covers automatic and SPA pageviews, engagement (time on page and scroll depth), outbound links, file downloads, form submissions, and `thebase-event-*` class tagging. See [Analytics](docs/analytics.md) for every option, the payload format, opt-out, and sample Go Fiber / FastAPI backends. [`examples/analytics/`](examples/analytics/) holds a ready-to-run BaseUI dashboard for the collected data.
 
+## PWA toolkit and CLI
+
+BaseUI can scaffold and ship installable apps (from 1.1.2). The `create-baseui-app` CLI creates a static-importmap or Vite project (`create`, `init`, `convert`) and generates `manifest.webmanifest`, `sw.js` and a default icon set (`pwa`, icons from 1.1.3); the same generators are exported from `@thebase/ui/pwa` as `buildManifest` / `buildServiceWorker`.
+
+```sh
+npx create-baseui-app create my-app
+npx create-baseui-app pwa . --config baseui.pwa.config.js
+```
+
+See [Usage Guide §5b](docs/usage-guide.md) and the [PWA component](docs/components/pwa.md). The examples site itself is an installable PWA (`examples/pwa/`).
+
+## ApiDoc
+
+New in 1.1.3: `ApiDoc` (`b-ui="apidoc"`) renders an OpenAPI 3 JSON file as browsable API docs — grouped sidebar, parameters, request bodies, responses, a Try It panel with code samples in 17 languages, and an Authorize dialog. See [ApiDoc](docs/components/apidoc.md), the `apidoc-01` block, and the live demo in [`examples/apidoc/`](examples/apidoc/).
+
 ## Release notes
 
-See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current version: **1.1.1**.
+See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current version: **1.1.3**.
 
 ## Versioning policy
 
@@ -91,7 +106,7 @@ What each release type means:
 
 Anything prefixed `_`, undocumented internals, and the `docs/`/`examples/` sources are not part of the public API. Neither are the source-level authoring helpers described in [Component Authoring](docs/component-authoring.md) (`optional()`, `slotProps`, the `open-state.js` hooks, `bindBootstrapOverlay()`): they aren't exported from the package and may change in any release. Deprecated APIs keep working until the next major and are flagged in the CHANGELOG first.
 
-Pinning: use an exact version (`@1.1.1`) when you need byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.0.0` in npm) to receive fixes and features without breaking changes. Avoid `@latest` in production — it will move to the next major.
+Pinning: use an exact version (`@1.1.3`) when you need byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.0.0` in npm) to receive fixes and features without breaking changes. Avoid `@latest` in production — it will move to the next major.
 
 ## Project Documents
 
@@ -129,7 +144,7 @@ npm run build
 npm run dev
 ```
 
-Open `examples/index.html` through the dev server to test the browser build.
+Open `examples/index.html` through the dev server to test the browser build. Standalone demos: `examples/apidoc/` (ApiDoc with a Petstore spec), `examples/analytics/` (dashboard + Go/FastAPI backends), and `momo_demo/` (static `b-ui` business-admin page).
 
 `examples/index.html` is the single Owl app shell for docs, the component gallery, the block gallery, icons, and the chart catalog, all reachable through one `main-nav` and hash routes (`#/docs`, `#/components`, `#/blocks`, `#/icons`, `#/chart`). Old bookmarked URLs like `/docs` and `/blocks` redirect to their hash-route equivalent. Each block has a shadcn-style Preview/Code/responsive viewer plus its source stylesheet colocated in `examples/blocks/`. `examples/charts/index.html` mirrors the current shadcn chart catalog with interactive BaseUI examples for area, bar, line, pie, radar, radial, and tooltip charts, and is embedded inline at `#/chart`.
 
@@ -145,6 +160,6 @@ BaseUI includes the full Lucide SVG icon set as a built-in icon library. Use `<s
 
 ## Distribution
 
-The npm package publishes the built `dist/` artifacts plus package metadata. The browser build bundles Bootstrap CSS, and `dist/baseui.min.js`/`baseui.esm.js` embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's `.behavior.js`/`runtime/*.js` helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. `dist/bootstrap.bundle.min.js` also ships standalone (unmodified) and `dist/baseui.icons.esm.js` stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget), as does the opt-in analytics service (`dist/baseui.analytics.esm.js`/`.min.js`, so pages that don't track pay nothing for it) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.
+The npm package publishes the built `dist/` artifacts plus package metadata. The browser build bundles Bootstrap CSS, and `dist/baseui.min.js`/`baseui.esm.js` embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's `.behavior.js`/`runtime/*.js` helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. `dist/bootstrap.bundle.min.js` also ships standalone (unmodified) and `dist/baseui.icons.esm.js` stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget), as do the ApiDoc language logos (`dist/apidoc/img/`, loaded on demand) and the opt-in analytics service (`dist/baseui.analytics.esm.js`/`.min.js`, so pages that don't track pay nothing for it) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.
 
 The published tarball also carries `docs/*.md` and `docs/components/` (see the "Project Documents" section above), `README.md`, `CHANGELOG.md`, and `LICENSE` — `docs/v2/` and `docs/component-authoring.md` are deliberately excluded from `package.json`'s `files` list since they're development-time-only references for working inside this repo.

package/bin/create-baseui-app.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const ownPackageJson = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -16,13 +17,18 @@ function toPackageName(name) {
     .replace(/^-+|-+$/g, "") || "baseui-app";
 }
 
-/** Builds the fixed set of Vite + BaseUI scaffold files for a project named `appName`. */
-function buildTemplateFiles(appName, baseuiVersion) {
-  const title = appName
+/** Turns a kebab/snake-case app name into a human-readable title, e.g. "qr-page" -> "Qr Page". */
+function toTitle(appName) {
+  return appName
     .split(/[-_]/)
     .filter(Boolean)
     .map((word) => word[0].toUpperCase() + word.slice(1))
     .join(" ");
+}
+
+/** Builds the fixed set of Vite + BaseUI scaffold files for a project named `appName`. */
+function buildTemplateFiles(appName, baseuiVersion) {
+  const title = toTitle(appName);
 
   return {
     "package.json": JSON.stringify(
@@ -140,6 +146,375 @@ npm run dev
   };
 }
 
+/** Builds one page's HTML shell: mounts #app and loads that page's own entry script. */
+function pageHtml(title, entryScript) {
+  return `<!doctype html>
+<html lang="en" b-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body class="bg-body text-body">
+    <div id="app"></div>
+    <script type="module" src="${entryScript}"></script>
+  </body>
+</html>
+`;
+}
+
+/** Builds one page's entry script: loads its templates/component and mounts via the shared mountPage helper. */
+function pageMain(componentName, templatesImportPath, componentImportPath) {
+  return `import "@thebase/ui/baseui.css";
+import pageTemplates from "${templatesImportPath}?raw";
+import { ${componentName} } from "${componentImportPath}";
+import { mountPage } from "../mount-page.js";
+import "../style.css";
+
+await mountPage(${componentName}, pageTemplates);
+`;
+}
+
+/** Builds a 4-page Vite + BaseUI starter (landing, login, signup, an authenticated home shell) for a
+ * project named `appName` — each page is its own Owl root mounted by its own HTML entry, composed
+ * from the same blocks as `examples/blocks/login-03.html`, `signup-03.html` and `sidebar-02.html`. */
+function buildStarterFiles(appName, baseuiVersion) {
+  const title = toTitle(appName);
+
+  return {
+    "package.json": JSON.stringify(
+      {
+        name: appName,
+        private: true,
+        version: "0.0.1",
+        type: "module",
+        scripts: {
+          dev: "vite",
+          build: "vite build",
+          preview: "vite preview",
+        },
+        dependencies: {
+          "@thebase/ui": `^${baseuiVersion}`,
+        },
+        devDependencies: {
+          vite: "^8.2.1",
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+
+    "vite.config.js": `import { defineConfig } from "vite";
+import { fileURLToPath } from "node:url";
+
+/** Resolves a file in this config's own directory, Node-ESM-safe (no __dirname in ESM). */
+const here = (file) => fileURLToPath(new URL(file, import.meta.url));
+
+export default defineConfig({
+  server: { open: true },
+  build: {
+    rollupOptions: {
+      input: {
+        main: here("./index.html"),
+        login: here("./login.html"),
+        signup: here("./signup.html"),
+        home: here("./home.html"),
+      },
+    },
+  },
+});
+`,
+
+    ".gitignore": `node_modules/\ndist/\n`,
+
+    "public/favicon.svg": `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"
+  fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <rect width="24" height="24" rx="5" fill="#0f172a" stroke="none" />
+  <path d="M8 12h8" />
+  <path d="M12 8v8" />
+</svg>
+`,
+
+    "src/style.css": `/* App-specific styles layered on top of @thebase/ui/baseui.css go here. */\n`,
+
+    "src/mount-page.js": `import { mount } from "@thebase/ui";
+import baseuiTemplates from "@thebase/ui/dist/baseui.templates.xml?raw";
+
+/** Both files are full <templates>...</templates> documents; strip each one's outer wrapper before
+ * joining them, otherwise the merged string has two root elements and Owl's XML parser throws. */
+const stripTemplatesWrapper = (xml) =>
+  xml.replace(/^\\s*<templates[^>]*>/, "").replace(/<\\/templates>\\s*$/, "");
+
+/** Merges BaseUI's component templates with one page's own templates and mounts its root component. */
+export async function mountPage(Root, pageTemplatesXml) {
+  const templates = \`<templates>\${stripTemplatesWrapper(baseuiTemplates)}\${stripTemplatesWrapper(pageTemplatesXml)}</templates>\`;
+  await mount(Root, document.getElementById("app"), { templates });
+}
+`,
+
+    "index.html": pageHtml(title, "/src/landing/main.js"),
+    "src/landing/main.js": pageMain("Landing", "./Landing.xml", "./Landing.js"),
+    "src/landing/Landing.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, CardHeader, CardTitle, Icon } from "@thebase/ui";
+
+/** Marketing landing page: header with a login link, hero pitch, feature grid, footer. */
+export class Landing extends Component {
+  static template = "app.Landing";
+  static components = { Button, Card, CardBody, CardHeader, CardTitle, Icon };
+}
+`,
+    "src/landing/Landing.xml": `<templates xml:space="preserve">
+  <t t-name="app.Landing">
+    <div class="d-flex flex-column min-vh-100">
+      <header class="border-bottom">
+        <div class="container d-flex align-items-center justify-content-between py-3">
+          <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+            <Icon name="'gallery-vertical-end'"/>
+            ${title}
+          </a>
+          <Button variant="'outline'" onClick="() => window.location.assign('/login.html')">Login</Button>
+        </div>
+      </header>
+
+      <section class="container py-5 text-center">
+        <h1 class="display-5 fw-bold mb-3">Build faster with ${title}</h1>
+        <p class="lead text-muted mx-auto mb-4" style="max-width: 40rem">
+          A starter scaffold wired up with BaseUI — pure Owl components, Bootstrap styling, and the pages you need to ship day one.
+        </p>
+        <div class="d-flex justify-content-center gap-3">
+          <Button icon="'rocket'" onClick="() => window.location.assign('/signup.html')">Get started</Button>
+          <Button variant="'outline'" onClick="() => window.location.assign('/login.html')">Login</Button>
+        </div>
+      </section>
+
+      <section class="container py-5">
+        <div class="row g-4">
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'zap'"/><CardTitle>Fast by default</CardTitle></CardHeader>
+              <CardBody>Vite dev server and production build, pre-wired to BaseUI's CDN or local dist.</CardBody>
+            </Card>
+          </div>
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'layout-dashboard'"/><CardTitle>Pages included</CardTitle></CardHeader>
+              <CardBody>Landing, login, signup and an authenticated home shell, ready to extend.</CardBody>
+            </Card>
+          </div>
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'component'"/><CardTitle>Pure Owl components</CardTitle></CardHeader>
+              <CardBody>Every page composes real BaseUI components — swap or extend without fighting the markup.</CardBody>
+            </Card>
+          </div>
+        </div>
+      </section>
+
+      <footer class="border-top mt-auto">
+        <div class="container py-4 d-flex align-items-center justify-content-between">
+          <small class="text-muted">© ${title}. All rights reserved.</small>
+          <a href="/login.html" class="small text-decoration-underline">Login</a>
+        </div>
+      </footer>
+    </div>
+  </t>
+</templates>
+`,
+
+    "login.html": pageHtml(`Login — ${title}`, "/src/login/main.js"),
+    "src/login/main.js": pageMain("Login", "./Login.xml", "./Login.js"),
+    "src/login/Login.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "@thebase/ui";
+
+/** Login page (ported from examples/blocks/login-03.html): email/password card, redirects home on submit. */
+export class Login extends Component {
+  static template = "app.Login";
+  static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
+}
+`,
+    "src/login/Login.xml": `<templates xml:space="preserve">
+  <t t-name="app.Login">
+    <div class="d-flex flex-column align-items-center justify-content-center gap-4 min-vh-100 bg-body-tertiary p-4">
+      <div class="d-flex flex-column align-items-center gap-4 col-12 col-sm-8 col-md-6 col-lg-4">
+        <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+          <Icon name="'gallery-vertical-end'"/>
+          ${title}
+        </a>
+        <Card className="'w-100'">
+          <CardBody>
+            <form class="d-flex flex-column gap-4">
+              <div class="d-flex flex-column gap-2 text-center">
+                <h2 class="h4 mb-0">Login to your account</h2>
+                <p class="text-muted mb-0">Enter your email below to login to your account</p>
+              </div>
+              <FieldGroup>
+                <Field>
+                  <Label>Email</Label>
+                  <Input type="'email'" placeholder="'m@example.com'"/>
+                </Field>
+                <Field>
+                  <div class="d-flex align-items-center justify-content-between">
+                    <Label>Password</Label>
+                    <a href="#" class="small text-decoration-underline">Forgot your password?</a>
+                  </div>
+                  <Input type="'password'"/>
+                </Field>
+                <Button icon="'log-in'" onClick="() => window.location.assign('/home.html')">Login</Button>
+                <Button variant="'outline'" icon="'mail'">Login with email</Button>
+              </FieldGroup>
+              <p class="text-center small mb-0">Don&apos;t have an account? <a href="/signup.html" class="text-decoration-underline">Sign up</a></p>
+            </form>
+          </CardBody>
+        </Card>
+      </div>
+    </div>
+  </t>
+</templates>
+`,
+
+    "signup.html": pageHtml(`Sign up — ${title}`, "/src/signup/main.js"),
+    "src/signup/main.js": pageMain("Signup", "./Signup.xml", "./Signup.js"),
+    "src/signup/Signup.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "@thebase/ui";
+
+/** Signup page (ported from examples/blocks/signup-03.html): single email field, sends the user to login after submit. */
+export class Signup extends Component {
+  static template = "app.Signup";
+  static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
+}
+`,
+    "src/signup/Signup.xml": `<templates xml:space="preserve">
+  <t t-name="app.Signup">
+    <div class="d-flex flex-column align-items-center justify-content-center gap-4 min-vh-100 bg-body-tertiary p-4">
+      <div class="d-flex flex-column align-items-center gap-4 col-12 col-sm-8 col-md-6 col-lg-4">
+        <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+          <Icon name="'gallery-vertical-end'"/>
+          ${title}
+        </a>
+        <Card className="'w-100'">
+          <CardBody>
+            <form class="d-flex flex-column gap-4">
+              <div class="d-flex flex-column gap-2 text-center">
+                <h2 class="h4 mb-0">Create an account</h2>
+                <p class="text-muted mb-0">Enter your email below to create your account</p>
+              </div>
+              <FieldGroup>
+                <Field>
+                  <Label>Email</Label>
+                  <Input type="'email'" placeholder="'m@example.com'"/>
+                </Field>
+                <Button icon="'user-plus'" onClick="() => window.location.assign('/login.html')">Sign up</Button>
+                <Button variant="'outline'" icon="'mail'">Sign up with email</Button>
+              </FieldGroup>
+              <p class="text-center small mb-0">Already have an account? <a href="/login.html" class="text-decoration-underline">Login</a></p>
+            </form>
+          </CardBody>
+        </Card>
+      </div>
+    </div>
+  </t>
+</templates>
+`,
+
+    "home.html": pageHtml(`Home — ${title}`, "/src/home/main.js"),
+    "src/home/main.js": pageMain("Home", "./Home.xml", "./Home.js"),
+    "src/home/Home.js": `import { Component, useState } from "@thebase/ui";
+import {
+  Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator,
+  Button, Icon, InputGroup, InputGroupAddon, InputGroupInput, Separator,
+  Shell, ShellContent, ShellHeader, ShellMain, ShellNav, ShellSidebar, ShellSidebarHeader,
+  SidebarGroupCollapsible, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarTrigger,
+} from "@thebase/ui";
+
+/** Authenticated home shell (ported from examples/blocks/sidebar-02.html): collapsible sidebar nav
+ * + sticky header, reached after login/signup; owns the sidebar's collapsed/expanded state. */
+export class Home extends Component {
+  static template = "app.Home";
+  static components = {
+    Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator,
+    Button, Icon, InputGroup, InputGroupAddon, InputGroupInput, Separator,
+    Shell, ShellContent, ShellHeader, ShellMain, ShellNav, ShellSidebar, ShellSidebarHeader,
+    SidebarGroupCollapsible, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarTrigger,
+  };
+
+  setup() {
+    this.state = useState({ collapsed: false });
+  }
+}
+`,
+    "src/home/Home.xml": `<templates xml:space="preserve">
+  <t t-name="app.Home">
+    <Shell className="'border'" collapsed="state.collapsed" onCollapsedChange="(value) => { state.collapsed = value; }">
+      <ShellSidebar>
+        <ShellSidebarHeader>
+          <a href="/" class="d-flex align-items-center gap-2 text-decoration-none fw-medium">
+            <Icon name="'gallery-vertical-end'"/>
+            <span class="d-flex flex-column lh-sm">
+              <span>${title}</span>
+              <small class="text-body-secondary fw-normal">Dashboard</small>
+            </span>
+          </a>
+        </ShellSidebarHeader>
+        <InputGroup>
+          <InputGroupAddon><Icon name="'search'"/></InputGroupAddon>
+          <InputGroupInput type="'search'" placeholder="'Search...'"/>
+        </InputGroup>
+        <ShellNav className="'d-flex flex-column gap-2'">
+          <SidebarGroupCollapsible label="'Getting Started'" defaultOpen="true">
+            <SidebarMenu>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'layout-dashboard'" active="true">Overview</SidebarMenuButton></SidebarMenuItem>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'users'">Customers</SidebarMenuButton></SidebarMenuItem>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'settings'">Settings</SidebarMenuButton></SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarGroupCollapsible>
+        </ShellNav>
+      </ShellSidebar>
+      <ShellMain>
+        <ShellHeader className="'border-bottom p-3'">
+          <SidebarTrigger/>
+          <Separator orientation="'vertical'"/>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem><BreadcrumbPage>Overview</BreadcrumbPage></BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+          <Button variant="'outline'" size="'sm'" className="'ms-auto'" icon="'log-out'" onClick="() => window.location.assign('/index.html')">Logout</Button>
+        </ShellHeader>
+        <ShellContent className="'d-flex flex-column gap-3'">
+          <div class="row row-cols-3 g-3">
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+          </div>
+          <div class="flex-grow-1 bg-body-secondary rounded-4"></div>
+        </ShellContent>
+      </ShellMain>
+    </Shell>
+  </t>
+</templates>
+`,
+
+    "README.md": `# ${title}
+
+Scaffolded with \`@thebase/ui\`'s CLI (\`create-baseui-app init\`): Vite + BaseUI, pure Owl API, 4 pages.
+
+- \`/\` — landing page (header, hero, features, footer)
+- \`/login.html\` — login (redirects to \`/home.html\` on submit)
+- \`/signup.html\` — signup (redirects to \`/login.html\` on submit)
+- \`/home.html\` — authenticated home shell (sidebar + header, logout returns to \`/\`)
+
+None of the pages call a real backend yet — wire up \`Login\`/\`Signup\`'s button \`onClick\` handlers to
+your own auth API once you have one.
+
+\`\`\`sh
+npm install
+npm run dev
+\`\`\`
+`,
+  };
+}
+
 /** Writes each template file under targetDir, skipping any that already exist (convert mode is additive/non-destructive). */
 function writeFiles(targetDir, files, { overwrite }) {
   const written = [];
@@ -173,6 +548,7 @@ function parseFlags(argv) {
     if (arg === "--no-install") flags.install = false;
     else if (arg === "--force") flags.force = true;
     else if (arg === "--version") flags.version = argv[++i];
+    else if (arg === "--config") flags.config = argv[++i];
     else positional.push(arg);
   }
   return { flags, positional };
@@ -205,6 +581,37 @@ function cmdCreate(argv) {
   console.log(`\nNext steps:\n  cd ${rawName}${flags.install ? "" : "\n  npm install"}\n  npm run dev`);
 }
 
+/** Scaffolds the 4-page starter (landing/login/signup/home) in a new ./<app-name> folder. */
+function cmdInit(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const rawName = positional[0];
+  if (!rawName) {
+    console.error("Usage: create-baseui-app init <app-name> [--version <x.y.z>] [--no-install] [--force]");
+    process.exit(1);
+  }
+  const appName = toPackageName(rawName);
+  const targetDir = path.resolve(process.cwd(), rawName);
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !flags.force) {
+    console.error(`Directory "${rawName}" already exists and is not empty. Use --force to write into it anyway.`);
+    process.exit(1);
+  }
+
+  const baseuiVersion = flags.version || ownPackageJson.version;
+  const files = buildStarterFiles(appName, baseuiVersion);
+  const { written } = writeFiles(targetDir, files, { overwrite: flags.force ?? false });
+
+  console.log(`Scaffolded a 4-page Vite + BaseUI starter in ${targetDir}`);
+  written.forEach((f) => console.log(`  create ${f}`));
+
+  if (flags.install) runInstall(targetDir);
+
+  console.log(
+    `\nNext steps:\n  cd ${rawName}${flags.install ? "" : "\n  npm install"}\n  npm run dev` +
+      `\n\nPages: / (landing), /login.html, /signup.html, /home.html`,
+  );
+}
+
 function cmdConvert(argv) {
   const { flags, positional } = parseFlags(argv);
   const targetDir = path.resolve(process.cwd(), positional[0] || ".");
@@ -248,6 +655,46 @@ function cmdConvert(argv) {
   console.log(`\nNext steps:\n  npm run dev`);
 }
 
+/** Generates manifest.webmanifest + sw.js for a PWA from a `baseui.pwa.config.js` the user wrote,
+ * using @thebase/ui's buildManifest/buildServiceWorker (see docs/usage-guide.md "PWA toolkit"). */
+async function cmdPwa(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const targetDir = path.resolve(process.cwd(), positional[0] || ".");
+  const configPath = path.resolve(targetDir, flags.config || "baseui.pwa.config.js");
+
+  if (!existsSync(configPath)) {
+    console.error(
+      `Config file not found: ${configPath}\n` +
+        "Create it first — export default { manifest: {...}, serviceWorker: {...} }, " +
+        "see docs/usage-guide.md \"PWA toolkit\" for the full config shape.",
+    );
+    process.exit(1);
+  }
+
+  const { manifest, serviceWorker } = (await import(pathToFileURL(configPath).href)).default;
+  const { buildManifest, buildServiceWorker, DEFAULT_ICON_FILES } = await import("../dist/baseui.pwa.esm.js");
+
+  writeFileSync(
+    path.join(targetDir, "manifest.webmanifest"),
+    JSON.stringify(buildManifest(manifest), null, 2) + "\n",
+  );
+  writeFileSync(path.join(targetDir, "sw.js"), buildServiceWorker(serviceWorker));
+
+  copyDefaultIcons(path.join(targetDir, "icons"), DEFAULT_ICON_FILES);
+
+  console.log(`Wrote manifest.webmanifest and sw.js in ${targetDir}`);
+}
+
+/** Gives a PWA the default BaseUI logo/favicon set, without replacing any icon the app already has. */
+function copyDefaultIcons(iconsDir, files) {
+  mkdirSync(iconsDir, { recursive: true });
+  const source = new URL("../dist/pwa-icons/", import.meta.url);
+  for (const file of files) {
+    const target = path.join(iconsDir, file);
+    if (!existsSync(target)) copyFileSync(new URL(file, source), target);
+  }
+}
+
 function printHelp() {
   console.log(`@thebase/ui project CLI
 
@@ -258,6 +705,17 @@ Usage:
   create-baseui-app convert [path] [--version <x.y.z>] [--no-install]
       Turn an existing (non-npm) folder into a Vite + BaseUI project, in place.
       Never overwrites files that already exist; only fills in what's missing.
+
+  create-baseui-app init <app-name> [--version <x.y.z>] [--no-install] [--force]
+      Scaffold a ready-to-start 4-page project in ./<app-name>: a landing page
+      (header/hero/features/footer), login, signup, and an authenticated home
+      shell (sidebar + header) — ported from the login-03/signup-03/sidebar-02
+      example blocks.
+
+  create-baseui-app pwa [path] [--config <file>]
+      Generate manifest.webmanifest + sw.js in [path] (default ".") from a
+      baseui.pwa.config.js config file (default name, override with --config).
+      Also copies the default logo/favicon set into [path]/icons/ (existing files kept).
 `);
 }
 
@@ -265,4 +723,6 @@ const [, , command, ...rest] = process.argv;
 
 if (command === "create") cmdCreate(rest);
 else if (command === "convert") cmdConvert(rest);
+else if (command === "init") cmdInit(rest);
+else if (command === "pwa") await cmdPwa(rest);
 else printHelp();

package/dist/apidoc/img/bash-plain.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#293138" d="M112.205 26.129 71.8 2.142A15.326 15.326 0 0 0 64.005 0c-2.688 0-5.386.717-7.796 2.152L15.795 26.14C10.976 28.999 8 34.289 8 40.018v47.975c0 5.729 2.967 11.019 7.796 13.878L56.2 125.858A15.193 15.193 0 0 0 63.995 128a15.32 15.32 0 0 0 7.796-2.142l40.414-23.987c4.819-2.86 7.796-8.16 7.796-13.878V40.007c0-5.718-2.967-11.019-7.796-13.878zm-31.29 74.907.063 3.448c0 .418-.267.889-.588 1.06l-2.046 1.178c-.321.16-.6-.032-.6-.45l-.032-3.394c-1.745.728-3.523.9-4.647.45-.214-.086-.31-.397-.225-.761l.739-3.116c.064-.246.193-.493.364-.643a.725.725 0 0 1 .193-.139c.117-.064.235-.075.332-.032 1.22.407 2.773.214 4.272-.535 1.907-.964 3.18-2.913 3.16-4.84-.022-1.757-.964-2.474-3.267-2.496-2.934.01-5.675-.567-5.718-4.894-.032-3.555 1.81-7.26 4.744-9.595l-.032-3.48c0-.428.257-.9.589-1.07l1.98-1.264c.322-.161.6.043.6.46l.033 3.48c1.456-.578 2.72-.738 3.865-.47.247.064.364.406.257.802l-.77 3.084a1.372 1.372 0 0 1-.354.622.825.825 0 0 1-.203.15c-.108.053-.204.064-.3.053-.525-.118-1.767-.385-3.727.6-2.056 1.038-2.773 2.827-2.763 4.155.022 1.585.825 2.066 3.63 2.11 3.738.064 5.344 1.691 5.387 5.45.053 3.684-1.917 7.657-4.937 10.077zm21.18-5.794c0 .322-.042.621-.31.771l-10.216 6.211c-.267.161-.482.022-.482-.3V99.29c0-.321.193-.492.46-.653l10.067-6.018c.268-.16.482-.022.482.3zm7.026-58.993L70.89 59.86c-4.765 2.784-8.278 5.911-8.288 11.662v47.107c0 3.437 1.392 5.665 3.523 6.318a12.81 12.81 0 0 1-2.12.204c-2.239 0-4.445-.61-6.383-1.757L17.219 99.408c-3.951-2.345-6.403-6.725-6.403-11.426V40.007c0-4.7 2.452-9.08 6.403-11.426L57.634 4.594a12.555 12.555 0 0 1 6.382-1.756c2.238 0 4.444.61 6.382 1.756l40.415 23.987c3.33 1.981 5.579 5.397 6.21 9.242-1.36-2.86-4.38-3.63-7.902-1.574z"/></svg>

package/dist/apidoc/img/c-original.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#a9bacd" d="M125 50c-4-32-24-50-62-50C29 0 3 24 3 64c0 39 24 64 64 64 32 0 55-19 58-50H87c-2 11-8 20-20 20-21 0-24-16-24-33 0-23 8-35 22-35 13 0 20 7 22 20z" /></svg>

package/dist/apidoc/img/csharp-original.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#9B4F96" d="M115.4 30.7L67.1 2.9c-.8-.5-1.9-.7-3.1-.7-1.2 0-2.3.3-3.1.7l-48 27.9c-1.7 1-2.9 3.5-2.9 5.4v55.7c0 1.1.2 2.4 1 3.5l106.8-62c-.6-1.2-1.5-2.1-2.4-2.7z"/><path fill="#68217A" d="M10.7 95.3c.5.8 1.2 1.5 1.9 1.9l48.2 27.9c.8.5 1.9.7 3.1.7 1.2 0 2.3-.3 3.1-.7l48-27.9c1.7-1 2.9-3.5 2.9-5.4V36.1c0-.9-.1-1.9-.6-2.8l-106.6 62z"/><path fill="#fff" d="M85.3 76.1C81.1 83.5 73.1 88.5 64 88.5c-13.5 0-24.5-11-24.5-24.5s11-24.5 24.5-24.5c9.1 0 17.1 5 21.3 12.5l13-7.5c-6.8-11.9-19.6-20-34.3-20-21.8 0-39.5 17.7-39.5 39.5s17.7 39.5 39.5 39.5c14.6 0 27.4-8 34.2-19.8l-12.9-7.6zM97 66.2l.9-4.3h-4.2v-4.7h5.1L100 51h4.9l-1.2 6.1h3.8l1.2-6.1h4.8l-1.2 6.1h2.4v4.7h-3.3l-.9 4.3h4.2v4.7h-5.1l-1.2 6h-4.9l1.2-6h-3.8l-1.2 6h-4.8l1.2-6h-2.4v-4.7H97zm4.8 0h3.8l.9-4.3h-3.8l-.9 4.3z"/></svg>

package/dist/apidoc/img/dart-original.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#00c4b3" d="M35.2 34.9l-8.3-8.3v59.7l.1 2.8c0 1.3.2 2.8.7 4.3l65.6 23.1 16.3-7.2-74.4-74.4z"/><path d="M27.7 93.4zm81.9 15.9l-16.3 7.2-65.4-23.1c1.3 4.8 4 10.1 7 13.2l21.3 21.2 47.6.1 5.8-18.6z" fill="#22d3c5"/><path fill="#0075c9" d="M1.7 65.1C-.4 67.3.7 72 4 75.5l14.7 14.8 9.2 3.3c-.3-1.5-.7-3-.7-4.3l-.1-2.8-.2-59.8m82.7 82.6l7.2-16.4-23-65.6c-1.5-.3-3-.6-4.3-.7l-2.9-.1-59.6.1"/><path d="M93.6 27.3c.2 0 .2 0 0 0 .2 0 .2 0 0 0zm16 82l17.7-5.8V54.8l-20.4-20.5c-3-3-8.3-5.8-13.2-7l23.1 65.6" fill="#00a8e1"/><path fill="#00c4b3" d="M90.5 18.2L75.7 3.5c-3.4-3.4-8-4.4-10.4-2.3L26.9 26.6h59.5l2.9.1c1.3 0 2.8.2 4.3.7l-3.1-9.2z"/></svg>