create-koppajs 1.2.1 → 1.2.3

package/template-overlays/router/src/home-page.kpa

@@ -1,17 +1,14 @@
 [template]
-  <section class="page-card">
+  <section class="page">
     <div class="page-copy">
-      <p class="section-label">Home route</p>
-      <h2 class="page-title">A small starter, now with real navigation</h2>
-      <p class="page-text">
-        The home page keeps the original interactive counter so the starter still
-        shows local state, while the navigation above now switches routes through
-        the published KoppaJS router.
+      <p class="eyebrow">Home route</p>
+      <h1>KoppaJS router starter</h1>
+      <p>
+        This page is rendered for <code>/</code>. The counter stays here so the
+        starter shows component state and route rendering in the same small app.
       </p>
 
-      <div class="page-actions">
-        <a data-route="/router" href="/router" class="page-link">Open the second page</a>
-      </div>
+      <a data-route="/router" href="/router" class="page-link">Open router page</a>
     </div>
 
     <counter-component></counter-component>
@@ -19,82 +16,48 @@
 [/template]
 
 [css]
-  .page-card {
+  .page {
     display: grid;
-    grid-template-columns: minmax(0, 1.1fr) auto;
-    gap: 1.5rem;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 2rem;
     align-items: start;
-    padding: 1.5rem;
-    border: 1px solid var(--border);
-    border-radius: 1.75rem;
-    background: var(--surface);
-    box-shadow: var(--shadow);
-    backdrop-filter: blur(18px);
   }
 
   .page-copy {
-    display: flex;
-    flex-direction: column;
+    display: grid;
     gap: 1rem;
   }
 
-  .section-label {
+  .eyebrow {
     color: var(--accent);
     font-size: 0.8rem;
-    letter-spacing: 0.28em;
+    letter-spacing: 0.2em;
     text-transform: uppercase;
   }
 
-  .page-title {
-    font-size: clamp(1.7rem, 3vw, 2.7rem);
+  h1 {
+    font-size: clamp(2rem, 4vw, 3rem);
     line-height: 1.1;
   }
 
-  .page-text {
+  p {
+    max-width: 58ch;
     color: var(--muted);
     line-height: 1.7;
-    max-width: 54ch;
   }
 
-  .page-actions {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.8rem;
+  code {
+    color: var(--accent);
   }
 
   .page-link {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 2.8rem;
-    padding: 0 1.25rem;
-    border-radius: 999px;
-    background: rgba(100, 220, 232, 0.1);
-    border: 1px solid rgba(100, 220, 232, 0.3);
-    color: var(--accent-strong);
-    text-decoration: none;
-    transition: background 0.25s ease, transform 0.15s ease;
-  }
-
-  .page-link:hover {
-    background: rgba(100, 220, 232, 0.18);
-  }
-
-  .page-link:active {
-    transform: translateY(1px);
+    width: fit-content;
+    color: var(--accent);
   }
 
-  @media (max-width: 840px) {
-    .page-card {
+  @media (max-width: 760px) {
+    .page {
       grid-template-columns: 1fr;
-      justify-items: start;
-    }
-  }
-
-  @media (max-width: 640px) {
-    .page-card {
-      padding: 1.15rem;
-      border-radius: 1.25rem;
     }
   }
 [/css]

package/template-overlays/router/src/main.ts

@@ -16,23 +16,14 @@ const ROUTE_LINK_SELECTOR = "a[data-route]";
 const routes = [
   {
     path: "/",
-    name: "home",
-    title: "Home",
-    description: "Landing page for the KoppaJS router starter.",
     componentTag: "home-page",
   },
   {
     path: "/router",
-    name: "router",
-    title: "Router",
-    description: "Second page showing how the KoppaJS router starter works.",
     componentTag: "router-page",
   },
   {
     path: "*",
-    name: "not-found",
-    title: "Not found",
-    description: "Fallback page for unmatched routes in the router starter.",
     componentTag: "not-found-page",
   },
 ] satisfies readonly RouteDefinition[];

package/template-overlays/router/src/not-found-page.kpa

@@ -1,69 +1,37 @@
 [template]
-  <section class="page-card page-card--missing">
-    <p class="section-label">404</p>
-    <h2 class="page-title">Page not found</h2>
-    <p class="page-text">
-      The router starter includes an explicit catch-all route, so unmatched URLs
-      still render a predictable fallback page instead of failing silently.
-    </p>
-
-    <div class="page-actions">
-      <a data-route="/" href="/" class="page-link">Return home</a>
-    </div>
+  <section class="page">
+    <p class="eyebrow">404</p>
+    <h1>Page not found</h1>
+    <p>The router fallback route rendered this page for an unknown URL.</p>
+    <a data-route="/" href="/" class="page-link">Return home</a>
   </section>
 [/template]
 
 [css]
-  .page-card {
-    display: flex;
-    flex-direction: column;
+  .page {
+    display: grid;
     gap: 1rem;
-    padding: 1.5rem;
-    border: 1px solid rgba(248, 113, 113, 0.24);
-    border-radius: 1.75rem;
-    background: linear-gradient(180deg, rgba(61, 12, 22, 0.5), rgba(11, 22, 40, 0.88));
-    box-shadow: var(--shadow);
   }
 
-  .section-label {
-    color: #fda4af;
+  .eyebrow {
+    color: var(--accent);
     font-size: 0.8rem;
-    letter-spacing: 0.28em;
+    letter-spacing: 0.2em;
     text-transform: uppercase;
   }
 
-  .page-title {
-    font-size: clamp(1.7rem, 3vw, 2.5rem);
+  h1 {
+    font-size: clamp(2rem, 4vw, 3rem);
     line-height: 1.1;
   }
 
-  .page-text {
-    color: #fecdd3;
+  p {
+    color: var(--muted);
     line-height: 1.7;
-    max-width: 58ch;
-  }
-
-  .page-actions {
-    display: flex;
   }
 
   .page-link {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 2.8rem;
-    padding: 0 1.25rem;
-    border-radius: 999px;
-    background: rgba(253, 164, 175, 0.12);
-    border: 1px solid rgba(253, 164, 175, 0.4);
-    color: #fff1f2;
-    text-decoration: none;
-  }
-
-  @media (max-width: 640px) {
-    .page-card {
-      padding: 1.15rem;
-      border-radius: 1.25rem;
-    }
+    width: fit-content;
+    color: var(--accent);
   }
 [/css]

package/template-overlays/router/src/router-page.kpa

@@ -1,102 +1,67 @@
 [template]
-  <section class="page-card">
-    <div class="page-copy">
-      <p class="section-label">Second page</p>
-      <h2 class="page-title">Router is active</h2>
-      <p class="page-text">
-        This view is rendered into <code>#app-outlet</code> by
-        <code>KoppajsRouter</code>. The active navigation state and the browser
-        URL are both managed by the router runtime.
-      </p>
+  <section class="page">
+    <p class="eyebrow">Router route</p>
+    <h1>Routing is active</h1>
+    <p>
+      This page is rendered for <code>/router</code>. Links with
+      <code>data-route</code> are handled by <code>KoppajsRouter</code>, and a
+      catch-all route handles unknown paths.
+    </p>
 
-      <ul class="feature-list">
-        <li>Routes are defined in <code>src/main.ts</code>.</li>
-        <li>Links opt into delegated navigation through <code>data-route</code>.</li>
-        <li>A catch-all route is already wired for unmatched paths.</li>
-      </ul>
+    <ul class="route-list" aria-label="Configured routes">
+      <li><code>/</code> renders <code>home-page</code></li>
+      <li><code>/router</code> renders <code>router-page</code></li>
+      <li><code>*</code> renders <code>not-found-page</code></li>
+    </ul>
 
-      <div class="page-actions">
-        <a data-route="/" href="/" class="page-link">Back to home</a>
-      </div>
-    </div>
+    <a data-route="/" href="/" class="page-link">Back home</a>
   </section>
 [/template]
 
 [css]
-  .page-card {
-    padding: 1.5rem;
-    border: 1px solid var(--border);
-    border-radius: 1.75rem;
-    background: var(--surface-strong);
-    box-shadow: var(--shadow);
-    backdrop-filter: blur(18px);
-  }
-
-  .page-copy {
-    display: flex;
-    flex-direction: column;
+  .page {
+    display: grid;
     gap: 1rem;
   }
 
-  .section-label {
+  .eyebrow {
     color: var(--accent);
     font-size: 0.8rem;
-    letter-spacing: 0.28em;
+    letter-spacing: 0.2em;
     text-transform: uppercase;
   }
 
-  .page-title {
-    font-size: clamp(1.7rem, 3vw, 2.5rem);
+  h1 {
+    font-size: clamp(2rem, 4vw, 3rem);
     line-height: 1.1;
   }
 
-  .page-text {
+  p {
+    max-width: 62ch;
     color: var(--muted);
     line-height: 1.7;
-    max-width: 58ch;
   }
 
   code {
-    color: var(--accent-strong);
+    color: var(--accent);
   }
 
-  .feature-list {
-    list-style: none;
+  .route-list {
     display: grid;
-    gap: 0.8rem;
-    color: var(--text);
-  }
-
-  .feature-list li {
-    padding: 0.95rem 1rem;
-    border-radius: 1rem;
-    border: 1px solid rgba(100, 220, 232, 0.18);
-    background: rgba(100, 220, 232, 0.06);
+    gap: 0.6rem;
+    list-style: none;
+    max-width: 34rem;
   }
 
-  .page-actions {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.8rem;
+  .route-list li {
+    padding: 0.8rem 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.75rem;
+    background: var(--surface);
   }
 
   .page-link {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 2.8rem;
-    padding: 0 1.25rem;
-    border-radius: 999px;
-    background: rgba(100, 220, 232, 0.1);
-    border: 1px solid rgba(100, 220, 232, 0.3);
-    color: var(--accent-strong);
-    text-decoration: none;
-  }
-
-  @media (max-width: 640px) {
-    .page-card {
-      padding: 1.15rem;
-      border-radius: 1.25rem;
-    }
+    width: fit-content;
+    color: var(--accent);
   }
 [/css]

package/template-overlays/router/src/style.css

@@ -1,16 +1,12 @@
 :root {
   color-scheme: dark;
-  --app-bg: #08111f;
-  --app-bg-accent: #102742;
-  --surface: rgba(9, 16, 31, 0.78);
-  --surface-strong: rgba(11, 22, 40, 0.92);
-  --border: rgba(148, 163, 184, 0.2);
+  --app-bg: #0f1117;
+  --surface: #171b29;
+  --border: #2a3042;
   --text: #edf6ff;
   --muted: #a7bfd7;
   --accent: #64dce8;
-  --accent-strong: #97f3fb;
-  --shadow: 0 24px 80px rgba(0, 0, 0, 0.32);
-  font-family: "Space Grotesk", "Avenir Next", "Segoe UI", sans-serif;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 }
 
 * {
@@ -19,29 +15,9 @@
   padding: 0;
 }
 
-html {
-  min-height: 100%;
-  background:
-    radial-gradient(
-      circle at top left,
-      rgba(100, 220, 232, 0.16),
-      transparent 30%
-    ),
-    radial-gradient(
-      circle at bottom right,
-      rgba(16, 39, 66, 0.55),
-      transparent 32%
-    ),
-    linear-gradient(
-      160deg,
-      var(--app-bg) 0%,
-      #060c18 45%,
-      var(--app-bg-accent) 100%
-    );
-}
-
 body {
   min-height: 100vh;
+  background: var(--app-bg);
   color: var(--text);
 }
 

package/template/AI_CONSTITUTION.md

@@ -1,50 +0,0 @@
-# AI Constitution
-
-## Purpose
-
-This repository is a KoppaJS starter scaffolded from the official minimal Vite
-and TypeScript baseline. Its job is to stay small, understandable, runnable,
-and trustworthy.
-
-## Core principles
-
-- Optimize for clarity over feature breadth.
-- Keep the bootstrap path obvious: one HTML shell, one TypeScript entrypoint, one root view.
-- Prefer published npm packages over local `file:` links in this repository.
-- Keep the starter close to real production usage, but do not turn it into a framework showcase.
-- Treat the meta layer as part of the product. If architecture or workflow changes, the documentation must change in the same update.
-
-## Architectural philosophy
-
-- `index.html` is the static document shell only.
-- `src/main.ts` is the only bootstrap module and the only place that registers root-level components with `Core.take(...)`.
-- `.kpa` files are the primary unit for simple UI composition, local state, and component-scoped styling.
-- When logic becomes reusable, branch-heavy, or worth unit testing, extract it from `.kpa` blocks into `.ts` modules.
-- Global CSS stays minimal. Component visuals belong inside component-local CSS blocks unless they are true application-wide primitives.
-
-## Collaboration rules for humans and AI
-
-1. Read [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md), [ARCHITECTURE.md](./ARCHITECTURE.md), [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md), [TESTING_STRATEGY.md](./TESTING_STRATEGY.md), and any relevant spec or ADR before editing code.
-2. Follow `spec -> quality plan -> implementation -> documentation` for any non-trivial change.
-3. Do not silently change public component tags, bootstrap flow, dependency sourcing, or the starter's setup instructions.
-4. Prefer existing repository patterns over inventing new structure.
-5. If a change affects architecture, module boundaries, build tooling, testing, or contributor workflow, update the meta layer in the same change.
-6. Record durable architectural decisions in `docs/adr/`.
-7. If code and documentation disagree, resolve the mismatch before merging further changes.
-
-## Change triggers
-
-- New subsystem or folder: update [ARCHITECTURE.md](./ARCHITECTURE.md) and [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
-- New enduring technical decision: add or update an ADR in [docs/adr](./docs/adr).
-- New development convention: update [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md).
-- New quality gate or test level: update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md).
-- New user-visible capability: create or update a spec in [docs/specs](./docs/specs).
-
-## Definition of done
-
-A change is not complete until:
-
-- the code or docs are aligned with the actual repository state,
-- applicable specs and ADRs are updated,
-- required quality checks have run,
-- contributor-facing guidance still matches the project.

package/template/ARCHITECTURE.md

@@ -1,86 +0,0 @@
-# Architecture
-
-This repository is a minimal KoppaJS application starter. It intentionally demonstrates a small end-to-end path: HTML shell, TypeScript bootstrap, a root KoppaJS view, and a single interactive child component. The repository also carries a small quality and release automation layer so the starter stays runnable, trustworthy, and maintainable as it evolves.
-
-## 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` imports `@koppajs/koppajs-core`, registers local components with `Core.take(...)`, and invokes `Core()` exactly once to bootstrap the app.
-- `src/app-view.kpa` is the root UI shell. It arranges the page and composes the interactive example component.
-- `src/counter-component.kpa` is the example stateful leaf component. It owns its own `count` state and button event handlers.
-- `src/style.css` contains the global reset only.
-- `public/` contains static assets referenced by the HTML shell or components.
-- `vite.config.mjs` wires the KoppaJS Vite plugin into the build and applies a small repo-local compatibility transform so `.kpa` files are emitted as valid ES modules.
-- `vitest.config.mjs` reuses the Vite config so unit and integration tests exercise the same `.kpa` loading path as the application.
-- `playwright.config.ts` runs a Chromium smoke test against `vite preview`, which keeps the minimal UI starter covered by one real browser path.
-- `CHANGELOG.md` records official tagged milestones for the repository.
-- `RELEASE.md` documents the maintainer release path across `develop`, `release/*`, and `main`.
-- `commitlint.config.mjs` defines the repository's commit message convention.
-- `.github/workflows/release.yml` reruns validation for `vX.Y.Z` tags, checks version alignment, and creates GitHub Releases.
-- `tests/unit/` covers isolated logic such as the `.kpa` module export normalization helper.
-- `tests/integration/` covers application bootstrap wiring without requiring a full browser run.
-- `tests/e2e/` covers the observable starter flow in a real browser.
-- `tsconfig.json` enforces strict TypeScript rules for source, tests, and TypeScript config files. `.kpa` compilation is still handled by the KoppaJS Vite plugin.
-
-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` and `counter-component` with KoppaJS Core, then calls `Core()`.
-4. KoppaJS instantiates `<app-view>`.
-5. [`src/app-view.kpa`](./src/app-view.kpa) renders the starter shell and nests `<counter-component>`.
-6. [`src/counter-component.kpa`](./src/counter-component.kpa) handles button clicks, mutates local state, and re-renders the displayed value.
-
-## Quality automation layer
-
-- `eslint.config.mjs` lint-checks TypeScript source plus the TypeScript- and JavaScript-based tooling files.
-- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent without introducing formatter-specific rules into ESLint.
-- `.npmrc` enforces the declared engine floor during installs.
-- `.husky/pre-commit` runs `lint-staged` so staged files get a fast local quality pass before commit.
-- `.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 for matching versions.
-- Stylelint is intentionally absent for now because the important styles live inside `.kpa` blocks and the repository does not yet have a low-friction, first-class way to lint those embedded blocks without giving a misleading sense of coverage.
-
-## Module responsibilities
-
-| Module                          | Responsibility                                                                             | Must not do                                                           |
-| ------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
-| `index.html`                    | Declare root tag and static assets                                                         | Hold business logic or feature wiring                                 |
-| `CHANGELOG.md`                  | Record official tagged release notes                                                       | Become a scratchpad for speculative work or duplicate repository docs |
-| `RELEASE.md`                    | Define the maintainer release procedure                                                    | Drift away from actual branch, tag, or workflow behavior              |
-| `commitlint.config.mjs`         | Define commit message validation rules                                                     | Expand into unrelated repository lint policy                          |
-| `src/main.ts`                   | Bootstrap and component registration                                                       | Accumulate feature logic, state, or DOM manipulation                  |
-| `src/app-view.kpa`              | Root layout and composition                                                                | Own unrelated business workflows or register components               |
-| `src/counter-component.kpa`     | Local interactive example state                                                            | Reach into global DOM or mutate app shell concerns                    |
-| `src/style.css`                 | Global reset/base rules                                                                    | Contain feature-specific visuals that belong to components            |
-| `public/`                       | Static assets                                                                              | Store generated build output or source code                           |
-| `tests/unit/`                   | Isolated tests for helper or tooling logic                                                 | Production runtime side effects or browser-only expectations          |
-| `tests/integration/`            | Wiring tests across bootstrap boundaries                                                   | Full browser assertions already covered by Playwright                 |
-| `tests/e2e/`                    | Real browser smoke coverage of the starter UI                                              | Deep implementation-detail assertions or brittle CSS-driven flows     |
-| `vite.config.mjs`               | Build and dev server integration, including the `.kpa` module export compatibility wrapper | Application runtime logic                                             |
-| `vitest.config.mjs`             | Unit and integration test runner configuration                                             | Runtime feature code                                                  |
-| `playwright.config.ts`          | Browser smoke-test orchestration against preview output                                    | Application runtime logic                                             |
-| `.github/workflows/release.yml` | Tagged release validation and GitHub Release creation                                      | Publish to npm while the repository remains private                   |
-
-## Invariants
-
-- There is exactly one application bootstrap path.
-- The root tag in `index.html` must match a component registered in `src/main.ts`.
-- `Core()` is called once from `src/main.ts`.
-- Official releases require matching versions across `package.json`, `CHANGELOG.md`, and `vX.Y.Z` tags.
-- Maintainer commits are expected to follow Conventional Commits.
-- No routing, persistence, network calls, or global client-side state are part of the baseline starter.
-- Stateful behavior remains local unless a documented new subsystem justifies centralization.
-- `pnpm check` remains fast enough for routine local use.
-- Playwright coverage stays focused on critical smoke coverage unless the UI grows into a broader workflow surface.
-- The repository remains `private` until an explicit decision changes the release target.
-
-## Extension guidance
-
-- Add new components under `src/` and compose them from `app-view.kpa` or other components.
-- Extract shared logic into `.ts` modules when it becomes reusable or deserves focused testing.
-- Add a spec before introducing new user-visible behavior.
-- Add an ADR before introducing architecture-changing capabilities such as routing, data fetching, persistence, state containers, SSR, or a new testing stack.

package/template/CHANGELOG.md

@@ -1,34 +0,0 @@
-# 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.
-
----
-
-## [Unreleased]
-
-This section is intentionally empty.
-
-Changes will only appear here when they:
-
-- alter the project's observable behavior,
-- change contributor or maintainer workflow,
-- or modify documented repository guarantees.
-
----
-
-## [1.0.0] — Initial Scaffold Baseline
-
-**2026-03-17**
-
-Initial scaffold created from the current official KoppaJS starter baseline.
-
-### Included
-
-- a minimal KoppaJS app shell with `app-view` and `counter-component`
-- bootstrap through `Core.take(...)` and `Core()`
-- ESLint, Prettier, Vitest, Playwright, Husky, and GitHub Actions CI
-- explicit architecture, ADR, spec, testing, and contributor documentation
-- a tag-driven GitHub release workflow for repository snapshots