Skip to content

docs(typescript): add a standalone native local-link diagnostic - #65

Open
Zixiaobowen wants to merge 1 commit into
stencil-hq:mainfrom
Zixiaobowen:docs/native-markdown-file-links
Open

Zixiaobowen wants to merge 1 commit into
stencil-hq:mainfrom
Zixiaobowen:docs/native-markdown-file-links

Conversation

@Zixiaobowen

@Zixiaobowen Zixiaobowen commented Oct 15, 2026 •

Copy link
Copy Markdown

Summary

Add a standalone TypeScript example and documentation for the local-file link behavior reported in #19.

The example uses only this repository's SDK: no omp, agent session, model call, plugin, Markdown rewrite, or automatic navigation. This is a reproduction/documentation contribution, not a renderer fix, and it should not close #19.

Reproduce

Run in a Tern terminal pane from typescript/:

bun examples/local-links.ts
# Optionally use an existing HTML report, including spaces or a literal # in its name:
bun examples/local-links.ts "/path/to/report #.html"

The default target is the example's own existing .ts file. The example requires a native TSP connection; it explicitly errors if TSP is unavailable rather than accepting a plain-text rendering as proof.

Set TERN_TSP_RECORD to a local JSONL file to inspect the SDK's actual messages.

Observed behavior

Verified with Tern 0.8.3 (e2b8656) on macOS arm64, using the real SDK program in an isolated tern serve native renderer. The rendered element tree and screenshot were inspected.

Input Rendered result
Markdown link to a file:///… URL Label only; no a element
Markdown link to the same encoded absolute path a
Markdown link to a relative path a
Markdown HTTPS link a
Native text span with the same file:///… href span.sf-link
Native text span with the encoded absolute path span.sf-link

The wire recording contains the original file:///… destination in the Markdown node, unchanged. The native span uses that same URL and does produce a link. This independently isolates the difference to Tern's native Markdown rendering rather than omp or SDK URL rewriting. Both the default non-HTML file and an existing HTML file with spaces and a literal # in its name reproduced it.

Handling notes

On the affected native Markdown renderer, an encoded absolute local path can be used as a destination-side workaround after resolving the intended session directory. Preserve encoded filename bytes (%20, %23) and leave the original file URL unchanged for native spans and OSC 8 hyperlinks. Do not blindly replace strings throughout Markdown source or alter unrelated URL schemes.

The local omp workaround that prompted this contribution changes only its native Markdown destinations after session-relative resolution; it does not repair Tern's renderer. This PR does not change SDK serialization, the renderer's URL policy, or plugin routing. Windows/UNC paths, remote hosts and fragment navigation have not been verified.

Checks

  • bun run typecheck in typescript/: passed.
  • Executed the submitted example in Tern's native renderer with its default .ts target and a boundary-name .html target; inspected actual rendered links and TSP messages.
  • TERN_TSP=0 bun examples/local-links.ts: expected native-only error and exit status 1 observed.
  • git diff --check: passed.

No full multi-language test suites or build were run; no library implementation changed. The native-renderer checks above establish link generation, not GUI click/navigation success.

Related: #19.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

@Zixiaobowen

Copy link
Copy Markdown
Author

anyone here?

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.

Markdown in the omp Reader and Carly drops file:// links

1 participant