create-koppajs 1.0.1 → 1.1.0

package/template/docs/adr/0005-adopt-a-tag-driven-release-baseline.md

@@ -0,0 +1,45 @@
+# ADR 0005: Adopt a tag-driven release baseline
+
+## Context
+
+The repository had gained a real quality baseline, governance documents, and a
+`develop`/`main` branch model, but it still lacked an explicit release contract.
+That left version bumps, changelog updates, and GitHub tagging behavior too
+implicit for a maintained official starter.
+
+`koppajs-core` already uses a documented tag-driven release path with guarded
+automation. This starter benefits from the same clarity, but its release target
+is different because the repository currently stays `private` and is not
+published to npm.
+
+## Decision
+
+Adopt a manual, tag-driven release baseline for this repository:
+
+- maintain `CHANGELOG.md` for official tagged milestones,
+- document the maintainer procedure in `RELEASE.md`,
+- create a GitHub Actions release workflow that runs on `vX.Y.Z` tags,
+- rerun full repository validation during the release workflow,
+- fail the workflow when the pushed tag does not match `package.json`,
+- create GitHub Releases only while the repository remains `private`.
+
+Release content is prepared on `develop`, moved through `release/*`, merged into
+`main`, tagged on `main`, and merged back into `develop` after a successful
+release.
+
+## Consequences
+
+- The repository now has an explicit versioning and release contract.
+- Maintainers must update `package.json`, `CHANGELOG.md`, and `RELEASE.md` in
+  sync when release practice changes.
+- Tagged releases are guarded against accidental version mismatches.
+- The release workflow improves traceability without forcing npm publishing.
+- If this repository later becomes publishable, a new ADR must extend or
+  replace this baseline rather than silently changing the release target.
+
+## Alternatives considered
+
+- Keeping releases informal and undocumented
+- Adding automated versioning via Changesets or semantic-release
+- Copying the npm publish path from `koppajs-core` even though this repository
+  is currently `private`

package/template/docs/adr/0006-adopt-commit-message-conventions.md

@@ -0,0 +1,39 @@
+# ADR 0006: Adopt commit message conventions
+
+## Context
+
+The repository now has staged-file checks, CI validation, and a documented
+release process, but commit history still had no enforced structure.
+
+That makes release review, changelog preparation, and future maintenance harder
+than necessary, especially for an official starter that should model a clear
+workflow for contributors.
+
+`koppajs-core` already enforces conventional commit messages with `commitlint`.
+The same baseline is appropriate here because it adds little overhead while
+improving traceability.
+
+## Decision
+
+Adopt Conventional Commits enforcement through `commitlint`:
+
+- add `@commitlint/cli` and `@commitlint/config-conventional`,
+- validate commit messages in `.husky/commit-msg`,
+- keep the rule set intentionally small,
+- enforce a maximum header length of 72 characters,
+- allow the existing fast `pre-commit` hook to stay focused on staged files.
+
+## Consequences
+
+- Contributors now need to use structured commit headers such as
+  `feat: add release workflow` or `docs: update quality workflow`.
+- Invalid commit messages are rejected before the commit is created.
+- The repository gains a cleaner history for release review and maintenance.
+- If the project later needs custom commit types or scopes, the change should go
+  through `commitlint.config.mjs` and matching documentation updates.
+
+## Alternatives considered
+
+- Keeping commit messages informal
+- Enforcing commit conventions only socially without a hook
+- Adding heavier release automation before stabilizing the commit baseline

package/template/docs/adr/README.md

@@ -0,0 +1,37 @@
+# Architecture Decision Records
+
+This directory stores durable architectural and workflow decisions.
+
+## When to write an ADR
+
+Write an ADR when a change:
+
+- changes repository structure,
+- introduces or removes a subsystem,
+- changes dependency sourcing or build tooling,
+- changes public starter behavior in a lasting way,
+- adds a new rule that future contributors must follow.
+
+## Format
+
+Use [`TEMPLATE.md`](./TEMPLATE.md). Every ADR must contain:
+
+- Context
+- Decision
+- Consequences
+- Alternatives considered
+
+## Naming
+
+- Prefix files with a four-digit sequence number.
+- Use a short kebab-case slug.
+- Never rewrite history silently; supersede older ADRs with new ones when decisions change.
+
+## Current ADRs
+
+- [`0001-keep-the-starter-minimal.md`](./0001-keep-the-starter-minimal.md)
+- [`0002-adopt-a-living-meta-layer.md`](./0002-adopt-a-living-meta-layer.md)
+- [`0003-normalize-kpa-plugin-output.md`](./0003-normalize-kpa-plugin-output.md)
+- [`0004-adopt-an-automated-quality-baseline.md`](./0004-adopt-an-automated-quality-baseline.md)
+- [`0005-adopt-a-tag-driven-release-baseline.md`](./0005-adopt-a-tag-driven-release-baseline.md)
+- [`0006-adopt-commit-message-conventions.md`](./0006-adopt-commit-message-conventions.md)

package/template/docs/adr/TEMPLATE.md

@@ -0,0 +1,18 @@
+# ADR XXXX: Title
+
+## Context
+
+Describe the situation, constraints, and forces that make a decision necessary.
+
+## Decision
+
+Describe the chosen approach in direct, testable language.
+
+## Consequences
+
+Explain the expected benefits, tradeoffs, and follow-up obligations.
+
+## Alternatives considered
+
+- Alternative 1
+- Alternative 2

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

@@ -0,0 +1,48 @@
+# Module Boundaries
+
+## Repository boundary model
+
+This repository is intentionally shallow. Its boundaries are designed to keep the starter easy to understand.
+
+| 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, extra scripts, framework-specific behavior         |
+| `CHANGELOG.md`                  | Tagged release history                                                                     | Release notes, versioned milestones                | Unreleased planning notes or unrelated contributor guidance       |
+| `RELEASE.md`                    | Maintainer release procedure                                                               | `package.json`, `CHANGELOG.md`, GitHub workflows   | Runtime code or undocumented branch conventions                   |
+| `commitlint.config.mjs`         | Commit message rules                                                                       | Conventional commit policy                         | Source-code linting or release branching rules                    |
+| `src/main.ts`                   | Application bootstrap and component registration                                           | `@koppajs/koppajs-core`, local `.kpa` modules      | UI business logic, ad hoc DOM manipulation, network code          |
+| `src/app-view.kpa`              | Root page layout and composition                                                           | Local markup, local CSS, child components          | Global bootstrap concerns, unrelated feature orchestration        |
+| `src/counter-component.kpa`     | Example local state and interaction                                                        | Local markup, local methods, local CSS             | Shared infrastructure, global state, direct root DOM coordination |
+| `src/style.css`                 | Global reset and truly global base rules                                                   | Standard CSS                                       | Component-specific visual rules                                   |
+| `public/`                       | Static assets served as-is                                                                 | Static files only                                  | Source code or generated artifacts                                |
+| `tests/unit/`                   | Isolated tests for helper and tooling logic                                                | Vitest, local modules                              | Full browser expectations or long integration chains              |
+| `tests/integration/`            | Bootstrap and boundary-level integration tests                                             | 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, including the `.kpa` module export compatibility wrapper | Vite and the KoppaJS Vite plugin                   | Application runtime logic                                         |
+| `vitest.config.mjs`             | Vitest orchestration merged with the Vite config                                           | Vitest and Vite config                             | Application runtime logic                                         |
+| `playwright.config.ts`          | Playwright orchestration against preview output                                            | Playwright and preview server script               | Application runtime logic                                         |
+| `.github/workflows/release.yml` | Tag-triggered validation and GitHub Release creation                                       | GitHub Actions, `package.json`, validation scripts | npm publishing while `package.json` is `private`                  |
+| `tsconfig.json`                 | TypeScript compiler behavior for source, tests, and TS config files                        | TypeScript compiler options                        | Application runtime logic                                         |
+
+## Boundary rules
+
+- Registration happens in `src/main.ts`, not inside component modules.
+- `app-view.kpa` may compose child components but should not become a global state hub by accident.
+- Component-local behavior stays inside the component until reuse or complexity makes extraction worthwhile.
+- Shared logic, once introduced, belongs in dedicated `.ts` modules with tests when justified.
+- Vitest owns helper-level and bootstrap-level confidence; Playwright owns browser smoke confidence.
+- Pre-commit checks stay limited to staged-file hygiene. Heavy validation belongs to `pnpm validate` and CI.
+- Commit-message validation lives in `.husky/commit-msg` and `commitlint.config.mjs`, not in ad hoc contributor lore.
+- Release metadata stays aligned across `package.json`, `CHANGELOG.md`, `RELEASE.md`, and `.github/workflows/release.yml`.
+
+## Escalation rules
+
+Before crossing existing boundaries, add a spec and ADR if the change introduces:
+
+- routing,
+- shared state,
+- async workflows,
+- persistence,
+- more than one root entrypoint,
+- npm publishing or deployment automation,
+- new top-level source folders.

package/template/docs/meta/maintenance.md

@@ -0,0 +1,40 @@
+# 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,
+- a subsystem such as routing or data fetching is introduced,
+- 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?
+- Do commit message examples and hook behavior still match `commitlint.config.mjs`?
+- Is any omitted tooling, such as Stylelint, still intentionally omitted for good reason?
+
+If any answer is "no", update the meta layer before considering the repository aligned.

package/template/docs/quality/quality-gates.md

@@ -0,0 +1,39 @@
+# Quality Gates
+
+## Baseline gates
+
+For the current repository scope, the baseline gates are:
+
+- staged files: `lint-staged` via `.husky/pre-commit`
+- commit messages: `commitlint` via `.husky/commit-msg`
+- fast local repository check: `pnpm check`
+- full repository validation: `pnpm validate`
+- release candidate verification: `pnpm release:check`
+- `pnpm typecheck`
+- `pnpm build`
+- `pnpm test:run`
+- `pnpm test:e2e` for UI, bootstrap, or preview-sensitive changes
+- tagged release automation: `.github/workflows/release.yml` reruns validation and checks tag/version alignment
+
+## Gate escalation rules
+
+Raise the quality bar when the repository grows:
+
+- New extracted logic modules: add unit tests.
+- Multi-component behavior: add integration or component tests.
+- Routing, async workflows, persistence, or deployment-sensitive behavior: expand end-to-end coverage beyond the current smoke scope.
+- If component-local `.kpa` styling grows more complex and a credible linting path appears, revisit the current decision to omit Stylelint.
+
+## Review checklist
+
+- Do setup instructions still work from a clean checkout?
+- Does the documented architecture still match the code layout?
+- Do specs still match observable behavior?
+- Are current quality gates enough for the newest change?
+- Do `CHANGELOG.md`, `RELEASE.md`, and the release workflow still agree on the release path?
+- Do commit message rules and contributor examples still match `commitlint.config.mjs`?
+- Are hooks still fast enough to help rather than hinder contributors?
+
+## Ownership rule
+
+Anyone changing code, tooling, or workflow is responsible for updating the quality gates if the risk profile changes.

package/template/docs/specs/README.md

@@ -0,0 +1,36 @@
+# 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.
+
+## Required structure
+
+Use [`TEMPLATE.md`](./TEMPLATE.md). Each spec should define:
+
+- purpose
+- behavior
+- inputs
+- outputs
+- constraints
+- edge cases
+- acceptance criteria
+
+## Lifecycle
+
+- Draft or update the relevant spec before implementing a non-trivial change.
+- Keep the spec narrow and testable.
+- If implementation diverges from the spec, reconcile them immediately.
+
+## Current specs
+
+- [`app-bootstrap.md`](./app-bootstrap.md)
+- [`counter-component.md`](./counter-component.md)
+- [`quality-workflow.md`](./quality-workflow.md)

package/template/docs/specs/TEMPLATE.md

@@ -0,0 +1,34 @@
+# Spec: Title
+
+## Status
+
+Draft | Approved | Superseded
+
+## Purpose
+
+Describe why this behavior exists.
+
+## Behavior
+
+Describe the observable behavior.
+
+## Inputs
+
+Describe user, system, or configuration inputs.
+
+## Outputs
+
+Describe rendered output, state changes, or side effects.
+
+## Constraints
+
+List constraints that implementation must respect.
+
+## Edge cases
+
+List the important boundary conditions.
+
+## Acceptance criteria
+
+- Criterion 1
+- Criterion 2

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

@@ -0,0 +1,46 @@
+# Spec: App bootstrap
+
+## Status
+
+Approved
+
+## Purpose
+
+Provide a predictable, minimal startup path for a standalone KoppaJS application.
+
+## 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` and `counter-component` with KoppaJS Core.
+- `src/main.ts` invokes `Core()` once to bootstrap the application.
+
+## Inputs
+
+- Browser loading `index.html`
+- Static asset and source file paths resolved by Vite
+
+## Outputs
+
+- A rendered `<app-view>` application shell
+- A registered `<counter-component>` available to the root view
+
+## 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`.
+- No hidden self-registration inside component modules.
+- Bootstrap must rely on the public KoppaJS root API via `Core()` rather than non-public setup helpers.
+- No extra runtime dependencies are required beyond the declared npm packages.
+
+## Edge cases
+
+- If a component tag changes, both `index.html` and `src/main.ts` must be updated together.
+- If more bootstrap behavior is added, it must not introduce a second source of truth for initialization.
+
+## 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 root view can render the counter component immediately after bootstrap.

package/template/docs/specs/counter-component.md

@@ -0,0 +1,48 @@
+# Spec: Counter component
+
+## Status
+
+Approved
+
+## Purpose
+
+Demonstrate local interactive state in a minimal KoppaJS component.
+
+## Behavior
+
+- The component renders a "Counter" label, a numeric count, and increment/decrement buttons.
+- The initial count is `0`.
+- Clicking the increment button increases the count by `1`.
+- Clicking the decrement button decreases the count by `1`.
+- The displayed count updates immediately after each click.
+- The increment and decrement buttons expose stable accessible names.
+- The rendered count is announced politely to assistive technology when it changes.
+
+## Inputs
+
+- User clicks on the increment button
+- User clicks on the decrement button
+
+## Outputs
+
+- Updated numeric text rendered in the component
+- No external side effects
+
+## Constraints
+
+- State is local to the component.
+- The component performs no persistence, networking, or cross-component coordination.
+- The component remains embeddable inside the root app shell.
+
+## Edge cases
+
+- Negative values are allowed.
+- Repeated clicks continue to update the count linearly within normal JavaScript number behavior.
+
+## Acceptance criteria
+
+- The counter is visible inside the app shell when the starter loads.
+- The first rendered value is `0`.
+- A single click on `+` changes the value from `0` to `1`.
+- A single click on `-` changes the value from `0` to `-1`.
+- Assistive technology can distinguish the increment and decrement actions without relying on symbol glyphs alone.

package/template/docs/specs/quality-workflow.md

@@ -0,0 +1,62 @@
+# Spec: Quality workflow
+
+## Status
+
+Approved
+
+## Purpose
+
+Keep the starter's tooling, tests, and contributor workflow consistent enough that regressions are caught early without turning a minimal example into a heavyweight platform.
+
+## Behavior
+
+- The repository exposes a fast local validation path through `pnpm check`.
+- The repository exposes a fuller validation path through `pnpm validate`, which adds a real-browser smoke test.
+- Staged files run through a fast `lint-staged` pre-commit hook.
+- Commit messages are validated by `commitlint` in a `commit-msg` hook.
+- Source, config, and test changes are checked by ESLint, Prettier, TypeScript, and Vitest.
+- The real UI smoke path is checked by Playwright against `vite preview`.
+- CI runs the same full validation flow as local contributors.
+- Tagged releases rerun the full validation flow and verify tag/version alignment before a GitHub Release is created.
+- Stylelint is intentionally absent until the repository has a credible way to lint embedded `.kpa` CSS without covering only the least relevant styling surface.
+
+## Inputs
+
+- Source, config, test, and documentation changes
+- Staged files at commit time
+- Commit messages at commit time
+- Pull requests and pushes that trigger CI
+- Version, changelog, and tag pushes that trigger the release workflow
+
+## Outputs
+
+- Consistent formatting on supported file types
+- Conventional commit history for maintainable review and release preparation
+- Type-safe source and TypeScript tooling files
+- Automated confidence for the `.kpa` export workaround, bootstrap wiring, and the starter UI smoke path
+- A guarded GitHub release path that fails when the pushed tag does not match `package.json`
+- Fast feedback before commit and in CI
+
+## Constraints
+
+- Hooks must stay fast enough for normal local use.
+- Playwright coverage must remain focused on smoke-level user journeys until the UI surface grows.
+- Tooling should stay aligned with the starter's actual risk profile rather than generic best-practice checklists.
+- Release automation must stay consistent with the repository remaining `private`; it may create GitHub Releases but must not imply npm publishing.
+- Commit rules should stay simple enough that contributors can apply them without release tooling knowledge.
+
+## Edge cases
+
+- If browser binaries are not installed locally, contributors must install Chromium before running `pnpm test:e2e` or `pnpm validate`.
+- If Stylelint is introduced later, it must cover the meaningful styling surface rather than only `src/style.css`.
+- If the UI grows beyond a simple smoke surface, expand Playwright coverage deliberately and update this spec.
+- If a pushed tag does not match `package.json`, the release workflow must fail before creating a release artifact.
+- Auto-generated merge, revert, `fixup!`, and `squash!` commits may be exempted by the hook logic.
+
+## Acceptance criteria
+
+- `pnpm check` runs lint, format verification, type checking, Vitest, and build successfully on a clean checkout.
+- `pnpm validate` reuses the built output to run the Playwright smoke test successfully.
+- A commit with a staged lint or formatting error is blocked by the pre-commit hook.
+- A non-conventional commit message is blocked by the `commit-msg` hook.
+- A pushed `vX.Y.Z` tag is rejected by release automation when `package.json` contains a different version.

package/template/eslint.config.mjs

@@ -0,0 +1,54 @@
+import js from "@eslint/js";
+import globals from "globals";
+import { fileURLToPath } from "node:url";
+import tseslint from "typescript-eslint";
+
+const tsconfigRootDir = fileURLToPath(new URL(".", import.meta.url));
+
+export default tseslint.config(
+  {
+    ignores: [
+      ".ai/**",
+      "coverage/**",
+      "dist/**",
+      "node_modules/**",
+      "playwright-report/**",
+      "test-results/**",
+    ],
+  },
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    extends: [js.configs.recommended],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ["**/*.{ts,mts,cts}"],
+    extends: [...tseslint.configs.recommendedTypeChecked],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir,
+      },
+    },
+  },
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+  },
+  {
+    files: ["tests/**/*.ts", "*.config.ts"],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+);

package/template/package.json

@@ -1,21 +1,72 @@
 {
-  "name": "koppajs-example",
+  "name": "__PROJECT_NAME__",
   "version": "1.0.0",
   "private": true,
-  "description": "Minimal starter example for KoppaJS.",
+  "description": "KoppaJS application scaffolded with create-koppajs.",
   "author": "Bastian Bensch",
   "license": "Apache-2.0",
+  "keywords": [
+    "koppajs",
+    "koppa",
+    "starter",
+    "scaffold",
+    "vite",
+    "typescript",
+    "web-components"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0",
+    "pnpm": ">=10"
+  },
   "scripts": {
     "dev": "vite --host",
-    "build": "tsc && vite build",
-    "serve": "vite preview"
+    "build": "tsc --noEmit && vite build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --write --ignore-unknown",
+    "format:check": "prettier . --check --ignore-unknown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "pnpm build && playwright test",
+    "test:e2e:headed": "pnpm build && playwright test --headed",
+    "test:e2e:ui": "pnpm build && playwright test --ui",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test:run && pnpm build",
+    "validate": "pnpm check && playwright test",
+    "release:check": "pnpm validate",
+    "typecheck": "tsc --noEmit",
+    "serve": "vite preview",
+    "serve:e2e": "vite preview --host 127.0.0.1 --strictPort --port 4173",
+    "prepare": "husky"
   },
   "dependencies": {
-    "@koppajs/koppajs-core": "^3.0.0"
+    "@koppajs/koppajs-core": "^3.0.2"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/js": "^10.0.1",
     "@koppajs/koppajs-vite-plugin": "^1.0.0",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.4.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.3",
+    "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "vite": "^7.2.6"
+    "typescript-eslint": "^8.57.0",
+    "vite": "7.2.6",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts,mts,cts}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,html,json,md,yml,yaml}": "prettier --write"
   }
 }

package/template/playwright.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const port = 4173;
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: true,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  use: {
+    baseURL: `http://127.0.0.1:${port}`,
+    screenshot: "only-on-failure",
+    trace: "on-first-retry",
+    video: "retain-on-failure",
+  },
+  webServer: {
+    command: "pnpm serve:e2e",
+    url: `http://127.0.0.1:${port}`,
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: {
+        ...devices["Desktop Chrome"],
+      },
+    },
+  ],
+});