Skip to content

fix(chat): show a muted cue on a refused link's label - #28418

Merged
bolichen97 merged 1 commit into
mainfrom
fix/9945-refused-link-cue
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/9945-refused-link-cue

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When a chat link's destination is refused by the link policy, the reader sees that a link was there and why it does nothing, instead of a label that looks like ordinary prose.

A chat message like open [my note](obsidian://vault/note) or [click me](javascript:alert(1)) renders its label as plain text: the destination is refused (correctly), but nothing on screen says so. The reader cannot tell a refused link from a normal word, so the message reads as if the agent forgot the link.

Why it matters

Agents regularly send custom-scheme deep links (obsidian://, other app schemes) and occasionally empty [x]() links. Today those silently lose their destination, and the user has no clue to ask for the raw URL or to open it another way. A small, muted cue closes that gap without making a refused destination clickable.

Not a goal

  • Showing or copying the refused destination itself. It is already gone by the time the component renders, and exposing it is a separate question.
  • Explaining which rule refused it (custom scheme vs javascript:/data: vs empty). The reason is one generic sentence.
  • Changing which schemes are allowed, or the "never an anchor" contract for a refused destination.
  • md-notebook's Preview.tsx, which is not a chat renderer and keeps its plain span.
  • Recording a docs/decisions/ entry. The issue asks a maintainer to choose between keeping silent prose and adding a cue; this draft is the concrete form of the cue option for that choice, and an entry can only record a decision a maintainer made.

What changed (motivation → approach → change)

  • Symptom: a refused link's label is visually identical to the prose around it.
  • Cause: both chat renderers turn a link with no usable href into a bare <span>{children}</span> with no styling, title or accessible text.
  • Change: both chat renderers now render that span with a muted dotted underline built from existing tokens (text-muted, decoration-muted in the dashboard; var(--text-muted) in Mochi, whose windows do not load the dashboard stylesheet), a title with the generic reason, and the same reason as visually-hidden text so touch, keyboard and screen-reader users get it too. In the dashboard that text is a ::after pseudo-element fed from a data-refused-reason attribute (after:sr-only after:content-[attr(data-refused-reason)]), not a text node: inline commenting's resolveSourcePos aligns the element's text nodes against the source span, so a hidden text node would shift every later selection in the paragraph, and copying a message would paste the reason into the sentence. Mochi has no sourcePos mode and no stylesheet for a pseudo-element, so it keeps a visually-hidden span marked user-select: none. The reason is a new catalog key, components.markdownRenderer.refused_link_destination ("Link not active: its destination can't be opened here."), translated into all 11 shipped catalogs under website/src/i18n/locales/ (en.json plus de, fr, es, it, pt, ru, ja, ko, zh-CN, hi, bn) and the regenerated pseudolocale en-XA.json.
  • Every input that reaches the inert-label branch gets the cue: urlTransform's '' sentinel (custom scheme, empty destination) and an href the sanitizer deleted (javascript:, data:), which arrives absent exactly like a raw <a> that never had an href. The deleted-href case cannot be told apart from a raw <a> with no href, so a plain <a>label</a> shares the cue. A raw in-page anchor (name or id, both kept by the sanitizer) and an anchor with no content are targets, not links, and keep the plain span; website/src/components/markdown/refusedLinkCue.ts holds that one rule for both renderers.
  • website/docs/frontend-conventions.md documents the cue next to the existing refused-destination contract.
  • Allowed links (http(s), allowlisted editor schemes, session and forge links) are untouched.

Backwards compatibility

Compatible: only the styling and accessible text of an already-inert span change; no link becomes or stops being an anchor.

Removes nothing: the change adds a class, a title and a hidden suffix to an existing span and removes no path, key or behaviour.

Tests

  • website/src/test/MarkdownRenderer.test.tsx (rejected link destinations): a refused custom scheme carries data-refused-link, the muted dotted classes, the translated title and data-refused-reason, the ::after classes, label-only textContent, and the output never contains the destination; a sourcePos regression selects target after a refused link in target\n\nSee [note](obsidian://vault/note) target. and asserts resolveSourcePos returns line 3, column 35 (it returns undefined when the reason is a text node); javascript:, data:, [label]() and <a>bare</a> all get the same cue, while <a name="install">, <a id="top">, an empty <a name="top"></a> and an empty <a></a> render with no cue and no title. The existing https / vscode controls still render real anchors.
  • website/src/apps/mochi/test/mochiRefusedLinkAnchor.test.tsx: the same cue in Mochi's ChatPanel for obsidian://, javascript:, data: and empty destinations; the https control asserts no cue, and named / id-only / empty anchors get none.
  • Mutant checks: with the two production files restored from origin/main, the new cue tests fail; with the reason rendered as a hidden text node instead of ::after, the sourcePos test fails; with wearsRefusedLinkCue forced to true, both named-anchor tests fail; with the fix, all pass.

Proof: not provable -- frontend test (prove.py runs Python only)

Ran: npx vitest run src/test/MarkdownRenderer src/apps/mochi/test plus src/test/MarkdownPanelCoverage.test.tsx (121 files, 1640 tests pass), I18N_BASE_REF=origin/main npx vitest run src/i18n (54 files pass, including catalog parity), tsc --noEmit, eslint on the changed files.

Manual verification

Rendered MarkdownRenderer with the real stylesheet and English catalog in a local loopback Vite harness (not committed) and screenshotted it in dark and light themes with Playwright, plus Mochi's Bubble under its own theme. The hover title read back as the translated reason in both renderers, and the dashboard label's textContent read back as the label alone. A third dashboard shot forces the ::after reason visible (outlined) to show what assistive tech reads; a native title tooltip does not render in a headless screenshot.

Screenshots / video

Dashboard, dark theme: an allowed link (accent) above three refused ones (custom scheme, javascript:, empty), each muted with a dotted underline.

refused link cue, dark

Dashboard, light theme, same content.

refused link cue, light

Dashboard with the visually-hidden reason forced visible (dashed outline added for the shot only): the text screen readers announce after each refused label, and the same string as the hover title.

reason revealed

Mochi chat bubble, same content: the same muted dotted cue.

mochi bubble

Related Issues

Fixes #9945

Sibling sweep

Swept: git grep -nE "children}|href ? <a" -- website/src
Sibling: website/src/components/MarkdownRenderer.tsx -- changed here
Sibling: website/src/apps/mochi/src/renderer/ChatPanelMarkdown.tsx -- changed here
Sibling: website/src/apps/md-notebook/Preview.tsx -- not affected -- notebook preview, not a chat renderer; scoped out in Not a goal

Pattern harvest

Not generalizable: the cue is a per-renderer presentation choice for one inert-label branch, not a recurring code defect.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 83b80be to 13dd5ef Compare November 2, 2026 18:11
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 0bcb99887feb056521db0afa74963ec748f31b53 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Issue #9945 is linked, and tests added here fail on base. The issue's choice between silent prose and a cue is settled by a maintainer merging or closing this PR. The PR doesn't change any default mode.

What this change ships

Inventory (10 items) — 9 justified

Intent: let a chat reader tell that a link was there and why it does nothing when the link policy refuses its destination. This is a FIX.

  1. In dashboard chat, a refused link's label now shows muted with a dotted underline — justified
  2. Hovering a refused label shows a generic reason ("Link not active…") — justified
  3. Screen-reader users hear the same reason, from ::after, and it stays out of copied text — justified
  4. Mochi chat bubbles get the same cue, with inline styles because Mochi has no dashboard stylesheet — justified
  5. A raw <a>label</a> that never had an href also gets the cue — rides along, declared, can't be told apart from a sanitizer-stripped href
  6. Named, id-only and empty anchors stay plain prose — justified
  7. New catalog key refused_link_destination in all 12 catalogs — justified
  8. New shared rule wearsRefusedLinkCue with 2 consumers (the dashboard renderer and Mochi) — justified
  9. New data-refused-link and data-refused-reason attributes on the inert span — justified
  10. frontend-conventions.md describes the cue next to the existing refused-destination contract (Chat markdown links with non-http(s) schemes (e.g. obsidian://) are rewritten to a local dashboard URL on copy #9925) — justified

[FIRST-PRINCIPLES-REVIEWED] 0bcb998

Description read

[DESCRIPTION-READ] 42fa9fd180956c44db46f5fb9e8bc297ee58a6bc2fde7b188120951465372b8a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 0bcb99887feb056521db0afa74963ec748f31b53 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The cue is small and reversible. One shared rule covers both chat renderers, and the screenshots match the description.

Notes

[DESIGN-REVIEWED] 0bcb998

Description read

[DESCRIPTION-READ] d2eceebee8c199c31d65c8b81105a516b5f3eedf9786c48aff3bc41e7c72522f

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 0bcb99887feb056521db0afa74963ec748f31b53 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The blind reader correctly took every refused label to be "a blocked link" where clicking would do "probably nothing", which is what the diff does.

Notes

  • Mochi's RefusedLinkLabel: in shot-04 the reader said the refused labels "barely stand out from ordinary text". The cue there is only var(--text-muted), which is close to the body colour, plus a dotted underline. Use a lighter muted token or a thicker dotted underline so the cue is visible.
  • refused_link_destination: the reader read "can't be opened here" as "whether it would work somewhere else, and how I'd get there". "Link disabled: this destination isn't allowed in chat." says what happened without hinting at another way in.
  • The hover title is the only reason a sighted user ever sees, and touch users never see it. Shots 1, 2 and 4 left the reader guessing what the grey means. The goal's "why it does nothing" holds only for mouse users who hover.

[UX-REVIEWED] 0bcb998

Description read

[DESCRIPTION-READ] 241dd8126d271406f9aad16f75dfc9eaf4cc53ea8d2a8f556743137bc8781098

That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 0bcb99887feb056521db0afa74963ec748f31b53 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0bcb998

Verdict parsed from the review's SHA-scoped output markers for commit 0bcb99887feb056521db0afa74963ec748f31b53.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 0bcb99887feb056521db0afa74963ec748f31b53 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 0bcb99887feb056521db0afa74963ec748f31b53 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0bcb998

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 0bcb99887feb056521db0afa74963ec748f31b53 false-positive: <reason, 20 to 500 characters>

@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 13dd5ef to 198c7a1 Compare November 2, 2026 18:37
@dodgeblaster

Copy link
Copy Markdown
Contributor Author
  • Hidden suffix misanchors document comments

fixed in 198c7a1: the dashboard reason is no longer a text node. MdAnchor renders it as an ::after pseudo-element fed from data-refused-reason (after:sr-only after:content-[attr(data-refused-reason)]), so the label's text nodes and textContent are the label alone and resolveSourcePos aligns against the source unchanged.
Regression: keeps sourcePos resolution exact for a selection after a refused link renders the finding's own trigger content with sourcePos, selects the final target, and asserts line 3, column 35; it returns undefined with the reason as a hidden text node.
The same change keeps the reason out of a copied message. resolveSourcePos itself is unchanged.

@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 198c7a1 to 4c34bf8 Compare November 2, 2026 19:53
@dodgeblaster

Copy link
Copy Markdown
Contributor Author
  • a raw named anchor that was never a link now shows the refused-link cue

fixed in 4c34bf8: both renderers gate the cue on wearsRefusedLinkCue(node) (website/src/components/markdown/refusedLinkCue.ts). An anchor carrying a non-empty name or id, or with no content, keeps the plain span with no title and no hidden reason; only a label someone was meant to follow wears the cue.
Regression: leaves named, id-only and empty anchors as plain prose without the cue in MarkdownRenderer.test.tsx (<a name="install">, <a id="top">, empty <a name="top"></a>, empty <a></a>) and in mochiRefusedLinkAnchor.test.tsx; both fail with the helper forced to true.

@dodgeblaster
dodgeblaster marked this pull request as ready for review November 2, 2026 21:51
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners November 2, 2026 21:51
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 2, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (product decision) at 4c34bf8.

The code looks sound. A refused destination still never becomes an anchor. The reason is kept out of the label's text nodes, so sourcePos and copy are unaffected (MarkdownRenderer.tsx#L325-L338). Named, id-only and empty anchors keep the plain span. Both earlier GPT and Opus findings were fixed with regression tests, and CI is green.

Blocker: #9945 is labelled needs-human and explicitly leaves "cue or silent prose" to a maintainer. The PR itself calls this the concrete form of the cue option, and Design Review asks for that decision before merge. A maintainer's ruling on #9945, or on this PR, in favour of the cue clears this.

AI findings judged non-blocking:

  • First Principles: a raw <a>label</a> also gets the cue. The renderer cannot tell it apart from a deleted href, and the PR documents the trade. refusedLinkCue.ts
  • UX: Mochi's muted shade is close to body text. This is a contrast refinement, and the title and hidden reason still carry the meaning. ChatPanelMarkdown.tsx#L195-L208

— crew-pr-reviewer (r142)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 3, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 4c34bf8 to 8ec5c39 Compare November 6, 2026 18:15
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main 35a1f00; resolved conflicts in website/src/test/MarkdownRenderer.test.tsx (import block only: kept main's new hostRelay import alongside this PR's i18nT / resolveSourcePos imports), kept main's changes. The rebased diff is line-for-line identical to the previous head 4c34bf8 (same 19 files, +225/-1). Re-ran locally green: npm run build; vitest MarkdownRenderer.test.tsx, mochiRefusedLinkAnchor.test.tsx, MarkdownRenderer.textPasses.test.tsx, catalogParity.test.ts, changedValueQa.test.ts (242 tests); brand and comment-history gates.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 6, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 8ec5c39 to 5dd2316 Compare November 6, 2026 20:21
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main 39717a0 to pick up #31625 (security package line budget), which fixes the inherited test_the_package_stays_within_its_line_budget red on Backend Tests shard 2. No conflicts; kept main's changes. The diff is still the same 19 files, identical to the previous head. Re-ran locally green: npm run build; vitest MarkdownRenderer.test.tsx, mochiRefusedLinkAnchor.test.tsx, MarkdownRenderer.textPasses.test.tsx, catalogParity.test.ts, changedValueQa.test.ts (242 tests); brand and comment-history gates.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
A chat link whose destination the link policy refuses rendered as plain
prose, indistinguishable from the sentence around it. Both chat renderers
(MdAnchor and Mochi's ChatPanelMarkdown) now give the inert label a muted
dotted underline from existing tokens, plus a generic translated reason as
the hover title and as a visually-hidden suffix. Allowed links are
unchanged and the label is still never an anchor.

Fixes #9945
@dodgeblaster
dodgeblaster force-pushed the fix/9945-refused-link-cue branch from 5dd2316 to 0bcb998 Compare November 6, 2026 21:53
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main 7c364bc to pick up #31803, which fixes the test_pull_request_target_allowlist red that main inherited from #31396 (Backend Tests (Windows) 7). No conflicts; kept main's changes. The diff is still the same 19 files, identical to the previous head. The fresh head also re-runs the AI review lanes that failed closed on the installation rate limit, and the Pod Boot Canary (Windows) timeout. Re-ran locally green: npm run build; vitest MarkdownRenderer.test.tsx, mochiRefusedLinkAnchor.test.tsx, MarkdownRenderer.textPasses.test.tsx, catalogParity.test.ts, changedValueQa.test.ts (242 tests); brand and comment-history gates.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving head 0bcb998. The gate shows 97 checks passed, none red or pending.

What I checked:

  • One decision for both renderers. wearsRefusedLinkCue returns false for a raw in-page target (name or id set) or an anchor with no children, and both MdAnchor and Mochi's ChatPanelMarkdown branch on it. The tests cover the '' sentinel, sanitizer-deleted javascript:/data: hrefs, [label]() and a bare <a>, plus the plain-prose cases.
  • The label text stays the source text. In MdAnchor the reason is ::after content fed from data-refused-reason, not a text node, and the new resolveSourcePos test pins that a selection after a refused link still maps to line 3, column 35. Mochi has no stylesheet for that, so it uses an unselectable visually-hidden span, which keeps copy clean there too.
  • Nothing leaks. The reason is one generic string, and the tests assert the refused destination never appears in the rendered HTML.
  • i18n. refused_link_destination is added to every locale file in the diff, en-XA included.

A small visual change that adds no new restriction. The convention note in frontend-conventions.md matches the code.

@bolichen97
bolichen97 merged commit 0975050 into main Nov 7, 2026
152 of 159 checks passed
@bolichen97
bolichen97 deleted the fix/9945-refused-link-cue branch November 7, 2026 06:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray pushed a commit that referenced this pull request Nov 9, 2026
A chat link whose destination the link policy refuses rendered as plain
prose, indistinguishable from the sentence around it. Both chat renderers
(MdAnchor and Mochi's ChatPanelMarkdown) now give the inert label a muted
dotted underline from existing tokens, plus a generic translated reason as
the hover title and as a visually-hidden suffix. Allowed links are
unchanged and the label is still never an anchor.

Fixes #9945

(cherry picked from commit 0975050)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Consider a visual cue when a chat link's destination is refused (follow-up to #9925)

3 participants