Recorded notes / design docs should be concise and direct — the essential
what + why, led by the principle or intuition — without losing information
or sliding into essays / exhaustive mechanism dumps. Also: when a behavior
is the correct default, state the principle rather than framing it as a
framework limitation.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: remove Ink-parity design docs (.agents/docs), keep the code
Removes the Ink-parity loop documentation — ink-parity-loop.md, ink-parity.md,
and the parity-ledger.md — and drops the now-dangling 'Current docs:' list from
AGENTS.md's Context Engineering section (the convention itself is kept). All the
merged parity CODE fixes remain on main; only the documentation/ledger artifacts
are cleared, to re-orchestrate the documentation with a different approach.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add focused Ink intentional-divergences design doc
Replaces the removed sprawling parity docs with one focused doc that records
ONLY where vue-tui deliberately differs from Ink (API surface, additive
features, unavoidable Vue-vs-React semantics, N/A React concepts, framework
idioms) — leaving placeholders for the maintainer to supplement.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The concurrency notes described `sequence.concurrent: true`, but that was
rolled back — it starved timing-sensitive render tests on the 4-core CI runner.
Rewrite to reflect what actually ships:
- File-level parallelism (fileParallelism: true), tests within a file serial;
explain WHY in-file concurrency is deliberately avoided (the local-vs-CI
core-count trap) and that PTY needs pool: forks.
- *.sequential.test.* files group process-global-state tests (fake timers,
listener/yoga-node counts).
- New rule: tests must not implicitly depend on host env. CI=true flips
interactive mode off, so both vitest configs force CI:false; inject env
behavior explicitly and reproduce CI with `CI=true vp run ci` on a fresh
checkout.
- FORCE_COLOR must also be set in spawned child envs, not just vitest config.
Record the rule: when code has to be written in a surprising or non-idiomatic
way because the situation requires it (control-char regexes, deliberate
code-point spread, justified lint suppressions), add a comment explaining why,
so the next reader doesn't have to guess whether it's intentional.
The main suite is now concurrent too, so correct the earlier "not concurrent"
note. Record the convention: snapshot tests stay concurrent via context-local
expect; process-global-state tests (fake timers, listener/node counts) move to
*.sequential.test.* files marked it.sequential / describe.sequential.
Document that the PTY suite runs concurrently (and the wall-clock-assertion
pitfall there), plus the two patterns that force the main suite to stay
sequential, with the root cause and fix for each:
- Inline snapshots lose test context under concurrency — fixable via the
context-local `expect` (test.concurrent("...", ({ expect }) => ...)).
- Fake timers mutate process-global timer functions, so concurrent tests
clobber each other's mocked timer state — not fixable with context; must
stay sequential.
Investigated empirically: enabling sequence.concurrent on the main suite fails
deterministically (not flaky) in exactly the snapshot files (background-color,
borders) and fake-timer files (throttle, animation-scheduler).
Tests must exercise the same ANSI code paths users see. Without
FORCE_COLOR, chalk disables all color in non-TTY test environments,
making style bugs invisible to the test suite.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Wrap each text line with applyChalk(bgProps) after wrapText so
background color is reapplied on every wrapped line (wrap-ansi
doesn't carry ANSI state across line breaks)
- Add wrapped-text backgroundColor regression test
- Fix typo: color=" cyan" → color="cyan" in example
- Add FORCE_COLOR=3 debugging tip to AGENTS.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Workspace setup with pnpm, Vite+, and shared TypeScript config.
Includes @vue-tui/utils and AGENTS.md project conventions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Yunfei He