39 lines
2.2 KiB
Markdown
39 lines
2.2 KiB
Markdown
|
# Runtime API And Parity
|
||
|
|
|
||
|
|
## Extending `RuntimeAPIs`
|
||
|
|
|
||
|
|
1. Add or extend the shared interface in `packages/ui/src/lib/api/types.ts`.
|
||
|
|
2. Implement web behavior under `packages/web/src/api/*` and compose it in `packages/web/src/api/index.ts`.
|
||
|
|
3. Implement VS Code webview behavior under `packages/vscode/webview/api/*`.
|
||
|
|
4. Add extension-host bridge handlers when filesystem, git, settings, or manager access is required.
|
||
|
|
5. Keep Electron shared through the web runtime unless behavior is inherently native.
|
||
|
|
6. Register APIs through app entrypoints and consume via `RuntimeAPIProvider` hooks.
|
||
|
|
|
||
|
|
React components use `useRuntimeAPIs()` or `useRuntimeAPI()`. Non-React modules use `getRegisteredRuntimeAPIs()` only when hooks are impossible. Do not introduce direct reads of `window.__OPENCHAMBER_RUNTIME_APIS__` in feature code.
|
||
|
|
|
||
|
|
## VS Code Route Decisions
|
||
|
|
|
||
|
|
| Route type | VS Code behavior |
|
||
|
|
|---|---|
|
||
|
|
| OpenChamber local route | Handle in the webview and bridge to extension host when needed |
|
||
|
|
| Official OpenCode route | Forward through the generic OpenCode proxy |
|
||
|
|
| SSE | Use the dedicated SSE bridge, never generic proxy |
|
||
|
|
| Session message POST | Use the dedicated session-message path |
|
||
|
|
| Unsupported native feature | Return stable explicit unsupported behavior, normally 501 JSON |
|
||
|
|
|
||
|
|
Register explicit OpenChamber handling before generic proxy fallback. Silent empty fallback is not parity.
|
||
|
|
|
||
|
|
## Electron Boundary
|
||
|
|
|
||
|
|
Electron normally reuses the web runtime/server implementation. Keep privileged shell behavior behind main/preload IPC and local-page gates.
|
||
|
|
|
||
|
|
- API base and shell identity may be broadly available for routing.
|
||
|
|
- Client tokens, home paths, filesystem/shell access, and privileged IPC remain local-page gated.
|
||
|
|
- Do not trust arbitrary loopback, `file://`, or `about:blank` origins as packaged UI.
|
||
|
|
- Remote pages and preview iframes must not gain local host privileges.
|
||
|
|
- Deep links that import hosts, store credentials, or switch runtimes require explicit in-app confirmation before mutation.
|
||
|
|
|
||
|
|
## Shared Contract Rule
|
||
|
|
|
||
|
|
For every shared capability, decide web, Electron, VS Code, hosted-mobile, and Capacitor behavior explicitly. A stable unsupported response is acceptable; accidental fallthrough is not.
|