A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.

Why This Exists

Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?

The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.

This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.

Quick Start

npm install -D @techninja/clearstack
npx clearstack init       # scaffold a spec-compliant project
npm install
npm run spec watch        # start dev server + spec dashboard

npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.

What's In The Box

A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.

Specification

| Document | What It Covers | | --------------------------------------------------------------------------- | -------------------------------------------------------------- | | FRONTEND_IMPLEMENTATION_RULES.md | Philosophy, framework choice, project structure, atomic design | | COMPONENT_PATTERNS.md | Authoring, light DOM, styling, layout engine, JSDoc typing | | STATE_AND_ROUTING.md | Store, routing, unified app state, realtime SSE sync | | CONVENTIONS.md | Naming rules, anti-patterns | | SERVER_AND_DEPS.md | Express server, import maps, vendor dependency loading | | BACKEND_API_SPEC.md | REST CRUD, JSON Schema via HEAD, entity management | | TESTING.md | Testing philosophy, tools, patterns, phase checkpoints | | I18N.md | Internationalization — 4-layer cascade, t() usage, conventions | | BUILD_LOG.md | How this project was built — LLM-human collaboration proof | | QUICKSTART.md | Scaffolder setup, development workflow, updating, compliance |

Using Clearstack

Install as a dev dependency, scaffold, and keep in sync:

npm install -D @techninja/clearstack    # add to your project
npx clearstack init                     # scaffold (interactive)
npx clearstack init -y                  # scaffold (fullstack defaults)
npx clearstack init --static            # scaffold (static, no server)
npx clearstack update                   # sync docs (skip existing configs)
npx clearstack update --force           # sync docs + overwrite configs
npm run spec                            # check compliance

Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).

See QUICKSTART.md for the full walkthrough.

Rules That Matter

• No build tools. ES modules served directly to the browser.
• ≤150 lines per code file. When it grows, it splits.
• Light DOM by default. Shared styles just work.
• JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
• Test at the boundary. Each phase passes before the next begins.
• The spec checks itself. npm run spec code and npm run spec docs.
• Lint and format. ESLint + Prettier, semicolons, 2-space indent.

Scripts

npm run spec watch  # Dev server + continuous spec dashboard (recommended)
npm start           # Start server only
npm run dev         # Start server with --watch
npm test            # Node + browser tests
npm run lint        # ESLint check
npm run lint:fix    # ESLint auto-fix
npm run format      # Prettier auto-format
npm run typecheck   # JSDoc type validation via tsc
npm run spec        # Spec compliance (interactive)
npm run spec all    # Full spec check
npm run spec code   # Check code files ≤150 lines
npm run spec docs   # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream

Watch dashboard keys

q / Ctrl-C   quit
↑ ↓           scroll violations
c            copy violations to clipboard (paste into LLM)

License

MIT