generator-white-label 5.0.1 → 9.0.0

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/.yarnrc.yml

@@ -0,0 +1,6 @@
+nodeLinker: node-modules
+npmPreapprovedPackages:
+  - "white-label-mediator"
+  - "white-label-model"
+  - "white-label-router"
+  - "white-label-view"

package/CLI.md

@@ -0,0 +1,82 @@
+# White Label CLI
+
+White Label has one project-creation engine and a thin command-line adapter.
+
+```text
+CLI ──────> createProject() ──────> project
+Node API ─┘
+```
+
+`createProject()` owns the scaffold, including destination safety. The CLI translates command-line input into that API.
+
+## Create a project
+
+With a globally installed CLI:
+
+```sh
+white-label create my-project
+```
+
+Or run the package directly with the package manager you prefer:
+
+```sh
+npx generator-white-label create my-project
+yarn dlx generator-white-label create my-project
+pnpm dlx generator-white-label create my-project
+```
+
+Project creation accepts a missing or existing **empty** directory. A non-empty destination is rejected before scaffold files are copied or written.
+
+Then install and test the generated project with npm, Yarn, or pnpm:
+
+```sh
+cd my-project
+npm install && npm test
+# or: yarn install && yarn test
+# or: pnpm install && pnpm test
+```
+
+When run interactively, the CLI asks whether page and view templates should use JSX/TSX. JSX is optional: choose **Yes** for White Label's first-party JSX syntax such as `<section>...</section>`, or **No** for plain TypeScript functions that return HTML strings. Both choices produce the same working starter application and features.
+
+Choose **No** when you want plain string templates or plan to use a third-party renderer. Install that renderer in the generated application and call it from the View `template` function; White Label does not require an adapter. See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for the tested third-party engines and rendering contract.
+
+For scripts and non-interactive use, choose explicitly:
+
+```sh
+white-label create my-project --jsx
+white-label create my-project --no-jsx
+
+npx generator-white-label create my-project --jsx
+npx generator-white-label create my-project --no-jsx
+```
+
+The same `--jsx` and `--no-jsx` flags work through `yarn dlx` and `pnpm dlx`.
+
+If no choice can be asked interactively and neither flag is supplied, JSX is the default.
+
+Run `white-label --help` for usage. See [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS.md) for package-manager compatibility details.
+
+## Use the API
+
+```js
+import {createProject} from 'generator-white-label';
+
+await createProject({
+    destination: '/absolute/path/to/my-project',
+    jsx: false
+});
+```
+
+Set `jsx: true` for JSX/TSX templates or `jsx: false` for plain TypeScript and HTML strings. Use `jsx: false` as the starting point when another template engine should own rendering. Omitting `jsx` defaults to `true`.
+
+`createProject()` uses the same destination-safety rule as the CLI: missing and empty directories are allowed; non-empty directories are rejected before project content is written.
+
+## Read the implementation
+
+The source is intentionally small enough to teach the design:
+
+- `scaffold/index.ts` — project creation and destination-safety boundary
+- `cli/index.ts` — command-line adapter
+- `test/` — executable contracts
+
+Creation behavior belongs in one place. Future integrations should call `createProject()` rather than copy templates or reimplement generation logic.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 bshack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/PACKAGE_MANAGERS.md

@@ -0,0 +1,35 @@
+# Package manager support
+
+`generator-white-label` and the projects it creates support npm, Yarn, and pnpm.
+
+## Run the generator
+
+```sh
+npx generator-white-label create my-project
+yarn dlx generator-white-label create my-project
+pnpm dlx generator-white-label create my-project
+```
+
+The same `--jsx` and `--no-jsx` options are available through every invocation path. JSX is optional: use `--jsx` for the first-party White Label JSX runtime, or `--no-jsx` for plain TypeScript templates and as the starting point for a third-party template engine.
+
+See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for tested third-party renderers and the View rendering contract.
+
+## Work with a generated project
+
+After generation, use the package manager you prefer:
+
+```sh
+npm install && npm test
+yarn install && yarn test
+pnpm install && pnpm test
+```
+
+Generated manifests require the supported Node.js runtime but do not require a specific package manager. Nested scripts use Node's `--run` support instead of invoking npm internally.
+
+Generated projects use exact npm versions for the four first-party White Label packages. They also carry narrow install-script approvals for the dependencies that actually need lifecycle builds: `esbuild`, `@parcel/watcher`, and `white-label-view`. npm uses pinned `allowScripts` entries, Yarn uses pinned `dependenciesMeta` build permissions, and pnpm uses `onlyBuiltDependencies`.
+
+Yarn's package-age security gate is left enabled for ordinary dependencies. The generated `.yarnrc.yml` preapproves only `white-label-mediator`, `white-label-model`, `white-label-router`, and `white-label-view` so a newly published White Label release can be installed immediately without disabling Yarn's protection for the rest of the dependency graph.
+
+## Repository development
+
+The committed `package-lock.json` remains the generator repository's canonical dependency lockfile and npm remains the maintenance/audit path used by primary CI. Compatibility CI packs the real generator artifact and verifies its API and CLI under npm, Yarn, and pnpm. Alternate lockfiles are not committed merely for compatibility testing.

package/README.md

@@ -1,195 +1,303 @@
-# white-label
+# generator-white-label
 
-`white-label` is a Yeoman generator and build system for creating static websites. It provides a working project structure with Handlebars templates, Sass styles, Bootstrap, responsive images, and TypeScript sources compiled to bundled JavaScript.
+`generator-white-label` is a framework-independent TypeScript project generator for small, accessible, SEO-friendly sites with progressive enhancement, composable White Label primitives, and a provider-neutral Node.js function example.
 
-Use it when you want a small, understandable static-site foundation that you can brand and extend without adopting a full application framework.
+[Documentation](https://whitelabeljs.org/docs/generator/) · [API reference](https://whitelabeljs.org/api/#generator) · [Demo site](https://whitelabeljs.org/)
 
-## What it builds
+The project is also its own teaching tool. The landing page, README, source, and tests are meant to be read together:
 
-The project separates source files by responsibility:
+```text
+understand → see → build → verify
+```
+
+White Label does not prescribe a framework. It provides focused pieces that can be composed where useful and omitted where they are not.
+
+## The idea
+
+A typical interactive feature can be understood as a flow of responsibilities:
+
+```text
+URL / user action
+       ↓
+    Router
+       ↓
+   Mediator
+       ↓
+     Model
+       ↓
+      View
+       ↓
+      DOM
+```
+
+These are responsibilities, not mandatory layers. Static content can stay plain JSX or plain TypeScript HTML strings. A feature that does not need routing does not need a router.
+
+- [`white-label-router`](https://github.com/bshack/white-label-router) turns location into application intent.
+- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) coordinates application events.
+- [`white-label-model`](https://github.com/bshack/white-label-model) owns observable state.
+- [`white-label-view`](https://github.com/bshack/white-label-view) owns rendering and DOM lifecycle.
+- [`white-label-view/jsx-runtime`](https://github.com/bshack/white-label-view) provides optional escaped JSX without React or another template engine.
+
+The goal is simple boundaries with explicit composition.
+
+## Learn from the generated application
+
+The generated landing page demonstrates the same architecture it documents.
+
+Its static sections use either JSX functions or equivalent plain TypeScript HTML-string functions, depending on the generator choice. The task example then shows all four packages working together:
+
+```text
+TaskRouter
+    ↓ route intent
+TaskMediator
+    ↓ state operation
+TaskModel
+    ↓ observable state
+TaskView
+    ↓ render
+DOM
+```
+
+Both generated variants provide the same application behavior and progressive enhancement. The only difference is template syntax.
+
+## A simple View click event
+
+Use View lifecycle hooks to add and remove browser listeners with the same callback reference:
+
+```ts
+import View from 'white-label-view';
+
+class ButtonView extends View {
+    handleClick = () => {
+        console.log('Clicked');
+    };
+
+    addListeners() {
+        this.element.addEventListener('click', this.handleClick);
+        return this;
+    }
+
+    removeListeners() {
+        this.element.removeEventListener('click', this.handleClick);
+        return this;
+    }
+}
+```
+
+`addListeners()` runs when the View mounts. `removeListeners()` runs before replacement or destruction, so the listener lifecycle stays owned by the View.
+
+## Read the source
+
+For the default JSX scaffold, a useful reading order is:
+
+1. [`app/index.tsx`](app/index.tsx) — page composition.
+2. [`app/assets/view/sections/LiveExampleSection.tsx`](app/assets/view/sections/LiveExampleSection.tsx) — static composition around an interactive feature.
+3. [`app/assets/view/examples/tasks/TaskExample.tsx`](app/assets/view/examples/tasks/TaskExample.tsx) — shared JSX rendering.
+4. [`app/assets/script/tasks/TaskApplication.ts`](app/assets/script/tasks/TaskApplication.ts) — explicit dependency wiring.
+5. `TaskRouter`, `TaskMediator`, `TaskModel`, and `TaskView` — one responsibility at a time.
+6. [`server/handler.ts`](server/handler.ts) — provider-neutral `Request`/`Response` serverless composition.
+7. [`test/app.test.js`](test/app.test.js) and [`template-test/site.test.js`](template-test/site.test.js) — browser and generated-project contracts.
+
+The `--no-jsx` scaffold mirrors the same structure with `.ts` files and HTML-string render functions.
+
+Comments focus on why boundaries exist instead of narrating obvious TypeScript.
 
-- `app/*.hbs` contains pages.
-- `app/assets/markup` contains reusable Handlebars partials.
-- `app/assets/data/view` contains global and page-specific JSON data.
-- `app/assets/style` contains Sass entry points and partials.
-- `app/assets/script` contains TypeScript and TSX entry points.
-- `app/assets/image` and `app/assets/font` contain static assets.
-- `scripts/build.ts` turns those sources into a deployable `_deploy` directory.
+When documenting public APIs, examples use comments where they clarify intent, lifecycle, side effects, or non-obvious behavior. Public method documentation should also state the return value—including meaningful boolean/status values, chaining returns, `undefined`, promises, and relevant thrown/rejected errors.
 
-The build renders Handlebars pages, compiles Sass, bundles JavaScript with esbuild, copies static assets, and writes the deployment configuration to `assets/data/config.json`. `global.css` includes the complete compiled Bootstrap CSS followed by the project's styles.
+A useful rule when extending the project is:
 
-Generated formatting utilities use native `Intl` and `Date` APIs, so new projects do not need Lodash, Moment, or Numeral for the included examples.
+> Introduce an abstraction when it gives a concern a clear home, not merely to create another layer.
 
-## Requirements
+## Create a project
 
-- Node.js 20 or newer
-- npm 10 or newer
+Requirement:
 
-## Generate a new site
+- Node.js `^22.18.0` or `>=24.11.0`
 
-Install Yeoman and the generator, then run it in an empty project directory:
+Install the CLI globally with your preferred package manager, or run the package directly.
+
+With npm:
 
 ```sh
-npm install --global yo generator-white-label
-mkdir my-site
-cd my-site
-yo white-label
+npx generator-white-label create my-project
 ```
 
-The generator copies the `app` and `scripts` directories and creates a project `package.json`. It intentionally does not install dependencies automatically, so you can review that manifest first:
+With Yarn:
 
 ```sh
-npm install
-npm test
+yarn dlx generator-white-label create my-project
 ```
 
-## Build the site
+With pnpm:
+
+```sh
+pnpm dlx generator-white-label create my-project
+```
+
+A global install also exposes the `white-label` command:
+
+```sh
+npm install --global generator-white-label
+white-label create my-project
+```
 
-A build with defaults is enough for local inspection:
+After generation, use npm, Yarn, or pnpm consistently within the project:
 
 ```sh
-npm run build
+cd my-project
+npm install && npm test
+# or: yarn install && yarn test
+# or: pnpm install && pnpm test
 ```
 
-The generated site is written to `_deploy`. Each asset build is placed under `_deploy/release/<version>/assets`; when no version is supplied, the build uses the current Unix timestamp.
+Interactive creation asks whether templates should use JSX/TSX. JSX is optional: choose **Yes** for White Label's first-party JSX syntax such as `<section>...</section>`, or **No** for plain TypeScript functions that return HTML strings. Both choices generate the same functional starter application.
 
-For a deployment build, pass explicit values after `--`:
+Choose the no-JSX path when another template engine should own rendering. Install that engine in the generated application and call it from the View `template` function; no White Label adapter is required. White Label View currently tests Handlebars, Eta, EJS, Mustache, Nunjucks, and Pug in both browser and server rendering. See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for tested versions, examples, the rendering contract, and security guidance.
+
+For explicit or non-interactive use:
 
 ```sh
-npm run build -- \
-  --www=https://www.example.com \
-  --cdn=https://cdn.example.com \
-  --service=https://api.example.com \
-  --version=2026.09.06 \
-  --production=true
+white-label create my-project --jsx
+white-label create my-project --no-jsx
+
+npx generator-white-label create my-project --jsx
+npx generator-white-label create my-project --no-jsx
 ```
 
-| Option | Default | Purpose |
-| --- | --- | --- |
-| `--www` | `/` | Public website base URL exposed to templates and configuration. |
-| `--cdn` | `/` | Asset base URL exposed to templates and configuration. |
-| `--service` | `/service-endpoint` | Backend service URL exposed to the site. |
-| `--version` | Current Unix timestamp | Directory name used for versioned assets. |
-| `--production` | `false` | Minifies CSS and JavaScript when set to `true`. |
+The same `--jsx` and `--no-jsx` options work through `yarn dlx` and `pnpm dlx`.
+
+If no interactive answer is available and neither flag is supplied, JSX is the default.
+
+The generator refuses to layer a scaffold over an existing non-empty destination. This protection is enforced by the shared `createProject()` engine, so it applies to both the CLI and programmatic use. An existing empty directory is allowed; a missing directory is created as part of generation.
 
-The version may contain only letters, numbers, dots, underscores, and hyphens. This prevents it from escaping the deployment directory.
+See [`CLI.md`](CLI.md) for the CLI contract and [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS.md) for package-manager compatibility details.
 
-## Add a page
+## Programmatic API
 
-Create `app/about.hbs`:
+Project creation has one implementation:
 
-```handlebars
-{{> element/head}}
-<main>
-    <h1>{{title}}</h1>
-    <p>{{introduction}}</p>
-</main>
+```js
+import {createProject} from 'generator-white-label';
+
+// Resolves after the scaffold files and package manifest have been written.
+await createProject({
+    destination: new URL('./my-project', import.meta.url).pathname,
+    jsx: false
+});
 ```
 
-Then create matching data at `app/assets/data/view/about.json`:
+Set `jsx: true` for JSX/TSX templates or `jsx: false` for plain TypeScript and HTML strings. Use `jsx: false` as the starting point for a third-party template engine. Omitting `jsx` defaults to `true`.
+
+`createProject(options)` returns `Promise<void>`. A successful call resolves with `undefined`; file-system failures reject the promise instead of returning a status value. If the destination already exists and contains files, it rejects before copying or writing project content.
+
+`createProject()` is the canonical creation API. The CLI and future integrations are adapters around it rather than separate generation systems. Keeping overwrite policy here prevents adapters from accidentally bypassing the same safety boundary.
+
+This is the same design principle used throughout White Label: one responsibility, one implementation, explicit adapters at environment boundaries.
+
+## Source layout
+
+| Path | Purpose |
+| --- | --- |
+| `scaffold/index.ts` | Canonical `createProject()` implementation and destination-safety boundary |
+| `scaffold/no-jsx/` | Plain-TypeScript template equivalents |
+| `cli/index.ts` | First-party command-line adapter |
+| `app/*.tsx` | Default JSX top-level static pages |
+| `app/assets/view/` | Default JSX views and page sections |
+| `app/assets/script/tasks/` | Model/View/Mediator/Router example |
+| `server/handler.ts` | Provider-neutral serverless `Request` → `Response` example |
+| `scripts/build.ts` | Static rendering and asset build for `.ts` and `.tsx` pages |
+| `test/` | Executable contracts and integration tests |
+| `template-test/` | Generated-project validation, including serverless portability budgets |
+
+No React, Bootstrap, Sass, Eta, Handlebars, Mustache, Nunjucks, Pug, web fonts, cloud SDK, or browser-side template framework is required. Third-party template engines and provider adapters remain optional application dependencies.
+
+## Template choice: JSX or no JSX
+
+JSX is optional. When enabled, TypeScript uses the White Label JSX runtime:
 
 ```json
 {
-  "title": "About us",
-  "introduction": "A short description of the organization."
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "white-label-view"
+  }
 }
 ```
 
-Global data from `app/assets/data/view/global.json`, page data, and build options are merged before the template is rendered. Page-specific values take precedence over global values, and build options take precedence over both.
-
-## Responsive images
+A page remains an ordinary function:
 
-The included `picture` partial supports AVIF and WebP sources at each responsive breakpoint, with an ordinary image as the final fallback:
-
-```handlebars
-{{> element/picture
-    imageFallback='assets/image/hero/fallback.jpg'
-    imageSmallAvif='assets/image/hero/small.avif'
-    imageSmallWebp='assets/image/hero/small.webp'
-    imageLargeAvif='assets/image/hero/large.avif'
-    imageLargeWebp='assets/image/hero/large.webp'
-    width='2048'
-    height='1600'
-    loading='lazy'
-    decoding='async'
-    alt='A human-readable description of the image'
-}}
+```tsx
+export default function Page(data: Record<string, unknown>) {
+    return <main><h1>{String(data.title)}</h1></main>;
+}
 ```
 
-Browsers choose the first supported source whose media query matches. Browsers without AVIF or WebP support use `imageFallback`. Supplying width and height also reserves layout space and helps avoid content movement while the image loads.
+With `--no-jsx`, the equivalent page is ordinary TypeScript returning an HTML string instead. The application architecture and generated features remain the same. That no-JSX scaffold is also the intended starting point when Handlebars, Eta, EJS, Mustache, Nunjucks, Pug, or another renderer should remain the project's template convention.
 
-## Development checks
+For larger pages, compose focused views instead of growing one renderer indefinitely.
 
-Run the same basic checks before proposing a change:
+White Label JSX HTML-escapes ordinary child text and ordinary attribute values by default, rejects intrinsic `on*` event-handler attributes, and uses runtime-owned identity for trusted JSX/raw values. That escaping is not a general-purpose sanitizer for URL or CSS semantics. Plain-TypeScript templates and third-party engines likewise remain responsible for their own contextual escaping, sanitization, raw-output features, and configuration. See [Template engines and JSX options](https://whitelabeljs.org/docs/view/#template-engines) for the tested matrix and trust boundaries.
 
-```sh
-npm run build
-npm run typecheck
-npm test
-npm run coverage
-npm run audit
-```
+## Progressive enhancement
 
-## Version 4 migration notes
+The generated project renders meaningful HTML during the build. Interactive task filters are real links first and are enhanced with History API navigation after initialization.
 
-Version 4 intentionally replaced the unsupported Gulp 3, Babel 6, PhantomJS, Karma, Bower, and legacy plugin pipeline. It also replaced Foundation with Bootstrap 5.3.8 and migrated the grid markup to Bootstrap `row` and responsive `col-*` classes. Projects upgrading from an older major version should treat the build tooling, supported Node.js versions, CSS framework, and generated markup as breaking changes.
+The principle is intentional:
 
-Version 4.1 removes Lodash, Moment, and Numeral from generated projects. If application code added its own imports from those packages, either retain the dependency in that application or migrate those calls before upgrading.
+```text
+HTML owns semantics.
+JavaScript enhances behavior.
+```
 
-## Related packages
+## Serverless and function runtimes
 
-- [`white-label-model`](https://github.com/bshack/white-label-model) provides event-emitting models and collections.
-- [`white-label-view`](https://github.com/bshack/white-label-view) renders templates and manages delegated DOM events.
-- [`white-label-router`](https://github.com/bshack/white-label-router) provides History API navigation.
-- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) provides shared application messaging.
-- [`white-label-service`](https://github.com/bshack/white-label-service) provides an authenticated JSON service backed by MySQL.
+Every generated project includes `server/handler.ts`, a provider-neutral example built around the Web `Request` and `Response` APIs. It composes Router, Mediator, Model, and `white-label-view/server` without Express or a provider SDK.
 
-## TypeScript development and version 5.0.0 migration
+Mutable White Label instances are created inside `handleRequest()`. This is intentional: serverless hosts can reuse a warm process for many requests, so mutable module-level Model/View/Router/Mediator instances can leak request data or listeners. Immutable configuration can still be shared at module scope when its lifetime is intentionally process-wide.
 
-Implementation code now uses strict TypeScript. Builds emit JavaScript, source maps with embedded source, and `.d.ts` declarations into `dist`. JavaScript callers can still use the package without compiling TypeScript themselves. JSDoc comments describe parameters, return values, lifecycle behavior, and validation at the implementation, and are retained in declarations.
+Cloud-specific adapters should stay at the boundary. Translate an AWS/Vercel/Netlify/Azure/etc. request into a Web `Request` when necessary, call `handleRequest()`, and translate the returned `Response` back only if the provider requires it.
 
-```ts
-// app/assets/script/profile.ts
-import User from './model/user.js';
+Generated-project tests exercise sequential warm invocations, concurrent requests, request-data escaping, execution without browser globals, and a browser/Web-target bundle smoke test. They also enforce a 100 kB minified serverless-composition bundle budget and a 750 ms fresh-process handler-import budget. These are regression guards, not universal latency guarantees.
 
-const profile = new User({name: 'Ada'});
-console.log(profile.get().name);
-```
+The Web-target bundle smoke test catches unresolved Node built-ins, but it does **not** claim blanket Cloudflare/Deno/edge-provider compatibility. The published runtime packages document Node as their supported server runtime; verify a specific edge provider before deployment.
 
-Write implementation files as `.ts`, or `.tsx` for React markup. Keep `.js` extensions on relative imports: TypeScript resolves them to source files and emits imports usable by Node. Every top-level script entry is bundled, except declaration-only `.d.ts` files. The build checks all sample modules, including modules not imported by an entry point.
+## Build and verify
 
-The generated project uses the current typed releases of `white-label-model` and `white-label-view`. The `types.d.ts` file declares only the optional SDK callbacks placed on `window`; package API types come directly from those dependencies.
+The repository keeps npm as its canonical maintenance/audit path and committed lockfile. Generated projects support npm, Yarn, and pnpm.
 
-Version 5 is a major release because generated projects now contain TypeScript and use a two-stage TypeScript/esbuild pipeline. Use Node.js 24 for development and CI. Existing generated sites are not changed automatically: migrate their script files, copy the new build configuration, and resolve strict type errors before deploying. The small `generators/app/index.js` file is only Yeoman's discovery bridge to compiled TypeScript.
+Development build:
 
-The generated project includes its own README. Full Bootstrap CSS remains included. Old inactive Gulp and Karma configuration has been removed; all historical share-URL assertions now run in the active Node test suite.
+```sh
+npm run build -- --version=local
+python3 -m http.server 8080 --directory _deploy
+```
 
-### Sample utility reference
+Production build:
 
-| Module | Functionality and example |
-| --- | --- |
-| `utility/ajax.ts` | `getScript('/sdk.js')` appends an asynchronous script; call it only when needed. |
-| `utility/form.ts` | Read multiselect values, select or find an option, decorate/split metadata, and build named options: `buildOptions([{id: 1, name: 'Ada'}], 1)`. Metadata helpers mutate their supplied arrays. |
-| `utility/string.ts` | Parse trusted HTML, read query values, format local dates, numbers and USD currency, and create phone/email links: `formatCurrency(12.5)` returns `$12.50`. `getQueryStringParamater` retains its historical spelling. |
-| `utility/share.ts` | Construct encoded Facebook, Twitter, LinkedIn and email URLs. Missing required values return `false`. Twitter retains its legacy 140-character rule; Google Plus support is a deprecated URL formatter for a discontinued service. |
-| `utility/regex.ts` | Legacy presentation-validation expressions for dates, passwords, phone numbers, ZIP codes, length and currency. These are not substitutes for server validation or a modern password policy. |
-| `model/user.ts` | An extendable observable object model. Country/state singletons contain the bundled JSON data. The global model starts with local URL defaults; the build separately writes deployment settings to `assets/data/config.json`. |
-| `api/facebook.ts`, `api/youtube.ts` | Optional SDK adapters that emit readiness events through the shared mediator. They are tested with local browser doubles, not live provider accounts. Review provider configuration before enabling them in a real site. |
-| `view/default.tsx` | A React greeting component: `<HelloMessage name="Ada" />`. |
-| `view/toolkit/youtube-player-1.ts` | An extension skeleton for a concrete player, with the legacy `removeListners` hook retained. |
-
-### Verification and coverage
+```sh
+npm run build -- \
+  --version=production \
+  --production=true \
+  --site-url=https://www.example.com
+```
+
+Verification:
 
 ```sh
-npm ci --ignore-scripts
-npm run typecheck
+npm run lint
 npm test
 npm run coverage
+npm run audit
 npm pack --dry-run
 ```
 
-`npm test` builds the code, checks TypeScript consumer examples against the emitted declarations, and runs the tests. `npm run coverage` additionally enforces **100% statements, branches, functions, and lines for each implementation file**. Unexecuted implementation files count toward the result; declaration-only files contain no executable code and are excluded. Reports are written to `coverage`, including `lcov.info` for coverage viewers. CI runs the same gate and checks committed build output for drift.
+Tests are part of the documentation. They demonstrate intended contracts while protecting behavior. Executable project source is held to 100% statement, branch, function, and line coverage. CI also checks the documented Node 22.18 minimum, the primary Node 24 line, packed CLI/programmatic API installation, and generated-project compatibility across npm, Yarn, and pnpm.
+
+## White Label ecosystem
 
-Tests exercise the compiled JavaScript interface used by downstream callers. Coverage is an execution metric, not proof that all possible inputs or external integrations are correct. Tests for third-party SDKs use local doubles. No live provider requests are needed.
+- [`white-label-model`](https://github.com/bshack/white-label-model) — observable state.
+- [`white-label-view`](https://github.com/bshack/white-label-view) — rendering, DOM lifecycle, optional JSX, and a template-engine-agnostic rendering contract.
+- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) — application events.
+- [`white-label-router`](https://github.com/bshack/white-label-router) — routing and URL state.
 
-To undo this migration, revert its commit and run `npm ci` from the restored lockfile. No npm release, database migration, or production deployment is performed by these development changes.
+The generated project imports the real packages rather than reproducing their behavior locally. That makes it both an example and an ecosystem integration test.

package/app/404.tsx

@@ -0,0 +1,28 @@
+interface PageData {
+    cdn: string;
+    version: string;
+    www: string;
+}
+
+export default function NotFoundPage(data: Record<string, unknown>) {
+    const page = data as unknown as PageData;
+    return (
+        <html lang="en-US" dir="ltr">
+            <head>
+                <meta charset="utf-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1" />
+                <meta name="robots" content="noindex,follow" />
+                <title>Page not found | White Label</title>
+                <link rel="stylesheet" href={`${page.cdn}release/${page.version}/assets/style/global.css`} />
+            </head>
+            <body>
+                <a className="skip-link" href="#main">Skip to the message</a>
+                <main id="main" tabindex="-1" className="mx-auto max-w-5xl px-4 py-24 sm:px-6 lg:px-8">
+                    <h1 className="text-5xl font-extrabold tracking-tight">Page not found</h1>
+                    <p className="mt-6 text-lg">The requested page does not exist.</p>
+                    <p className="mt-6"><a className="font-bold underline" href={page.www}>Return to the White Label starter</a></p>
+                </main>
+            </body>
+        </html>
+    );
+}