Transports

What ships

Selector behaviour

selectTransport(config) tries them in fixed order:

1. dartc if config.transport.dartc is set. Wait for the data channel to open.
2. fallback if config.transport.fallback is set and navigator.gpu exists. Returned unprepared — the host must call prepare() on a user gesture.
3. direct if config.transport.direct is set.

config.transport.preferred = […] from pod.toml is parsed but not yet honoured by the selector — it's advisory metadata today.

The selector throws if none succeed; the trace of failures is on runtime.transport.trace.

Inspecting the active transport

runtime.transport.status;          // "idle" | "connecting" | "ready" | "error" | "destroyed"
runtime.transport.name;            // "dartc" | "fallback" | "direct"
runtime.transport.trace;           // string[] of attempts that failed
runtime.transport.error;           // last error message
runtime.transport.dartcEvents;    // stage events from the WebRTC ladder
runtime.getTransport();            // the live Transport instance

For a compact one-liner snapshot suitable for status badges or logs:

import { quickTransportStatus } from "@gemmapod/embed/runtime";

console.log(quickTransportStatus(runtime));
// { phase: "ready", transportName: "dartc", detail: "via dartc" }

(quickTransportStatus is also exposed on the IIFE global as GemmaPod.quickTransportStatus.)

attachBrowserFallbackPrepare

If you want the WebGPU fallback panel rendered into a specific DOM node without using mountPod's fallbackUi: "default":

import { attachBrowserFallbackPrepare } from "@gemmapod/embed/runtime";

const unmount = attachBrowserFallbackPrepare(myEl, runtime);
// later
unmount();

The panel handles model picker, cache state, WebGPU availability, and the explicit prepare button. See in-browser fallback guide for the UX.

Direct access to the FallbackTransport

For a fully custom prepare UI:

import { FallbackTransport } from "@gemmapod/shim";

const t = runtime.getTransport();
if (t instanceof FallbackTransport) {
  await t.prepare((progress) => updateProgressBar(progress));
}

prepare(), abort(), setModel(), cacheStatus() are the lower-level hooks the default panel uses internally.

See also

• In-browser fallback guide
• Architecture — transport selection
• DARTC envelope