consumeText() walked every code point, appended it to the line string and called TextEncoder.encode() on it to count UTF-8 bytes, so a 250KB chunk allocated ~250k arrays on the main thread. It now finds the next CR/LF with one regex scan, appends the text before it as one slice and encodes that slice once for its byte count. Byte counts only grow within a line, so checking the line/incomplete-buffer limits per segment fails on exactly the same inputs as the per-character check. BOM, pending CR across reads, CRLF terminator bytes and QUEUE_OVERFLOW ordering are unchanged. Correctness: existing parser tests pass unchanged. New tests (all green on the old parser first, as characterization): whole vs byte-by-byte input with CRLF, CR-only, multi-line data, BOM and a mid-stream U+FEFF, 2/3/4-byte UTF-8 split across reads; trailing CR blank line dispatched at finish; UTF-8 bytes (not UTF-16 units) counted against line and event limits, also when a multibyte character is split across reads; a max-size line over 1,000-byte reads accepted and one byte more rejected; a 248,780-byte chunk of 200 events. Benchmark (throwaway script, not committed; Node 24.14; 200 events in one ~250KB chunk; machine under load avg 39-54 on 22 cores, so numbers are noisy): - old/new interleaved in one process, forced GC before each run, median: ASCII 248,780 B: 294-345 ms -> 4.3-8.2 ms (36-80x) multibyte 248,180 B (Korean/emoji/accented): 95-130 ms -> 19-26 ms (~5x) - each parser standalone, sequential runs, average: ASCII: 664-764 ms -> 0.9-3.7 ms multibyte: 155-196 ms -> 1.5-6.3 ms Remaining cost of the new parser is mostly native TextDecoder/TextEncoder work (profiled); a JS charCode loop for the byte count was not faster. Gates: check:architecture, check:types:app, check:types:test, lint, test:component pass. test:unit passes except removal-fixture.test.ts, which needs generated artifacts/release evidence absent from this fresh worktree (unrelated). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Clean Architecture Frontend Template
A React/Vite reference implementation where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.
Start locally
Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and
Corepack. The repository pins pnpm in package.json.
Product source, tests, build/quality scripts, and supported tool configuration
are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
erasable-syntax enforcement. Project-owned executable source contains no
JavaScript-family files; negative architecture, security, and type-compatibility
fixtures are TypeScript/TSX as well.
corepack pnpm install --frozen-lockfile
corepack pnpm dev
Runtime-public settings live in public/config.json and are validated before
the product tree mounts. Client secrets are forbidden.
Included starter experience
The default build mounts a domain-neutral application shell with a header,
responsive sidebar, route focus management, session integration status, and a
persistent system / light / dark theme selector.
| Route | Purpose |
|---|---|
/ |
implementation readiness and starter links |
/examples/ui |
buttons, fields, cards, alerts, badges, modal, and tokens |
/examples/states |
loading, refresh, empty, error, auth, forbidden, and not-found states |
/examples/auth |
reactive external-auth integration seam |
/examples/reference-resources |
removable, session-required reference feature |
AUTH_MODE=demo is credential-free and accepted only in local/development
environments. Deployments use AUTH_MODE=external and provide the opaque auth
owner described in
docs/architecture/starter-experience.md.
The client route policy is user experience only; server authorization remains
authoritative.
Architecture
This repository is a Frontend Application Foundation: a starter/composition skeleton plus a reusable capability platform. Platform capabilities stay horizontal while product business features use vertical slices.
Dependencies point inward:
presentation -> application -> domain
adapters -----^
bootstrap composes concrete adapters
feature use case -> feature port <- feature-owned capability binding
See
docs/architecture/frontend-application-foundation.md,
docs/architecture/overview.md, docs/architecture/layers.md, and
docs/architecture/starter-experience.md. The removable vertical slice is
under src/features/reference-feature; its domain, application input, HTTP
binding, contracts, route runtime, and presentation own their contributions.
The central installed catalogs only aggregate selected contributions. The
generic starter routes continue to typecheck, test, and build after that
feature is removed.
Platform capability review
The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:
- platform capability review
- ports, adapters, and feature boundaries
- REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State
- Protobuf browser transports and REST Gateway
- backend API and Server State handoff contract
- TypeScript, state ownership, and data flow
- routing, page templates, and reusable patterns
- browser data capability completion ledger
- browser file and origin-storage platform
- client cache and storage
- realtime events, Web Push, and bounded polling
- presigned transfer, resumable upload, streaming download, and Image CDN
- server file capability infrastructure
- design-system platform
- frontend platform testing strategy
- implementation roadmap
These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.
Verification
Common local checks:
corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
test:all is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run corepack pnpm test:system only on the
compatible Linux assurance host described in
docs/testing/taxonomy.md.
check:types는 source, Node scripts/config와 tests를 분리된 TypeScript
project로 모두 검사한다. type/architecture/security/registry의 invalid
fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로
실행된다. 도구 호환성 결정은
VD-01에 기록돼
있다.
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
TypeScript/TSX negative fixture로도 검증된다.
Install the pinned Playwright browser engines before the first cross-browser run:
corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
review:a11y-manualneeds a signed human keyboard/focus/screen-reader review for all ten registered routes:APP_HOME,EXAMPLES_PLATFORM,EXAMPLES_UI,EXAMPLES_STATES,EXAMPLES_AUTH,NOT_FOUND,REFERENCE_RESOURCE_LIST,REFERENCE_RESOURCE_DETAIL,REFERENCE_RESOURCE_FORMandREFERENCE_RESOURCE_STATUS.verify:documentationderives that list from the route registry and fails if this paragraph falls behind it.collect:web-vitals-evidencestaysFAIL_UNVERIFIEDuntil a reviewed minimum eligible-sample threshold and 28 days of production data exist.
Live release verification additionally requires HOSTING_BASE_URL.
CI and evidence
The 27-gate registry is config/ci/gates.json; the Gitea workflow is
.gitea/workflows/quality-gates.yml. It follows:
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
DOCUMENTATION_READY is independent. No gate is downgraded to a warning.
Machine-readable evidence is written below artifacts/; generated evidence is
ignored by Git while .gitkeep files preserve the taxonomy.
Operational details are in docs/operations/, with incident procedures in
docs/runbooks/.