lume-js CLAUDE.md

CLAUDE.md — Lume.js

Agent onboarding: what this project is and how to navigate it. The process contract (artifact matrix, quality gates, commit rules) lives in AGENTS.md — read it before making ANY change. This file doesn't repeat it.

What this is

Lume.js is a reactive state-management library whose entire pitch is standards-only: plain JavaScript Proxy state + data-* attributes in valid HTML. No custom syntax, no build step, no virtual DOM. The product is trust in a tiny core: a 1.46 KB gz universal kernel (lume-js/state — works in Node/Deno/Bun/workers), 2.66 KB with DOM binding (lume-js), everything else opt-in via lume-js/addons and lume-js/handlers. Published on npm as lume-js (v2.3.1), MIT, docs site at https://sathvikc.github.io/lume-js/.

Formatting rule — never hard-wrap prose (STRICT)

Never hard-wrap prose at a fixed column — not in markdown files, not in commit message bodies, not in PR descriptions. One paragraph = one line; one list item = one line, however long. Editors soft-wrap; manual line breaks create ragged gaps and make diffs noisy. Line breaks in prose are reserved for real structure only: new paragraph, new list item, headings, tables, and code blocks (code keeps its normal line breaks).

Source-of-truth documents (read in this order)

1. AGENTS.md — the process contract. Non-negotiable.
2. docs/design/design-decisions.md — ratified decisions. If your change contradicts an entry, the entry wins until amended.
3. docs/design/VISION.md — direction, roadmap, open problems.
4. docs/ARCHITECTURE.md — how the code actually works (module walkthrough, data flow).

Directory map

src/
  core/state.js      # THE kernel: Proxy, per-state microtask flush, $subscribe, read observers
  core/batch.js      # cross-store synchronous batching (state.js imports it; never the reverse)
  core/effect.js     # auto-tracking + explicit-deps effects (built on withReadObserver)
  core/bindDom.js    # data-* attribute binding, handler engine, two-way input delegation
  state.js           # `lume-js/state` entry (kernel only, DOM-free)
  index.js           # `lume-js` entry (state + bindDom + effect)
  all.js             # CDN/global IIFE entry (re-exports everything)
  addons/            # computed, watch, repeat, persist, hydrateState, cleanupGroup, withPlugins, debug
  handlers/          # show, className, classToggle, boolAttr, ariaAttr, stringAttr, on, presets, htmlAttrs
  utils/log.js       # logError/logWarn (the only module handlers may import)
  *.d.ts             # HANDWRITTEN type declarations — update in the same commit as signature changes
tests/               # vitest + jsdom; mirrors src/ layout; 439 tests, 100% coverage enforced
docs/api/            # one reference page per public export
docs/guides/         # universal-core, choosing-reactive-primitives, cleanup, SSR
docs/design/         # design-decisions.md (contract) + VISION.md (roadmap)
docs/changes/        # per-commit write-ups for proposal branches
examples/            # runnable demos; import from 'lume-js' (vite alias → src/)
scripts/             # build.js, check-size.js, complexity.js, bench-core.js, build-site-assets.js
gh-pages/            # docs-site source (deployed by workflow — don't touch unless asked)
dist/                # generated by scripts/build.js — never edit, not tracked in git
.github/workflows/   # ci.yml (tests/coverage/gates), gh-pages.yml, publish.yml (on release)