Introduce host-specific capability overrides

[manzt]

Positron is built on Code OSS, the open-source core of VS Code, so most of the marimo extension can work there without changes. Positron also adds data-science-specific APIs that can provide a better execution path for some behaviors. For example, positron.window.previewUrl can show documentation in the Positron Viewer instead of using our existing external-browser path.

Checking for Positron at each call site would spread host-specific branches throughout the extension. That would couple otherwise general features to one editor, repeat capability detection, and make each integration harder to test or replace. We instead want to add these enhancements incrementally while keeping the rest of the extension independent of the host.

The proposed foundation moves a host behavior behind a narrow Effect service with a VS Code default, e.g.:

export class WebPreview extends Effect.Service<WebPreview>()("WebPreview", {
  effect: Effect.gen(function* () {
    const code = yield* VsCode;
    return {
      open: Effect.fn("WebPreview.open")(function* (url: string) {
        const uri = yield* code.utils.parseUri(url);
        yield* code.env.openExternal(uri);
      }),
    };
  }),
}) {}

An Effect service can be read here as an injectable interface with a default implementation. Feature code depends on the capability rather than the editor providing it.

At the top level, HostPlatform detects Positron once and substitutes only the implementations for which Positron has a preferred path:

const positron = tryAcquirePositronApi();
return positron
  ? makePositronAdapter(positron)
  : WebPreview.Default;

The rest of the extension can then prefer the shared capability without checking the host:

const preview = yield* WebPreview;
yield* preview.open(url);

Because the base implementations use VS Code APIs, they should continue to work across compatible Code OSS-based editors. Positron, or another compatible host, can selectively replace capabilities where it offers a better experience. This spike implements only web preview so that we can evaluate and communicate the pattern before committing to broader integrations.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[github-actions]

Coverage Report

Area	Lines	Branches	Functions
Python	74.52% (1491 / 1923)	60.98% (261 / 428)	—
TypeScript	60.82% (3813 / 6269)	49.34% (1497 / 3034)	59.34% (1118 / 1884)

_{TypeScript statements: 60.04% (3974 / 6618)}

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>