create-koppajs 1.1.0 → 1.2.0

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.

package/template-overlays/router/docs/meta/maintenance.md

@@ -0,0 +1,38 @@
+# Meta-Layer Maintenance
+
+The meta layer is a living system. Any change that alters the real system must update the corresponding governance document in the same change.
+
+## Update matrix
+
+| Change                                     | Required updates                                                                               |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| New feature or behavior                    | Add or update a spec in `docs/specs/`; update `README.md` if setup or visible behavior changes |
+| New enduring technical decision            | Add or update an ADR in `docs/adr/`                                                            |
+| New module, folder, or data flow           | Update `ARCHITECTURE.md` and `docs/architecture/module-boundaries.md`                          |
+| New coding pattern or dependency rule      | Update `DEVELOPMENT_RULES.md`                                                                  |
+| New test tooling or quality gate           | Update `TESTING_STRATEGY.md` and `docs/quality/quality-gates.md`                               |
+| New hook, CI step, or contributor workflow | Update `CONTRIBUTING.md` and `.github/instructions/ai-workflow.md`                             |
+| Version, changelog, or release workflow    | Update `CHANGELOG.md`, `RELEASE.md`, `package.json`, and affected GitHub workflow files        |
+
+## Review triggers
+
+Perform a meta-layer review when:
+
+- a pull request changes the repo structure,
+- a new dependency is added,
+- a public component tag changes,
+- a build or test command changes,
+- a hook or CI workflow changes,
+- the routing model or route surface changes,
+- a README section no longer matches the actual code.
+
+## Periodic review checklist
+
+- Does [ARCHITECTURE.md](../../ARCHITECTURE.md) still match the runtime flow?
+- Do current specs cover the user-visible behaviors in the repo?
+- Do ADRs still represent active decisions?
+- Do contributor instructions still match the actual toolchain?
+- Did a recent change deserve a new quality gate?
+- Do `CHANGELOG.md`, `RELEASE.md`, and the release workflow still match actual branch and tag practice?
+
+If any answer is "no", update the meta layer before considering the repository aligned.

package/template-overlays/router/docs/specs/README.md

@@ -0,0 +1,19 @@
+# Specifications
+
+Specs define expected behavior before or alongside implementation. They are the highest-precedence project documents.
+
+## When a spec is required
+
+Create or update a spec when a change:
+
+- introduces or changes user-visible behavior,
+- adds a subsystem,
+- changes public setup or bootstrap behavior,
+- changes a feature in a way that needs explicit acceptance criteria.
+
+## Current specs
+
+- [`app-bootstrap.md`](./app-bootstrap.md)
+- [`counter-component.md`](./counter-component.md)
+- [`router-navigation.md`](./router-navigation.md)
+- [`quality-workflow.md`](./quality-workflow.md)

package/template-overlays/router/docs/specs/app-bootstrap.md

@@ -0,0 +1,42 @@
+# Spec: App bootstrap
+
+## Status
+
+Approved
+
+## Purpose
+
+Provide a predictable startup path for a KoppaJS application that includes the official router runtime.
+
+## Behavior
+
+- The application starts from `index.html`.
+- The HTML shell loads one global stylesheet and one module entrypoint.
+- The document declares exactly one root custom element: `<app-view>`.
+- `src/main.ts` registers `app-view`, `home-page`, `router-page`, `not-found-page`, and `counter-component` with KoppaJS Core.
+- `src/main.ts` invokes `Core()` once and starts one `KoppajsRouter` instance.
+
+## Inputs
+
+- Browser loading `index.html`
+- Static asset and source file paths resolved by Vite
+
+## Outputs
+
+- A rendered `<app-view>` application shell
+- A rendered route component inside `#app-outlet`
+- A registered `<counter-component>` available to the home route
+
+## Constraints
+
+- There must be a single bootstrap entrypoint.
+- The root tag in `index.html` must stay aligned with the component registered in `src/main.ts`.
+- `Core()` must remain the only KoppaJS bootstrap call.
+- Router initialization must happen after the route outlet exists.
+- No extra runtime dependencies are required beyond the declared npm packages.
+
+## Acceptance criteria
+
+- Opening the app through Vite renders the root view without manual DOM scripting.
+- `src/main.ts` remains the only location that calls `Core()`.
+- The route outlet is initialized by the router and can render the home route immediately after bootstrap.

package/template-overlays/router/docs/specs/router-navigation.md

@@ -0,0 +1,41 @@
+# Spec: Router navigation
+
+## Status
+
+Approved
+
+## Purpose
+
+Define the starter's router baseline so the generated project demonstrates a small but real navigation flow.
+
+## Behavior
+
+- The starter initializes one `KoppajsRouter` instance from `src/main.ts`.
+- The router renders matched route components into `#app-outlet`.
+- Primary navigation links use `data-route` and participate in active-link state updates.
+- The starter includes a home route, a second content route, and an explicit `*` fallback route.
+
+## Inputs
+
+- Route definitions declared in `src/main.ts`
+- Browser URL and History API state
+- User clicks on matching `data-route` links
+
+## Outputs
+
+- URL changes that stay aligned with the rendered route component
+- Active navigation state on the current route link
+- A predictable not-found page for unmatched paths
+
+## Constraints
+
+- The route table must stay small and inspectable.
+- The fallback route must be explicit rather than implicit.
+- Route content stays in consumer-owned `.kpa` files, not inside the router package.
+
+## Acceptance criteria
+
+- Visiting `/` renders the home route.
+- Visiting `/router` renders the second route.
+- Visiting an unmatched path renders the fallback route.
+- The active navigation link exposes `aria-current="page"` for the current route.

package/template-overlays/router/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>KoppaJS Router Starter</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <app-view></app-view>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>