Add Electron accessibility research note to guides

[malpern]

What

Adds guides/electron-text-parity.md — a research note on why accessibility-driven text
manipulation works in native macOS text fields and fails in Electron ones.

It documents 14 defects and missing capabilities, allocated by owner:

• Chromium (6) — text offset mapping bugs, contenteditable linearization, write-path
  fidelity, granular AXMode, tree-readiness signal, conformance tests
• Electron (4) — false advertisement of support, AXManualAccessibility robustness,
  granular mode plumbing, text-layer triage ownership
• Apple (4) — undocumented AXTextMarker, no assistive-tech activation API, no modern
  custom-attribute path, no capability negotiation

Item IDs (C1–C6, E1–E4, A1–A4) are stable and intended to be quotable in upstream reports.

Also cross-linked from guides/kindavim.md, which already refers to the Keyboard fallback
strategy without explaining why it's needed, and added to the docs.md landing page.

Why

The KindaVim guide tells users that Slack gets a degraded command set, but not why or what would
have to change. This fills that gap and doubles as a reference for anyone wanting to push fixes
upstream.

Open questions

• Placement. AGENTS.md reserves guides/ for user-facing content and docs/ for
  developer-facing material. This is developer-facing but needs to be publicly reachable, so it
  went in guides/. Moving it to a separate research section on the site is a reasonable
  alternative.
• Not yet published to gh-pages. The copy step is deliberately not done — destination
  pending review.

Confidence

Marked inline in the document rather than smoothed over. Four items are inference rather than
citation and say so: C3 (argues from symptoms, not from Blink source), C2 (WebKit
comparison is judgement, not measurement), C6 (inferred from C1 persisting), and A4
(observation that no such API exists).

Most recent upstream activity found is 2023–24. The note states explicitly that this is
absence of search results, not proof of inactivity.

Every other item cites a primary source.

Testing

Documentation only — no code paths touched. Jekyll frontmatter matches the existing guide
convention (layout, title, description, theme, permalink).

[claude]

Reviewed the new guides/electron-text-parity.md guide and the two nav-link additions (docs-only change). Two content-accuracy nits worth fixing before merge:

1. "Five Tools Hit This Independently" table includes a non-tool. The table and the surrounding claim ("None of them fixed it. They all routed around it") frame all 5 rows as tools that independently converged on the same workaround. But the "Electron #36337" row isn't a tool — it's the bug report itself, and its "Route around" cell reads "Closed as not planned," which contradicts "they all routed around it" (nothing was routed around there — the issue was just closed). Worth reframing the table/row or dropping it from the "tools" framing so the convergence argument stays accurate.

2. Confidence section is incomplete. The "Confidence" block says "High — C1, C4, C5, E1–E4, and A1–A3 are each grounded in a cited source below" and "Inference — C3," but never rates C2 (the "WebKit handles this better" contenteditable claim), C6 (no conformance tests), or A4 (no capability negotiation) — all stated as confident assertions with no citation. Since the doc explicitly invites readers to quote it in upstream bug reports, this gap should be closed (either cite them or add them to the confidence breakdown).

No structural/build issues — the new Liquid relative_url links in docs.md and kindavim.md are consistent with existing entries, and the front matter/permalink match the guide conventions used elsewhere.

[malpern]

Both points were correct — fixed in 2c86b0a, along with a third error the review didn't catch.

1. Non-tool in the convergence table. Right on both counts: electron#36337 is a bug report, not a tool, and "closed as not planned" is the opposite of routing around the problem. The table is now four tools. The bug report moved to prose, where it actually strengthens the argument rather than undermining it — workarounds succeed, upstream fixes stall, and that asymmetry is the finding.

2. Incomplete confidence breakdown. Also right, and it mattered more than the first one, since the document explicitly invites readers to quote item IDs upstream. C2, C6 and A4 were stated as confidently as the cited items. All four inference items are now listed with what specifically is unverified about each:

• C3 argues from observed symptoms, not from reading Blink
• C2's WebKit comparison is domain judgement, not measurement
• C6 is inferred from C1 persisting, not confirmed against Chromium's test suite
• A4 observes that no such API exists — easy to falsify if one does

3. Arithmetic. Found while fixing the above: the gap count was stated as 13. It's 14 — 6 + 4 + 4.

Note that this branch is not yet copied to gh-pages; the publish step is deliberately held pending a decision on whether this belongs in guides/ or a separate research section.

---

Generated by Claude Code

[claude]

One actionable finding in guides/electron-text-parity.md:

• Suspicious/placeholder citation URL in the Sources list: [kindaVim: reaching inputs ↗](https://github.com/godbout/kindaVim.blahblah/discussions/43). The repo name kindaVim.blahblah looks like an unreplaced placeholder rather than a real repository, unlike the other citations in the same list (godbout/kindaVim.docs, electron/electron, nchudleigh/vimac, etc.). Since the doc explicitly states item IDs and sources are "intended to be quotable in upstream bug reports," a dead/fake link here undermines the credibility of an otherwise carefully-hedged research note (it even has an explicit Confidence/Inference section calling out other claims as unverified, but doesn't flag this one). Please verify and fix the URL before merge, or drop the citation if it can't be confirmed.

Everything else (front matter, permalinks, cross-links added in docs.md and kindavim.md) is consistent with the existing guide structure — no other issues found.

[malpern]

Verified this one before changing it — the URL is not a placeholder. godbout/kindaVim.blahblah is the real repository name, and both the repo and the discussion resolve live:

• godbout/kindaVim.blahblah — 993 stars, 582 commits, 40 open issues, active
• Discussion refactor: extract plist generation into standalone PlistGenerator #43 "reaching inputs", posted by @godbout, exists under that exact name

The author uses a .theapp / .docs / .blahblah naming convention across their repos, which is unusual enough to read as a template artifact but is genuine.

That said, the underlying observation was a fair catch. The sources list cited kindaVim.docs/issues/70 alongside kindaVim.blahblah/discussions/43 — two names for one project. The repository was renamed and GitHub redirects the old path, so both worked, but the inconsistency is exactly what made the link look broken. Both now point at the current name in 32f94f7.

No change to the confidence section: these citations resolve to real primary sources, so they don't belong in the inference list.

---

Generated by Claude Code

[claude]

Reviewed this docs-only diff (new guides/electron-text-parity.md + two nav links). No correctness/reliability/security/performance/test-coverage issues — there's no executable code here.

Two minor, non-blocking notes:

• The page cites external URLs (e.g. godbout/kindaVim.blahblah, the Electron/Chromium issue links) that I can't verify from the diff alone — worth a quick manual click-through before merge to make sure none 404.
• The frontmatter description is on the long side for a meta description (~150 chars); consider trimming for SEO if that matters for this site.

The doc already does the right thing by self-labeling speculative claims (C2, C3, C6, A4) as 'Inference'/'Unverified' rather than presenting them as fact, so no concerns there.

[malpern]

Both checked.

Frontmatter description — trimmed in 7f1d3b1. The point holds: at 152 characters it was the longest description in guides/, against a median of 85 and a next-highest of 125 (kindavim.md). Now 121, in line with the existing range.

External URLs — partially verified, and I can't finish the job from here. Reporting precisely rather than claiming a clean bill:

Verified live, real content returned:

URL	Result
electron/electron#36337	exists — offset bug, closed not planned
electron/electron#37465	exists — attribute unsettable
electron/electron#10305	exists — AXManualAccessibility added
nchudleigh/vimac#78	exists — activation side effects
godbout/kindaVim.blahblah#70	exists — Firefox false positive
godbout/kindaVim.blahblah discussion 43	exists — "reaching inputs", by @godbout

Not verified — the six remaining hosts are blocked by this environment's network policy. The proxy returns connect_rejected / "gateway answered 403 to CONNECT" for espanso.org, chromium.googlesource.com, www.chromium.org, www.hammerspoon.org, developer.chrome.com, and shortcat.app. That is a policy denial on my side, not evidence about those URLs — they came from search results with real content summaries, but I can't confirm them by fetching.

So the manual click-through you suggested is still worth doing, specifically for those six. I'd rather flag the limit than imply I checked links I couldn't reach.

---

Generated by Claude Code

[claude]

Docs-only PR, a few things worth a look before this goes live:

1. Verify external citations before merging. The guide explicitly states item IDs are "intended to be quotable in upstream bug reports" and cites specific issue/PR numbers (electron#36337, electron#37465, electron#10305, vimac#78, kindaVim#70, kindaVim discussion refactor: extract plist generation into standalone PlistGenerator #43) with claimed outcomes ("closed as not planned", "fixed in 2023 by an outside contributor", etc.). If any of these numbers, statuses, or attributed quotes are inaccurate, readers who copy these citations into real upstream bug reports will be misled — worth a manual double-check of each link/claim since this can't be verified from the diff alone.

2. Confidence section slightly overstates citation coverage. "Cited — ... A1–A3 each rest on a primary source listed below" — but A3 ("Custom attributes have no modern equivalent") has no distinct source in the Sources list; it reads as inferred from A2 (vimac#78) rather than independently cited. Might belong in the "Inference" bullet alongside A4 for consistency with how C2/C3/C6 are handled.

3. kindavim.md link description may not match the linked content. The new line says the guide explains "why the Keyboard fallback is needed in Slack," but electron-text-parity.md itself never uses the term "Keyboard fallback" — it discusses clipboard-based and synthesized-key workarounds (per Espanso) instead. Worth confirming this description reflects an existing concept elsewhere in kindavim.md rather than being a stray/mismatched term.

No code/build/test impact since this only touches guides/docs.md.

[malpern]

Point 1 caught a real error, and point 2 caught a second one. Both fixed in 80c7d1e.

1. Attributed outcome was wrong. You were right to push past "do the links resolve" to "are the claimed outcomes accurate." E2 said the AXManualAccessibility fix came from "an outside contributor." It did not — electron#38102 was authored by @codebytere, an Electron Member, merged 26 April 2023 and backported to the 23/24/25 branches. Replaced with those verifiable facts.

This is exactly the failure mode you described: someone quoting "fixed by an outside contributor" into an upstream thread would have been repeating something I inferred rather than checked. The original attribute (electron#10305) was from ivmirx with no visible member badge, but that association isn't confirmed either, so the guide now makes no claim about it.

2. A3's citation coverage was overstated. Also correct, and I verified why: electron#10305 contains no discussion of NSAccessibility custom attributes at all. That claim traces to a search-engine summary, not to anything in the source list. A3 moved to the Inference bullet with that reason stated explicitly, so a reader knows exactly what's unverified about it.

3. "Keyboard fallback" term. The term is legitimate — kindavim.md uses it in two places to describe KindaVim's degraded strategy, so the cross-link reads correctly from where the reader encounters it. But you're right that the target never picked the thread up. The guide now ties the Electron failure explicitly to why KindaVim runs the Keyboard strategy in Slack, so the link lands on the concept it promises.

Remaining known limit, unchanged from my last comment: six of the twelve cited hosts are unreachable from this environment's network policy, so they still want a manual click-through.

---

Generated by Claude Code

[claude]

Docs-only PR, mostly LGTM. One thing worth double-checking before merge:

• Sources section (guides/electron-text-parity.md) cites a suspicious repo name. Two links point at github.com/godbout/kindaVim.blahblah (issues/70 and discussions/43). That repo name looks like a placeholder/typo rather than KindaVim's actual GitHub repo — if it doesn't resolve, this guide ships two dead citations in the one section whose entire purpose is backing up the "Cited" confidence claims for C1/C4/E-items. Worth confirming the real org/repo name before publishing.

No other correctness/reliability issues spotted — the rest is prose/links with appropriately flagged "Inference"/"Unverified"/"Stale" caveats.

[malpern]

Already verified — see my earlier reply. Short version: godbout/kindaVim.blahblah is the real repository (993 stars, 582 commits, 40 open issues), and both issues/70 and discussions/43 resolve under it. Confirmed by live fetch, not inference.

The author uses a .theapp / .docs / .blahblah naming convention, which is unusual enough to read as a template artifact but is genuine. The links stay as-is.

Noting for the record that this is the second independent review pass to flag this same URL as suspicious. That's not evidence the link is broken — it's evidence the name looks broken, which human readers may also conclude. Flagging it for @malpern as a judgement call rather than acting on it unilaterally: the citation is correct, so I'm not changing it, but if it draws this reaction twice from automated review it may be worth a parenthetical in the Sources list.

---

Generated by Claude Code