ink-divergences.md used to record only divergences from Ink. Broaden it into the
single record point for the *whole* Ink relationship: it now also records deliberate
alignments (intentional sameness) as first-class entries, not just differences.
- Reframe the title + intro: three relationship kinds (deliberate alignments,
intentional divergences, non-behavioral notes), each a conscious decision.
- Elevate + strengthen the governing principle: aligning to Ink is only a means to
reduce bugs, never the goal — correctness and Vue philosophy outrank parity, and
"because Ink does it" is never on its own a justification.
- Add a first-class "Deliberate Alignments" section; promote the two deliberate-
sameness records (commit-timing Ink-alignment, literal-tab measure-vs-paint, the
latter keeping its existing [VOUCHED @hyf0]) out of Non-Behavioral Notes into it.
- Restructure the classification flow to split deliberate match vs deliberate
divergence first ("How to Classify an Entry").
- Update AGENTS.md guidance and the two stale cross-references to the renamed
headings (accessibility-api.md + the in-file ARIA entry).
No existing divergence entry's substance changed; no [VOUCHED] stamp was added or
removed (AI cannot self-bless). Reviewed by Codex + an independent reviewer.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the homegrown "Context Engineering" convention with the canonical
Project Context Records (PCR) block in AGENTS.md, and migrate the
.agents/docs/ records to match.
- cross-links: [[wiki-link]] -> relative markdown [name](./name.md)
- provenance: the old "Maintainer decision (DATE): KEEP" markers -> canonical
[VOUCHED @hyf0] stamps (dates dropped, KEEP/OVERRIDE verdicts kept), covering
every variant ((DATE, user-blessed), (maintainer decision DATE), and
"(Decision recorded after review surfaced it.)")
- methodology prose describing the mechanism reworded to the vouch vocabulary
(generic [VOUCHED @handle])
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A source-reading audit of the Ink-divergence ledger was wrong on all
three of its highest-confidence calls; running the real Ink/vue-tui
harness overturned them. Add a guideline: behavior claims (parity
assertions, "what Ink does" lines) are hypotheses until a real run
against the pinned version confirms them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Align several user-observable runtime behaviors with the Ink v7.0.4 parity audit: live input/paste handler refs, duplicate focus id registration, string-only color props, noninteractive empty final newlines, cross-realm error headers, and contained zero-content box layout/paint.
Document Vue-specific KEEP decisions and require Conventional Commits for commit messages and PR titles.
Co-authored-by: Claude <noreply@anthropic.com>
When parity/divergence work needs Ink's source, clone it once to a fixed path
(/tmp/ink) and read locally instead of relying on node_modules (Ink isn't a
dependency). Always check out and confirm the pinned baseline first — the exact
version/commit lives in .agents/docs/ink-divergences.md — since a claim read
against the wrong Ink version is worse than none.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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