Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions typescript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,46 @@ bun examples/progress.tsx # a flow surface with a running card
bun examples/chat.tsx # an inline surface with an editor in the dock
```

### Native local-file links

`local-links.ts` compares Markdown destinations with native span `href`s,
without omp, a model call or a Markdown rewriter. Run it in a Tern pane:

```sh
bun examples/local-links.ts # use the example's own source file
bun examples/local-links.ts "/path/to/report.html"
```

The target must be an existing local file. The example requires a native TSP
connection and fails outside Tern instead of treating plain-text output as a
rendering check. It does not open any destination automatically.

Observed on macOS arm64 with Tern `0.8.3 (e2b8656)`:

- The Markdown `file://` destination becomes plain text, with no `a` element.
- The encoded absolute path, relative path and HTTPS Markdown controls produce
`a` elements.
- Both native span controls produce `span.sf-link`, including the unchanged
`file://` URL used in the first Markdown row.

This also reproduces with a non-HTML target. The difference is in Tern's
Markdown link rendering, not HTML page loading or SDK URL rewriting. See
[tern-sdk#19](https://github.com/stencil-hq/tern-sdk/issues/19). This example
documents the behavior; it does not fix the renderer or close that issue.

For an affected native Markdown renderer, using the encoded absolute local
path as the destination is a client-side workaround. Keep percent-encoded
filename bytes intact (`%20` for spaces, `%23` for a literal `#`); keep the
original file URL for native spans and OSC 8 hyperlinks. Resolve relative
paths against the intended session directory before constructing the target.
Do not replace `file://` throughout Markdown source or change other URL schemes.
The path controls here use the local file URL's `pathname`; Windows/UNC,
remote hosts and fragment navigation have not been verified.

To inspect what the SDK actually sent, set `TERN_TSP_RECORD` to a local JSONL
file before running the example. The recording retains the original Markdown
`file://` destination, so it can distinguish client output from rendering.

## Development

```sh
Expand Down
27 changes: 27 additions & 0 deletions typescript/examples/local-links.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/** Compare native Markdown and span links without an agent or a Markdown rewriter. */
import { statSync } from 'node:fs';
import { relative, resolve, sep } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { connect, span, ui } from '@stencil-hq/tern';

const file = resolve(process.argv[2] ?? fileURLToPath(import.meta.url));
if (!statSync(file).isFile()) throw new Error(`Expected a local file: ${file}`);
const fileUrl = pathToFileURL(file);
const absoluteTarget = fileUrl.pathname;
const relativeTarget = relative(process.cwd(), file).split(sep).map(encodeURIComponent).join('/');

await using session = await connect({ app: 'local-links' });
if (!session) throw new Error('Run this example in a Tern terminal pane with TSP enabled.');
const surface = session.open({ mode: 'flow', listen: false });
surface.render(
ui.col(
ui.text(`Local file: ${file}`),
ui.md(`[Markdown file URL](<${fileUrl.href}>)`),
ui.md(`[Markdown absolute path](<${absoluteTarget}>)`),
ui.md(`[Markdown relative path](<${relativeTarget}>)`),
ui.md('[Markdown HTTPS](https://example.com/)'),
ui.text(span('Native span file URL', undefined, { href: fileUrl.href })),
ui.text(span('Native span absolute path', undefined, { href: absoluteTarget }))
)
);
await surface.close({ keep: true });