redweb 0.16.1 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.16.2
+
+- Make `redweb init` generate a neutral, runnable TypeScript/TSX foundation by default so tutorials and original applications share one low-boilerplate starting structure.
+- Add composable `--with auth,multiplayer` dependency profiles without copying dashboard, chat, counter, or game-domain source. Keep named templates as explicit finished examples.
+- Add `--bare` as the same application foundation without its test directory, test scripts, or test-only coverage dependency. Report the selected foundation, capabilities, and test inclusion in machine-readable and human CLI output.
+- Cover the generated default with unit tests and actual CLI, TypeScript, HTTP, CSS, rerun, and lifecycle integration checks; no mocks or fixed-duration soak tests.
+
 ## 0.16.1
 
 - Refresh API and guide examples around concise `defineApp`, plain decorated pages, reusable TSX components, CSS, and connected clients. Keep lower-level HTTP, socket, template, and protocol APIs explicitly documented as alternatives.

package/README.md

@@ -8,21 +8,23 @@ Redweb 0.14.0 adds [`defineApp({ pages, sockets, services, port })`](docs/APPLIC
 
 ## Install
 
-Start with a complete, tested counter application:
+Start with a neutral, tested application foundation:
 
 <!-- redweb:setup:start -->
-> Documentation for Redweb 0.16.1. Install that exact version when following these examples.
+> Documentation for Redweb 0.16.2. Install that exact version when following these examples.
 
 ```sh
-npx --yes redweb@0.16.1 init my-realtime --template realtime
-cd my-realtime
-npm install --save-exact redweb@0.16.1
+npx --yes redweb@0.16.2 init my-app
+cd my-app
+npm install --save-exact redweb@0.16.2
 npm test
 npm run dev
 ```
 <!-- redweb:setup:end -->
 
-Open two tabs at `http://localhost:8181`. Clicking either button changes the counter on the server and updates both tabs.
+Append `--with auth,multiplayer` when you need those dependency sets without copying example-domain code. Use `--bare` only to omit generated tests. The application, CSS, TypeScript configuration, build scripts, and development watcher remain.
+
+The optional realtime example below is available with `redweb init my-realtime --template realtime`. Open two tabs at `http://localhost:8181`; clicking either button changes the counter on the server and updates both tabs.
 
 This is the starter's exact `src/app.tsx`. The initializer also supplies its stylesheet, compiler configuration, and real-network tests; startup and shutdown belong to Redweb itself. The file is not a standalone copy-and-run program.
 
@@ -58,7 +60,7 @@ if (require.main === module) void app.run().catch(error => { console.error(error
 
 ## Choose what to build
 
-The links below describe each starter and its boundaries. Reuse the version-correct setup above, changing both the directory name and `--template realtime` to your chosen template. Every initialized project includes all application files and real tests; complete generated recipe pages and file contents are also available in the [documentation catalogue](docs/generated.json).
+The links below describe each optional example and its boundaries. Reuse the version-correct counter setup above, changing both the directory name and `--template realtime` to your chosen template. Every non-bare initialized project includes all application files and real tests; complete generated recipe pages and file contents are also available in the [documentation catalogue](docs/generated.json).
 
 | Build | Starter | Recipe notes |
 | --- | --- | --- |

package/docs/CLI.md

@@ -4,7 +4,7 @@ Use the version installed in your project (`npx --no-install redweb`) when troub
 
 ## Add pages, components, and socket routes
 
-These commands are available in `redweb@0.16.1`.
+These commands are available in `redweb@0.16.2`.
 
 ```sh
 npx --no-install redweb add page dashboard
@@ -35,7 +35,13 @@ Follow a [complete recipe's version-specific setup](GETTING_STARTED.md#start-wit
 
 The initializer creates missing files only. It does not install dependencies, run package scripts, or validate existing source code. A message saying initialization completed means the file operation completed, not that a preserved existing project is valid.
 
-`--template realtime|chat|site|socket|dashboard|http-ws` selects a complete runnable recipe. The default is `realtime`, a shared server-owned counter. `chat` includes the canonical reusable chat component, validated actions and its stylesheet; `site` has two non-live pages with a shared layout; `socket` exposes `/match` with separate `join`, `move`, and `resume` handlers, a shared Zod contract, and bounded in-memory sessions. The [dashboard](../recipes/dashboard/README.md) combines private live cards, SQLite persistence, explicit account provisioning, expiring sessions and account-wide sign-out. It requires Node 22.13+. The [http-ws starter](../recipes/http-ws/README.md) combines an HTTP health endpoint and a raw socket route on one explicitly owned listener. Each starter includes network tests, build/production instructions, and a development watcher. `--existing` and `--template` cannot be combined. The chat, socket and dashboard starters add Zod; Redweb itself does not require Zod or SQLite at runtime.
+Without a template, `redweb init my-app` creates a neutral, runnable TypeScript/TSX foundation. It contains one placeholder page, CSS, build/development scripts, and real HTTP/lifecycle tests, but no counter, chatroom, dashboard, or game-domain code. This is the common starting point for tutorials and new applications.
+
+`--with auth,multiplayer` composes optional dependency sets into that same foundation without generating another example. `auth` adds Express, Zod, their TypeScript declarations, and the Node 22.13+ requirement used by Redweb's native-SQLite authentication path. `multiplayer` adds Redweb Client and Zod. Either capability can be selected alone, the comma-separated list must not contain duplicates, and capabilities may also supplement an explicit example template.
+
+`--template realtime|chat|site|socket|dashboard|http-ws` explicitly selects a complete runnable example. `realtime` is a shared server-owned counter. `chat` includes the canonical reusable chat component, validated actions and its stylesheet; `site` has two non-live pages with a shared layout; `socket` exposes `/match` with separate `join`, `move`, and `resume` handlers, a shared Zod contract, and bounded in-memory sessions. The [dashboard](../recipes/dashboard/README.md) combines private live cards, SQLite persistence, explicit account provisioning, expiring sessions and account-wide sign-out. It requires Node 22.13+. The [http-ws starter](../recipes/http-ws/README.md) combines an HTTP health endpoint and a raw socket route on one explicitly owned listener. Templates are learning/reference applications, not prerequisites for starting a project.
+
+Every non-bare initialization includes network tests and a development watcher. `--bare` retains the same runnable source, CSS, manifest, compiler configuration, build scripts, and watcher, but omits the `test/` directory, test scripts, and the test-only coverage dependency. `--existing` cannot be combined with `--template`, `--with`, or `--bare`. The optional capability and template dependencies remain application-local; Redweb itself does not require Zod or SQLite at runtime.
 
 Doctor also checks the application's declared `engines.node` minimum (for example `>=22.13.0`). An incompatible runtime produces `PROJECT_NODE_UNSUPPORTED`. More complex ranges produce `PROJECT_NODE_UNCHECKED`, not a guessed success; npm remains responsible for its full engine-range interpretation. CI runs the dashboard acceptance tests on Node 22; older core compatibility jobs explicitly skip that recipe's runtime execution.
 
@@ -53,7 +59,7 @@ npx --no-install redweb doctor --json
 
 `--existing` creates only a missing `tsconfig.json`; it does not generate a new app, CSS, or package manifest. Adjust the generated source/output directories for your application. An existing `tsconfig.json` is never overwritten, even if it is incompatible.
 
-`--dry-run` does not create files or directories. `--json` reports a versioned result with `operation`, `root`, `created`, `skipped`, and `planned`. The shared file-plan writer preflights all destinations, including planned directory/file conflicts, case aliases and nonportable segments such as Windows device names, alternate streams and trailing dots/spaces. It rejects symbolic links/junctions in the destination's ancestor chain, including above the chosen project root. Exclusive creation prevents overwriting a file created concurrently.
+`--dry-run` does not create files or directories. `--json` reports a versioned result with `operation`, `foundation`, `capabilities`, `tests`, `root`, `created`, `skipped`, and `planned`. The shared file-plan writer preflights all destinations, including planned directory/file conflicts, case aliases and nonportable segments such as Windows device names, alternate streams and trailing dots/spaces. It rejects symbolic links/junctions in the destination's ancestor chain, including above the chosen project root. Exclusive creation prevents overwriting a file created concurrently.
 
 This is not a transactional installer or a lock on the filesystem tree. An operating-system error during writing can leave completed files, a partial attempted file, or new directories; the error reports completed writes and the attempted destination. Inspect those paths before retrying. Rerunning preserves existing files rather than repairing their contents. Another process must not rename or replace destination directories while generation runs.
 

package/docs/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # Development refresh and inspection
 
-This API is available in `redweb@0.16.1`. Use documentation matching the installed package before enabling it.
+This API is available in `redweb@0.16.2`. Use documentation matching the installed package before enabling it.
 
 ## Browser refresh
 

package/docs/GETTING_STARTED.md

@@ -4,7 +4,27 @@ Redweb renders TypeScript/TSX on Node.js and connects server-owned state and act
 
 It is not React, a browser component framework, a database, an identity provider, or a managed multiplayer platform. Do not use React hooks or import `react/jsx-runtime`. An edge-only host without Node listeners cannot run a live Redweb server; exported static pages need no Node runtime.
 
-## Start with a complete recipe
+## Start a project
+
+Create the same neutral foundation whether you are following a tutorial or starting your own application:
+
+```sh
+npx --yes redweb@0.16.2 init my-app
+cd my-app
+npm install --save-exact redweb@0.16.2
+npm test
+npm run dev
+```
+
+Add capability dependencies without importing example-domain code:
+
+```sh
+npx --yes redweb@0.16.2 init my-game --with auth,multiplayer
+```
+
+The default includes its real tests. `--bare` omits only the test directory, test scripts, and test-only coverage dependency; it retains the runnable application, CSS, compiler configuration, build scripts, and development watcher.
+
+## Explore complete recipes
 
 Choose one of these complete applications:
 
@@ -15,7 +35,7 @@ Choose one of these complete applications:
 - [HTTP and WebSockets](../recipes/http-ws/README.md): one listener, an HTTP health endpoint and a raw `/chat` route with an explicit cleanup owner.
 - [Private dashboard](../recipes/dashboard/README.md): persistent SQLite cards, account sessions and private live updates (Node 22.13+).
 
-Each generated recipe page contains its exact files, commands, limitations, and real HTTP/WebSocket acceptance tests. Follow that recipe's version-specific setup instructions rather than mixing an unreleased example with a published npm version.
+Named templates are finished examples rather than the default project structure. Each generated recipe page contains its exact files, commands, limitations, and real HTTP/WebSocket acceptance tests. Follow that recipe's version-specific setup instructions rather than mixing an unreleased example with a published npm version.
 
 Requirements: Node.js satisfying the package's `engines` field and npm. Use a supported Node.js release in production. TypeScript and the development watcher are installed by the starter. No React, frontend bundler or broker is required. Only the dashboard starter uses a database; its native SQLite requirement is recipe-local.
 
@@ -47,7 +67,7 @@ For private raw socket subscriptions, see [room authorization and shared request
 
 Build first. Deploy `dist/`, the package manifest, and the lockfile, then install runtime dependencies with `npm ci --omit=dev`. The starters are tested with `src/` unavailable after compilation. Configure HTTPS/WSS and a proxy that supports WebSocket upgrades when using a reverse proxy.
 
-These deployment commands require a verified release pair. `redweb@0.16.1` installs published `redweb-client@0.3.0` automatically through its dependency. Future unreleased Redweb changes require their matching tested tarball until a release containing them is published. The `npm link` workflow is local development only: a clean production install does not preserve that link.
+These deployment commands require a verified release pair. `redweb@0.16.2` installs published `redweb-client@0.3.0` automatically through its dependency. Future unreleased Redweb changes require their matching tested tarball until a release containing them is published. The `npm link` workflow is local development only: a clean production install does not preserve that link.
 
 Before public access, add authentication, authorization, trusted-origin policy, input/rate limits, application persistence where needed, and bounded shutdown. Treat reconnect/session tokens as credentials. Do not promise exactly-once delivery or durable sessions from an in-memory starter. See [operations](MULTIPLAYER_OPERATIONS.md) and [guarantees and limits](PRODUCTION_READINESS.md).
 

package/docs/MIGRATION.md

@@ -1,6 +1,6 @@
 # Upgrade an existing Redweb application
 
-Match the installed package to its versioned documentation. Redweb 0.16.1 contains the capabilities described by the 0.16.1 guides; a later development checkout may not match that release. See [release verification](RELEASE_TRUST.md) and the changelog shipped with your selected package. Keep your lockfile and rollback artifact, and run your own real HTTP/WebSocket/browser tests after upgrading.
+Match the installed package to its versioned documentation. Redweb 0.16.2 contains the capabilities described by the 0.16.2 guides; a later development checkout may not match that release. See [release verification](RELEASE_TRUST.md) and the changelog shipped with your selected package. Keep your lockfile and rollback artifact, and run your own real HTTP/WebSocket/browser tests after upgrading.
 
 ## 0.8 migration notes
 

package/docs/RELEASE_TRUST.md

@@ -41,18 +41,18 @@ An ordinary installation without this root policy can still select affected
 dependencies. No Express 5 migration, bundled fork or published shrinkwrap is
 introduced. Audit results remain time-sensitive and application-specific.
 
-For a published application, select an exact release, commit its lockfile, and use `npm ci` in CI/deployment. This guide is versioned for 0.16.1. Before registry publication, verify the packed candidate; after publication, repeat these registry checks from a clean application:
+For a published application, select an exact release, commit its lockfile, and use `npm ci` in CI/deployment. This guide is versioned for 0.16.2. Before registry publication, verify the packed candidate; after publication, repeat these registry checks from a clean application:
 
 ```sh
-npm view redweb@0.16.1 version engines dist.integrity dist.signatures dist.attestations gitHead --json
-npm install --save-exact redweb@0.16.1
+npm view redweb@0.16.2 version engines dist.integrity dist.signatures dist.attestations gitHead --json
+npm install --save-exact redweb@0.16.2
 npm audit signatures
 npm audit --omit=dev
 ```
 
 The signature command must run in the installed application directory. Keep TLS verification enabled and use a current npm CLI; a certificate/trust-store failure is not a reason to disable verification. A lockfile's integrity value detects changed package bytes; registry signatures authenticate registry metadata; provenance, when present and verified, links an artifact to a build/source identity. Vulnerability audit is a separate check against known advisories, not an application penetration test.
 
-Redweb 0.16.1 contains socket-bound TSX controls and connection-owned page state, unified application startup, server-rendered TSX, reactive state/actions, complete starters, shared socket contracts, authorization, diagnostics, lifecycle work, and bounded heartbeat grace described by these versioned guides. Keep the package and documentation version aligned; do not mix a development guide or a future checkout with 0.16.1 and assume newer APIs exist.
+Redweb 0.16.2 contains neutral composable initialization, socket-bound TSX controls and connection-owned page state, unified application startup, server-rendered TSX, reactive state/actions, complete starters, shared socket contracts, authorization, diagnostics, lifecycle work, and bounded heartbeat grace described by these versioned guides. Keep the package and documentation version aligned; do not mix a development guide or a future checkout with 0.16.2 and assume newer APIs exist.
 
 Redweb is pre-1.0. Consult the changelog and versioned guide before upgrading, run your own real HTTP/WebSocket/browser tests, and keep a rollback artifact. Patch/minor numbers and a compatible TypeScript build alone do not prove wire compatibility, preserved sessions, database compatibility or application authorization. HTTP-created live-page sessions are process-owned; a restart or rolling replacement does not migrate them automatically. Raw socket protocol versions are negotiated only when the route opts in, and application payload compatibility remains your contract.
 

package/docs/RUNTIME_DIAGNOSTICS.md

@@ -1,6 +1,6 @@
 # Understand failures before retrying
 
-Status: included in `redweb@0.16.1`.
+Status: included in `redweb@0.16.2`.
 
 Authentication identifies a visitor. Authorization decides what that visitor may do. Validation checks an input's shape. An application failure means server code or a dependency failed; it is not evidence that the visitor supplied bad credentials.
 

package/docs/SOCKET_CONTRACTS.md

@@ -1,10 +1,10 @@
 # Shared socket contracts
 
-Status: included in `redweb@0.16.1`.
+Status: included in `redweb@0.16.2`.
 
 A contract declares message payloads once. The same schema supplies runtime validation and inferred TypeScript types for senders and handlers. The URL still selects the route (`/match`), and the envelope's `type` selects an individual handler (`join`, `move`, `resume`). No socket decorators or second action dispatcher are required.
 
-Start with `npx --yes redweb@0.16.1 init my-match --template socket`. The complete maintained example lives in [the socket recipe](../recipes/socket/README.md): [contract](../recipes/socket/contract.ts), [handlers](../recipes/socket/handlers.ts), [server](../recipes/socket/app.tsx), and [real-network tests](../recipes/socket/app.test.cjs).
+Start with `npx --yes redweb@0.16.2 init my-match --template socket`. The complete maintained example lives in [the socket recipe](../recipes/socket/README.md): [contract](../recipes/socket/contract.ts), [handlers](../recipes/socket/handlers.ts), [server](../recipes/socket/app.tsx), and [real-network tests](../recipes/socket/app.test.cjs).
 
 Session ownership is separate from room fan-out. For authenticated group delivery,
 see [room authorization](ROOM_AUTHORIZATION.md) and the complete