create-koppajs 1.1.0 → 1.2.1

package/template/pnpm-lock.yaml

@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@koppajs/koppajs-core':
-        specifier: ^3.0.2
-        version: 3.0.2
+        specifier: ^3.0.3
+        version: 3.0.3
     devDependencies:
       '@commitlint/cli':
         specifier: ^20.1.0
@@ -22,8 +22,8 @@ importers:
         specifier: ^10.0.1
         version: 10.0.1(eslint@10.0.3(jiti@2.6.1))
       '@koppajs/koppajs-vite-plugin':
-        specifier: ^1.0.0
-        version: 1.0.0(typescript@5.9.3)(vite@7.2.6(@types/node@25.4.0)(jiti@2.6.1)(sass@1.97.1)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        specifier: ^1.0.1
+        version: 1.0.1(typescript@5.9.3)(vite@7.2.6(@types/node@25.4.0)(jiti@2.6.1)(sass@1.97.1)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@playwright/test':
         specifier: ^1.58.2
         version: 1.58.2
@@ -605,12 +605,12 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
-  '@koppajs/koppajs-core@3.0.2':
-    resolution: {integrity: sha512-wvgg6sbWZMSe6Qhqy4WwIdKpzfgdK5f7sTh5rZIJwmBUsvfzJ3mIjl/1xgfDcNWBw9ij9epoW41MzekCgTBbkw==}
+  '@koppajs/koppajs-core@3.0.3':
+    resolution: {integrity: sha512-l6e+M8hEugVW/4crOzddeImLM/0j+rqSJ5ZkFyBZPdv57Bp45WWdbmoK7HNKzPd+L70SehCaH7CcgRKM8ltbCQ==}
     engines: {node: '>=20', pnpm: '>=10.24.0'}
 
-  '@koppajs/koppajs-vite-plugin@1.0.0':
-    resolution: {integrity: sha512-tO1yyYOcHKTXqpbVOoMhdBmk9qw0DG2RcBUknpxVmPmMEXWysLXRRRFrkz0A/dOv72F1FrMN5OpIMztEvH6Hcg==}
+  '@koppajs/koppajs-vite-plugin@1.0.1':
+    resolution: {integrity: sha512-idjAD9zYQsK68yLxAI9So2bZScH7R4akDPsznHHivVCksMHSvkvQVtq328oeAg8rCi9AYN4z1Q0SAUB90aMDbg==}
     engines: {node: '>=20', pnpm: '>=10.24.0'}
     peerDependencies:
       typescript: '>=5.5 <6'
@@ -944,11 +944,6 @@ packages:
     peerDependencies:
       acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
 
-  acorn@8.15.0:
-    resolution: {integrity: sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==}
-    engines: {node: '>=0.4.0'}
-    hasBin: true
-
   acorn@8.16.0:
     resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
     engines: {node: '>=0.4.0'}
@@ -2411,11 +2406,11 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
-  '@koppajs/koppajs-core@3.0.2': {}
+  '@koppajs/koppajs-core@3.0.3': {}
 
-  '@koppajs/koppajs-vite-plugin@1.0.0(typescript@5.9.3)(vite@7.2.6(@types/node@25.4.0)(jiti@2.6.1)(sass@1.97.1)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
+  '@koppajs/koppajs-vite-plugin@1.0.1(typescript@5.9.3)(vite@7.2.6(@types/node@25.4.0)(jiti@2.6.1)(sass@1.97.1)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
-      acorn: 8.15.0
+      acorn: 8.16.0
       autoprefixer: 10.4.23(postcss@8.5.6)
       postcss: 8.5.6
       sass: 1.97.1
@@ -2726,8 +2721,6 @@ snapshots:
     dependencies:
       acorn: 8.16.0
 
-  acorn@8.15.0: {}
-
   acorn@8.16.0: {}
 
   agent-base@7.1.4:

package/template-overlays/router/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+This repository is a small KoppaJS router starter. It demonstrates a clear
+bootstrap path: HTML shell, TypeScript entrypoint, one root app shell
+component, one router instance, two primary routes, and one explicit not-found
+route. The repository also carries the same quality and release automation
+baseline as the minimal starter so the example remains production-like.
+
+## System overview
+
+- `index.html` provides the document shell, loads global CSS, declares the
+  `<app-view>` root element, and imports the TypeScript entrypoint.
+- `src/main.ts` registers local components with `Core.take(...)`, calls
+  `Core()` once, waits for the route outlet to exist, and initializes one
+  `KoppajsRouter` instance.
+- `src/app-view.kpa` is the root shell. It renders the hero area, the primary
+  navigation, and the `#app-outlet` container that receives route content.
+- `src/home-page.kpa` is the default route and composes `counter-component`.
+- `src/router-page.kpa` is the second route and explains the router wiring.
+- `src/not-found-page.kpa` is the explicit catch-all route.
+- `src/counter-component.kpa` remains the example local-state component.
+- `src/style.css` defines global tokens, base layout, and the background.
+- `tests/integration/` verifies bootstrap wiring and router startup.
+- `tests/e2e/` verifies the user-visible route flow and counter behavior.
+
+More detailed boundaries live in [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+
+## Runtime flow
+
+1. The browser loads [`index.html`](./index.html).
+2. The document loads [`src/style.css`](./src/style.css) and [`src/main.ts`](./src/main.ts).
+3. [`src/main.ts`](./src/main.ts) registers `app-view`, `home-page`,
+   `router-page`, `not-found-page`, and `counter-component`, then calls
+   `Core()`.
+4. KoppaJS instantiates `<app-view>`.
+5. [`src/app-view.kpa`](./src/app-view.kpa) renders the app shell, navigation,
+   and `#app-outlet`.
+6. `src/main.ts` initializes `KoppajsRouter` with the route table and outlet.
+7. The router renders the matching route component into `#app-outlet`,
+   synchronizes active links, and updates the current browser URL.
+
+## Quality automation layer
+
+- `eslint.config.mjs` lint-checks TypeScript source plus tooling files.
+- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent.
+- `.npmrc` enforces the declared engine floor during installs.
+- `.husky/pre-commit` runs `lint-staged`.
+- `.husky/commit-msg` validates commit headers with `commitlint`.
+- `.github/workflows/ci.yml` runs the full repository validation flow on GitHub.
+- `.github/workflows/release.yml` runs tagged release validation and creates GitHub Releases.
+
+## Module responsibilities
+
+| Module                      | Responsibility                                                   | Must not do                                            |
+| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| `index.html`                | Declare the root tag and static assets                           | Hold feature logic or router setup                     |
+| `src/main.ts`               | Bootstrap the app, register components, and start one router     | Accumulate page copy or unrelated UI state             |
+| `src/app-view.kpa`          | Render the shared shell, nav, and router outlet                  | Own route resolution or register components            |
+| `src/home-page.kpa`         | Render the landing route and compose the counter example         | Reach into router internals or mutate global DOM state |
+| `src/router-page.kpa`       | Render the second route and explain the router baseline          | Own bootstrap logic or global navigation state         |
+| `src/not-found-page.kpa`    | Render the explicit fallback route                               | Replace route matching or bootstrap responsibilities   |
+| `src/counter-component.kpa` | Demonstrate local interactive state                              | Reach into route orchestration or app-shell concerns   |
+| `src/style.css`             | Hold global tokens and truly global base styles                  | Duplicate component-local visuals                      |
+| `tests/integration/`        | Verify bootstrap and router-start boundaries                     | Duplicate full browser smoke expectations              |
+| `tests/e2e/`                | Verify visible navigation and counter behavior in a real browser | Assert brittle implementation details                  |
+
+## Invariants
+
+- There is exactly one bootstrap entrypoint.
+- The root tag in `index.html` must match a component registered in `src/main.ts`.
+- `Core()` is called once from `src/main.ts`.
+- The starter owns exactly one router instance.
+- The route table contains an explicit `*` fallback route.
+- Route rendering happens through `#app-outlet`.
+- Official releases require matching versions across `package.json`,
+  `CHANGELOG.md`, and `vX.Y.Z` tags.
+
+## Extension guidance
+
+- Add new route components under `src/` and register them from `src/main.ts`.
+- Keep route definitions in one obvious place.
+- Extract reusable route helpers into `.ts` modules only when logic becomes
+  shared or branch-heavy.
+- Add a spec before changing visible navigation behavior.
+- Add an ADR before changing the routing model, adding data fetching,
+  persistence, or another major subsystem.

package/template-overlays/router/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Change Log
+
+All notable changes to **__PROJECT_NAME__** are documented in this file.
+
+This project uses a **manual, tag-driven release process**.
+Only tagged versions represent official releases.
+
+This changelog documents **intentional milestones and guarantees**,
+not every internal refactor.
+
+---
+
+## [Unreleased]
+
+_No unreleased changes yet._
+
+---
+
+## [1.0.0] — Initial Starter Baseline
+
+**2026-03-17**
+
+### Added
+
+- a small KoppaJS router app shell with `app-view`, `home-page`,
+  `router-page`, `not-found-page`, and `counter-component`
+- route-based rendering through `@koppajs/koppajs-router`
+- ESLint, Prettier, Vitest, Playwright, Husky, lint-staged, and commitlint
+- starter governance docs, ADRs, specs, and release workflow files
+
+---
+
+## Versioning Policy
+
+- Semantic Versioning (SemVer) is followed pragmatically
+- **Breaking changes** include:
+  - public runtime behavior changes
+  - route structure changes
+  - release workflow changes
+
+---
+
+_This changelog documents intent.
+If something is not written here, it is not guaranteed._

package/template-overlays/router/DEVELOPMENT_RULES.md

@@ -0,0 +1,57 @@
+# Development Rules
+
+## Scope
+
+These rules describe how code and documentation are expected to evolve in this repository.
+
+## Source layout rules
+
+- Keep `index.html` as a static shell with asset references and the single root element.
+- Keep `src/main.ts` limited to bootstrap concerns: imports, `Core.take(...)`
+  registrations, route definitions, and initialization of the single router instance.
+- Use `.kpa` files for UI composition, local component state, and component-scoped CSS.
+- Keep the route outlet inside `app-view.kpa` and keep route rendering consumer-owned.
+- If logic becomes reusable, asynchronous, or branch-heavy, move it into `.ts` modules under `src/`.
+- Keep `public/` for static assets only.
+
+## Naming conventions
+
+- Custom element names must be kebab-case.
+- Root-level application components should use `app-` prefixes when they represent app shells or app-wide structure.
+- Route component filenames should match their registered component tags or route purpose.
+- New files and folders should use descriptive names over abbreviations.
+
+## Dependency rules
+
+- Runtime dependencies must be justified by a concrete need in a spec or ADR.
+- Prefer browser APIs and KoppaJS primitives before adding helper libraries.
+- Keep this repository wired to published npm packages unless there is an explicit ADR stating otherwise.
+- Build tooling changes must update contributor docs and architecture docs in the same change.
+- Quality tooling must stay proportionate to the starter.
+
+## Coding patterns
+
+- Favor simple, local state over premature abstraction.
+- Keep route definitions obvious and close to router initialization.
+- Avoid hidden side effects during import.
+- Keep CSS local to components unless the style truly applies application-wide.
+- Preserve strict TypeScript settings; do not weaken `tsconfig.json` to work around errors.
+- Give interactive controls stable accessible names so smoke tests can target public semantics instead of brittle selectors.
+
+## Forbidden without a spec and ADR
+
+- Replacing the starter's single-router model with a second navigation system
+- Adding global state containers
+- Adding network or persistence layers
+- Introducing SSR, multi-page bootstraps, or multiple root entries
+- Switching dependency sourcing from npm packages to local monorepo links
+- Expanding the starter into a feature-rich demo application
+- Adding heavyweight hooks that run the entire suite on every commit
+
+## Documentation obligations
+
+- Update [ARCHITECTURE.md](./ARCHITECTURE.md) when source layout or runtime flow changes.
+- Update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) when quality gates or tooling change.
+- Update or create a spec in [docs/specs](./docs/specs) for user-visible changes.
+- Add an ADR in [docs/adr](./docs/adr) for durable technical decisions.
+- Update [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) when scripts, hooks, CI checks, or browser-smoke expectations change.

package/template-overlays/router/README.md

@@ -0,0 +1,243 @@
+<a id="readme-top"></a>
+
+<div align="center">
+  <img src="https://public-assets-1b57ca06-687a-4142-a525-0635f7649a5c.s3.eu-central-1.amazonaws.com/koppajs/koppajs-logo-text-900x226.png" width="500" alt="KoppaJS Logo">
+</div>
+
+<br>
+
+<div align="center">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
+</div>
+
+<br>
+
+<div align="center">
+  <h1 align="center">__PROJECT_NAME__</h1>
+  <h3 align="center">KoppaJS router starter project</h3>
+  <p align="center">
+    <i>Scaffolded from the official KoppaJS router starter baseline.</i>
+  </p>
+</div>
+
+<br>
+
+<div align="center">
+  <p align="center">
+    <a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-core">KoppaJS Core</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-router">KoppaJS Router</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-vite-plugin">Vite Plugin</a>
+  </p>
+</div>
+
+<br>
+
+<details>
+<summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#what-is-this">What is this?</a></li>
+    <li><a href="#requirements">Requirements</a></li>
+    <li><a href="#getting-started">Getting Started</a></li>
+    <li><a href="#quality-workflow">Quality Workflow</a></li>
+    <li><a href="#routing-overview">Routing Overview</a></li>
+    <li><a href="#project-structure">Project Structure</a></li>
+    <li><a href="#meta-layer">Meta Layer</a></li>
+    <li><a href="#community--contribution">Community & Contribution</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+---
+
+## What is this?
+
+This project was scaffolded from the official KoppaJS router starter baseline.
+
+It keeps the application intentionally small while demonstrating one extra
+subsystem beyond the minimal starter:
+
+- one HTML shell
+- one TypeScript bootstrap file
+- one root app shell component
+- one router instance with a visible two-page flow
+- one counter component on the home route
+- one explicit catch-all route for unmatched paths
+
+It also carries the same quality and governance baseline as the minimal starter:
+
+- ESLint for source and tooling files
+- Prettier plus `.editorconfig` for supported text formats
+- Vitest for local unit and integration coverage
+- Playwright for a real-browser smoke test
+- Husky plus lint-staged for fast staged-file checks
+- Conventional Commits enforcement via `commitlint`
+- a tag-driven GitHub release baseline with `CHANGELOG.md` and `RELEASE.md`
+
+Use it when you want to start from a small KoppaJS app that already shows how
+route definitions, `data-route` links, and route-based outlet rendering fit
+together.
+
+---
+
+## Requirements
+
+- Node.js 20.19+, 22.13+, or 24+
+- pnpm >= 10
+
+Node 23 is intentionally not treated as supported here because the current
+upstream frontend toolchain excludes it.
+
+---
+
+## Getting Started
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Install the Playwright browser once if you want to run the browser smoke test locally:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+Useful commands:
+
+```bash
+pnpm lint
+pnpm format:check
+pnpm typecheck
+pnpm test:run
+pnpm test:coverage
+pnpm build
+pnpm serve
+pnpm release:check
+```
+
+---
+
+## Quality Workflow
+
+Fast local baseline:
+
+```bash
+pnpm check
+```
+
+Full validation, including Playwright:
+
+```bash
+pnpm validate
+```
+
+Standalone browser smoke test:
+
+```bash
+pnpm test:e2e
+```
+
+---
+
+## Routing Overview
+
+The starter wires `@koppajs/koppajs-router` in `src/main.ts`.
+
+The route table currently contains:
+
+- `/` -> `home-page`
+- `/router` -> `router-page`
+- `*` -> `not-found-page`
+
+The router renders into `#app-outlet`, updates active navigation state for
+links that use `data-route`, and keeps the browser URL aligned with the current
+page.
+
+---
+
+## Project Structure
+
+```text
+__PROJECT_NAME__/
+├── .editorconfig
+├── .github/
+├── .gitignore
+├── .husky/
+├── .npmrc
+├── .prettierignore
+├── CHANGELOG.md
+├── commitlint.config.mjs
+├── AI_CONSTITUTION.md
+├── ARCHITECTURE.md
+├── CONTRIBUTING.md
+├── DECISION_HIERARCHY.md
+├── DEVELOPMENT_RULES.md
+├── RELEASE.md
+├── ROADMAP.md
+├── TESTING_STRATEGY.md
+├── eslint.config.mjs
+├── index.html
+├── package.json
+├── playwright.config.ts
+├── pnpm-lock.yaml
+├── prettier.config.mjs
+├── tsconfig.json
+├── vite.config.mjs
+├── vitest.config.mjs
+├── docs/
+│   ├── adr/
+│   ├── architecture/
+│   ├── meta/
+│   ├── quality/
+│   └── specs/
+├── public/
+│   └── favicon.svg
+├── src/
+│   ├── main.ts
+│   ├── style.css
+│   ├── app-view.kpa
+│   ├── counter-component.kpa
+│   ├── home-page.kpa
+│   ├── router-page.kpa
+│   └── not-found-page.kpa
+└── tests/
+    ├── e2e/
+    ├── integration/
+    └── unit/
+```
+
+---
+
+## Meta Layer
+
+The repository includes an explicit meta layer so architecture, testing, and
+contributor rules evolve together with the codebase.
+
+Start here:
+
+- `DECISION_HIERARCHY.md`
+- `AI_CONSTITUTION.md`
+- `ARCHITECTURE.md`
+- `DEVELOPMENT_RULES.md`
+- `TESTING_STRATEGY.md`
+- `CHANGELOG.md`
+- `RELEASE.md`
+- `docs/quality/quality-gates.md`
+- `docs/adr/`
+- `docs/specs/`
+
+---
+
+## Community & Contribution
+
+Contribution workflow details live in `CONTRIBUTING.md`.
+Update this section with your own repository links once the project has a
+canonical home.
+
+---
+
+## License

package/template-overlays/router/ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap
+
+This roadmap describes intended directions, not guaranteed delivery dates.
+
+## Current priorities
+
+- Keep the router starter focused and production-like.
+- Preserve a clear bootstrap path for new KoppaJS users.
+- Keep the meta layer synchronized with the actual repository.
+
+## Near-term opportunities
+
+- Add route-level examples only when they demonstrate a real starter need.
+- Strengthen route-related tests if the starter gains redirects, params, or nested routes.
+- Keep documentation aligned with the actual router wiring.
+
+## Longer-term expansion triggers
+
+These should happen only with a spec and ADR:
+
+- async data fetching
+- persistence
+- richer route hierarchies
+- shared state beyond local component state
+- CI automation changes
+
+## Meta-layer maintenance
+
+Every release or architecture-changing change should answer:
+
+- Does the architecture document still match the code?
+- Did any new decision deserve an ADR?
+- Did testing expectations change?
+- Did contributor instructions stay accurate?

package/template-overlays/router/TESTING_STRATEGY.md

@@ -0,0 +1,67 @@
+# Testing Strategy
+
+## Current state
+
+This repository carries a small automated testing stack aligned with the router starter's actual risk profile:
+
+- `pnpm test:run` for unit and integration tests in Vitest
+- `pnpm test:coverage` for local coverage reporting
+- `pnpm test:e2e` for a Playwright smoke test against `vite preview`
+- `pnpm check` for the fast repository baseline
+- `pnpm validate` for the full local and CI validation path
+- `pnpm release:check` for tagged release candidates
+- `commitlint` through `.husky/commit-msg` for commit message validation
+
+## Philosophy
+
+- Test the smallest meaningful unit that gives confidence.
+- Prefer extracting logic into `.ts` modules when it becomes complex enough to warrant focused unit tests.
+- Avoid brittle tests that mirror implementation details instead of observable behavior.
+- Reuse the real Vite loading path in automated tests whenever `.kpa` handling is part of the risk surface.
+
+## Test pyramid for this repository
+
+### Unit tests
+
+Use unit tests for isolated logic that can fail independently of the browser runtime.
+
+### Integration or component tests
+
+Use integration tests when bootstrap, component registration, and router startup
+must be verified together but a full browser run would be disproportionate.
+
+Typical triggers:
+
+- bootstrap registration in `src/main.ts`
+- router startup wiring and route table shape
+- build-time behavior that depends on the Vite plugin
+
+### End-to-end tests
+
+Keep Playwright intentionally user-facing and smoke-level.
+
+Typical triggers:
+
+- root UI rendering
+- route navigation between starter pages
+- critical starter interactions such as the counter behavior
+- preview/build regressions that would not be caught by Vitest alone
+
+## Coverage expectations
+
+- There is no blanket repository percentage target right now.
+- New non-trivial logic should come with focused tests.
+- When a subsystem introduces more branching logic, async behavior, or shared state, test automation stops being optional.
+
+## Quality gates by change size
+
+- Documentation-only change: verify links and document consistency.
+- Small style or copy change: run `pnpm check`.
+- Source or config change: run `pnpm check`.
+- UI, bootstrap, or browser-sensitive change: run `pnpm validate`.
+- Version, changelog, or release workflow change: run `pnpm release:check`.
+
+## Maintenance rule
+
+Whenever test tooling, quality gates, or expected confidence levels change,
+update this file and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) in the same change.

package/template-overlays/router/docs/adr/0001-keep-the-starter-minimal.md

@@ -0,0 +1,32 @@
+# ADR 0001: Keep the router starter focused
+
+## Context
+
+This repository starts from the maintained KoppaJS router starter baseline.
+Its audience needs a runnable reference that demonstrates routing without
+turning into a broad showcase application.
+
+## Decision
+
+The router starter remains intentionally small:
+
+- one HTML shell,
+- one TypeScript bootstrap file,
+- one root KoppaJS view,
+- one router instance,
+- two primary routes plus one explicit fallback route,
+- one stateful child component,
+- published npm packages instead of local monorepo `file:` dependencies.
+
+Any expansion beyond that baseline requires a spec and ADR.
+
+## Consequences
+
+- New users get a fast example of routing without a lot of incidental complexity.
+- The repository stays easy to audit and maintain.
+- More advanced route features must be introduced deliberately rather than accumulating ad hoc.
+
+## Alternatives considered
+
+- A feature-rich demo app that showcases many KoppaJS patterns at once
+- A monorepo-linked starter that depends on local sibling packages

package/template-overlays/router/docs/architecture/module-boundaries.md

@@ -0,0 +1,39 @@
+# Module Boundaries
+
+## Repository boundary model
+
+This repository is intentionally shallow. Its boundaries keep the starter easy to inspect.
+
+| Path                        | Responsibility                                                    | Allowed dependencies                                                     | Must not depend on                                  |
+| --------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
+| `index.html`                | Document shell, root element, asset references                    | Static assets, `src/main.ts`, `src/style.css`                            | Feature logic, router setup, extra scripts          |
+| `src/main.ts`               | Application bootstrap, component registration, and router startup | `@koppajs/koppajs-core`, `@koppajs/koppajs-router`, local `.kpa` modules | Page copy, route component visuals, unrelated state |
+| `src/app-view.kpa`          | Shared shell, primary navigation, and route outlet                | Local markup, local CSS                                                  | Route matching, component registration              |
+| `src/home-page.kpa`         | Landing-route content and counter composition                     | Local markup, local CSS, `counter-component`                             | Router setup or global shell orchestration          |
+| `src/router-page.kpa`       | Second-route content                                              | Local markup and local CSS                                               | Bootstrap or route resolution concerns              |
+| `src/not-found-page.kpa`    | Explicit fallback-route content                                   | Local markup and local CSS                                               | Route matching rules or global state                |
+| `src/counter-component.kpa` | Example local state and interaction                               | Local markup, local methods, local CSS                                   | Route orchestration or app-shell concerns           |
+| `src/style.css`             | Global tokens and truly global base rules                         | Standard CSS                                                             | Route-specific or component-specific visual rules   |
+| `tests/integration/`        | Bootstrap and router boundary verification                        | Vitest, local modules, selective mocks                                   | Browser-only smoke assertions                       |
+| `tests/e2e/`                | Real-browser smoke coverage                                       | Playwright, preview server                                               | Implementation-detail assertions                    |
+| `vite.config.mjs`           | Build and dev server integration                                  | Vite and the KoppaJS Vite plugin                                         | Application runtime logic                           |
+
+## Boundary rules
+
+- Registration and route configuration happen in `src/main.ts`.
+- `app-view.kpa` may compose navigation and the outlet but must not become a second router.
+- Route components own their own copy and layout.
+- Shared logic belongs in dedicated `.ts` modules once reuse or complexity justifies it.
+- Vitest owns helper-level and bootstrap-level confidence; Playwright owns browser smoke confidence.
+
+## Escalation rules
+
+Before crossing existing boundaries, add a spec and ADR if the change introduces:
+
+- nested or parameterized routing beyond the current baseline,
+- shared state,
+- async workflows,
+- persistence,
+- more than one root entrypoint,
+- npm publishing or deployment automation,
+- new top-level source folders.