---
id: AGD-0055
ticket: pbs-lsp-document-links
title: PBS LSP Document Links
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, document-links, imports]
---

## Pain

Domain owner: `studio/lsp`

PBS import/module references and asset-like surfaces are plain text in VS Code, so users cannot click through to imported modules or related project resources.

## Context

The compiler understands module references and project files. The LSP does not announce documentLinkProvider, and the VS Code extension delegates all language behavior to the server.

## Open Questions

- [ ] Which references should become document links first: imports, barrels, stdlib modules, assets/addressables, or docs?
- [ ] How should virtual or stdlib resources be represented as link targets?
- [ ] Should document links overlap with go-to-definition or remain a separate lightweight navigation feature?

## Options

### Option A - Import/module links only

- **Approach:** Expose `documentLink` for module references such as `@sdk:gfx` and barrel paths.
- **Pro:** Narrow, useful, and mostly aligned with existing module resolution.
- **Con:** Does not cover assets/addressables or documentation links.
- **Maintainability:** Strong first wave.

### Option B - General resource links

- **Approach:** Link imports, stdlib modules, assets, addressables, and possibly documentation/resource surfaces.
- **Pro:** Richer navigation across project resources.
- **Con:** Requires resource-specific target policy and may overlap with definition.
- **Maintainability:** Good only after resource ownership is defined.

## Tradeoffs

Document links should remain lightweight. If a link requires semantic identity and symbol resolution, it may belong in go-to-definition instead.

## Recommendation

Prefer Option A first: imports and module references only.

## Discussion

Coordinate stdlib target handling with go-to-definition.

## Resolution

Ainda em aberto.

## Next Step

Decide first-wave link targets and how stdlib/module URIs are represented.