Merge pull request #12 from cs-util-com/v4

V4

Author: cs-util

.gitignore

@@ -1,5 +1,7 @@
 # Stryker Mutation testing
 .stryker-tmp/
+mutation-testing/reports/mutation-report.json
+mutation-testing/reports/html/
 
 # Logs
 logs
@@ -25,6 +27,8 @@ lib-cov
 # Coverage directory used by tools like istanbul
 coverage
 *.lcov
+playwright-report/
+test-results/
 
 # nyc test coverage
 .nyc_output

.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "semi": true
+}

AGENTS.md

@@ -1,106 +1,49 @@
-# AGENTS.md — TemplateJs
 
-Canonical instructions for coding agents. Human-facing docs are in `README.md`.
+# Rules
 
-## Quick facts
-- Minimal single-page web app (static HTML + modular JS)
+## General
+- Minimal local first web app (static HTML + modular JS)
 - Entrypoint: `index.html` (+ static pages in `pages/`)
-- Source in `src/` with colocated tests
-- Deploy via GitHub Pages from `main` (static assets)
-- Preferred dev env: Codespaces (optional)
-
-## Runbook
-- Before commit: `npm run check:all` then `npm test`
-- Before PR/release: `npm run validate:all` (tests + checks + mutation)
-- Always run commands in a real terminal and include actual output in notes/PRs.
+- Source composed of small, focused modules in `src/` (`components/`, `utils/`, ..) with colocated tests
+- Frequently during development and before each commit: run `npm test` 
+- `README.md` typically contains big picture dev. spec and context. It should be kept up to date whenever the code is ready for a PR
+- Static app => serve `index.html` with simple static server (e.g., VS Code Live Server)
+- Only change code directly related to the current task; keep diffs small
+- Preserve existing comments & docs; add concise, long-lived comments where useful and avoid narrating changes via comments
+- When external documentation is needed and you lack a browsing/online search tool, ask the user to run an online search for you (e.g., "Please search for \"x\" and paste back the findings")
 
-## Build/Serve
-- Static app; serve `index.html` with a simple static server (e.g., VS Code Live Server)
+## Dependencies & no-build approach to use
+This project follows a no-build, static workflow:
+- Use native ES modules and `<script type="importmap">` to map bare specifiers when needed.
+- Then load your entry/module scripts with `<script type="module">` and import using the mapped specifiers.
+- Prefer CDN URLs from unpkg.com for third-party modules compatible with ESM.
+- Do not add bundlers/build chains unless explicitly requested in an issue/PR.
 
-## Tests
-- Run all tests: `npm test`
-- Tests live near code: `src/**/foo.test.js`, `*.property.test.js`
+## Test layout
+- Unit specs: `*.test.js`
+- Property-based specs: `*.property.test.js`
+- Property-based tests are important, don't omit them for important components
 - Keep tests deterministic and fast; avoid E2E unless asked
 
-Failure loop
-1) Prefer the simplest fix
-2) Make minimal, focused changes
-3) Re-run failing tests immediately and include real output
-4) Iterate until green
-
-## Coding guidelines
-- Small, focused modules in `src/` (`components/`, `utils/`)
-- Keep public HTML under `pages/` stable; don’t break URLs
-- Use existing lint/format scripts if present
-
-## Commits & PRs
-- Commits: concise; Conventional Commits preferred (e.g., `feat: add person card`); don’t churn history for formatting
-- PRs: small, scoped diffs; explain what you ran (install/tests/validation); add/update tests for changed behavior
-
-Checklist
-- [ ] `npm ci` and `npm run validate:all` pass locally
-- [ ] Tests added/updated for new behavior
-- [ ] No unrelated refactors/drive-bys
-- [ ] PR description includes summary, commands run, brief test output
-
-## Safety & guardrails
-- No secrets (.env/tokens/creds)
-- No deploy changes (Pages/release flows)
-- Least privilege: prefer read-only changes
-
-## File map (read before changing code)
-- `README.md`
-- `package.json` source of truth for commands
-- `index.html`, `pages/` static entry points
-- `src/` — app code and tests
-
-## When in doubt — ask before
-- Large refactors
-- Changing public URLs or Pages config
+## TDD Failure loop to use
+1. Prefer the simplest fix first 
+2. Use TDD: Add a failing test first and run `npm test` to verify it's failing
+3. Make minimal, focused changes
+4. Re-run `npm test` after each fix and document real output
+5. Iterate until green
 
-## Feature development process (for agents)
+## Feature development process to use
 
 Follow this lightweight spec-first flow before coding:
 
 1) Requirements gathering
-- Ask one question at a time and iterate until requirements are complete.
-- Build each question on previous answers; prefer numbered response options to keep it structured.
+- Ask one question at a time and iterate until requirements are clear.
+- Build each question on previous answers; prefer 4+ numbered response options for the user to select from.
+- For larger changes: draft a high-level implementation plan and pause for explicit user approval before modifying code.
 
 2) Specification development
-- Major features: capture functional requirements, architecture choices/integration points, data handling (I/O, validation), error handling and edge cases, testing strategy (unit, property-based, integration), and any UI/performance considerations.
-- Smaller changes: clearly state what changes, how it integrates, and key edge cases.
+- Smaller changes: clearly state what changes, how it integrates, testing strategy and key edge cases.
+- Major features: capture functional requirements, architecture choices/integration points, data handling (I/O, validation), error handling and edge cases, testing strategy (unit + property-based + integration), and any UI & performance considerations.
 
 3) Final specification
-- Compile a concise developer-ready spec markdown next to new components if any were added
-
-## Implementation guidelines
-- Only change code directly related to the current task; keep diffs small
-- Preserve existing comments/docs; add concise, long-lived docs where useful and avoid narrating changes via comments
-
-## Quality checks
-- During development: run frequently
-  - `npm run check:all`
-  - `npm test`
-- Before PR: `npm run validate:all` (tests + checks + mutation)
-
-Test structure
-- `*.test.js` — unit
-- `*.property.test.js` — property-based (fast-check)
-- Mutation: `npm run mutation` (CI too); aim >50%
-
-Failure triage loop
-1. Simplest fix first
-2. Minimal changes
-3. Re-run the specific failing scope
-4. Iterate until green
-
-Verification discipline
-- Only claim pass/fail with real command output
-
-## Dependencies & no-build approach
-
-This project follows a no-build, static workflow:
-- Use native ES modules and `<script type="importmap">` to map bare specifiers when needed.
-- Then load your entry/module scripts with `<script type="module">` and import using the mapped specifiers.
-- Prefer CDN URLs from unpkg.com for third-party modules compatible with ESM.
-- Do not add bundlers/build chains unless explicitly requested in an issue/PR.
+- Compile a concise developer-ready spec markdown next to new components if any were added. Include as a first line a summary that could also be used as a commit message for the change.