# Browser and Playground

## Browser-Compatible Execution

Kedi parsing/compilation can remain on a Python backend while embedded Python
and model inference are delegated through bridges. This avoids pretending the
entire Python runtime or provider SDK runs natively in the browser.

## Pyodide Executor

```python
from kedi.executors import PyodideExecutor

executor = PyodideExecutor(bridge, timeout=60)
runtime = compile_program(program, executor=executor)
```

`PyodideExecutor` subclasses `PlaygroundExecutor`. Its synchronous bridge
receives operation, code, referenced environment values, synchronization names,
and source offset; it returns result, environment updates, stdout, or an error.

## Supported Language Surface

Inline expressions, Python blocks, side effects, preludes, and type expressions
are forwarded. JSON-compatible values cross by value. Worker-owned unsupported
objects cross as opaque `PlaygroundReference` handles when the bridge supports
them.

Only names referenced by the Python code are serialized, reducing bridge
traffic. Existing Kedi variables are synchronized back after side effects.

## Browser Model Bridge

`WebGPUAdapter` sends prompts, JSON Schema, settings, and iterative tool calls
through a `BrowserModelBridge`. It supports structured output, scoped tools,
profile/model/effort/settings overrides, and optionally selected MCP
transports.

It is not registered as a normal DSL shortname; construct and pass the adapter
instance from Python.

## Interactive Example

The repository's `examples/webgpu_kedi_demo` runs a GGUF model with wllama/
WebGPU in a browser worker while the Python server executes Kedi:

```bash
python examples/webgpu_kedi_demo/server.py
```

Open `http://127.0.0.1:8787`. The demo supports Hugging Face download, a local
server model, or browser file selection.

## Runtime Isolation

A bridge is an execution boundary, not automatically a security boundary.
Security depends on the worker runtime, exposed operations, serialization
policy, server endpoints, and browser origin controls.

The demo's Env Manager stores values in browser `localStorage`. `HF_TOKEN` may
be sent for model downloads; other displayed BYOK fields are currently stored
but not wired into adapters.

## Browser Limitations

- Browser model quality and structured/tool reliability depend on the loaded
  GGUF model.
- Response caching is disabled in the demo.
- Model files are excluded from Docker images.
- The demo adapter/HTTP polling bridge is a proof of integration, not a
  production multi-user service.
- Debug/stdout and opaque references need explicit lifecycle handling.