DongHyeonkaandClaude Opus 5.5 aac7a32862 perf(realtime): split SSE lines on bytes and decode each line once (R3-5)
The parser now finds CR/LF with Uint8Array.indexOf before decoding, so a
line's UTF-8 byte count comes from byte offsets instead of re-encoding the
text. Each complete line is decoded once by a streaming fatal TextDecoder;
a line that continues into the next read is stream-decoded, and the bytes
of a character split across reads count once it completes, as before.

Behavior kept (the push() input was already Uint8Array; no seam change in
fetch-sse-connection.ts, public API unchanged):
- CR / LF / CRLF, CR and LF split across reads, multi-line data
- one leading BOM stripped (now done by the parser, decoder uses
  ignoreBOM: true, so a BOM at a later line start stays text)
- line / event / incomplete-buffer byte limits, same failure point
- drain() and the per-call item cap; kept bytes are copied
- a pending CR or the item cap waits while only part of a character is
  left, as the text-based parser did
- error codes (MALFORMED_EVENT / EVENT_TOO_LARGE / QUEUE_OVERFLOW / CLOSED)

Differences only on invalid UTF-8: the old parser decoded a whole chunk
first, so malformed bytes won over another error later in that chunk and
malformed bytes past the item cap failed in push(). Now the first
problem in stream order wins and those bytes fail in drain(). Both
still fail closed.

Fixed: Node's streaming TextDecoder (ignoreBOM: false) drops a U+FEFF
right after the stream's first character when that character is split
across reads, e.g. [EF] [BB BF EF BB BF] decoded to "" instead of
"". The old parser inherited that; the new one keeps the text.

Tests: existing parser and connection tests unchanged and passing. Added
a split-BOM case and a differential test against the round-2 parser
(tests/unit/realtime/sse-parser-reference.ts) over 2x1,500 seeded random
ASCII / multibyte streams with random read splits, random small limits,
truncated streams and skipped drains. 300,000 seeds also matched in a
manual run.

Benchmark (manual, not committed; Node v24.14.0, one push of one chunk,
best of 150 runs, host load average ~11-14 so absolute ms are noisy):

| input (one chunk)              | original e59994a | round 2 | new     | new vs original | new vs round 2 |
|--------------------------------|------------------|---------|---------|-----------------|----------------|
| ASCII, 249 KB, 209 events      | 103.72 ms        | 0.48 ms | 0.30 ms | 348x            | 1.6x           |
| Korean/emoji, 249 KB, 209 ev.  | 23.30 ms         | 0.85 ms | 0.44 ms | 53x             | 1.9x           |
| ASCII, 234 KB, 4 x 60 KB lines | 176.45 ms        | 0.61 ms | 0.34 ms | 513x            | 1.8x           |
| Korean/emoji, 234 KB, 4 x 60KB | 25.28 ms         | 1.10 ms | 0.65 ms | 39x             | 1.7x           |

Across five runs, multibyte new vs original stayed between 19x and 70x
(target: 10x or more).

Realtime bundle: 39903 / 40000 gzip bytes (baseline 39685, +218).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:31:29 +09:00

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:

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-manual needs 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_FORM and REFERENCE_RESOURCE_STATUS. verify:documentation derives that list from the route registry and fails if this paragraph falls behind it.
  • collect:web-vitals-evidence stays FAIL_UNVERIFIED until 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/.

S
Description
No description provided
Readme
20 MiB
Languages
TypeScript 98.2%
Python 1%
CSS 0.5%
Shell 0.3%