Inside the Interactive Demo Sandbox

The playground processes user code in three phases:

1. Type Generation — Python server code is parsed client-side (regex-based) to extract @model class fields and @rpc function signatures, then converted to TypeScript declarations.
2. Monaco Integration — The generated types are injected into Monaco Editor as virtual files at /node_modules/@pyrpc/types/index.d.ts, enabling real-time autocomplete and type errors on client.* calls.
3. Sandbox Execution — When the user clicks Run, client calls are extracted via regex, dispatched to a local API endpoint that parses the server code to construct mock return values, and the results are fed through a simulated console.log.

The type pipeline lives in docs/lib/parsePythonTypes.ts. Three functions form the core:

• parseServerCode(code) — Uses regex to find @model classes and @rpc functions. Extracts field names and types for models, parameter names/types and return type for procedures.
• introspectionToTypes(schema) — Converts the parsed schema into TypeScript declaration strings. Python types like int become number, list[X] becomes X[], model names reference the generated interfaces.
• validateServerCode(code) — Detects unknown decorators (e.g. @procedure), missing return type annotations, and empty model classes.

The output is a TypeScript source string containing export interface User { ... } and export interface Types { get_user(id: number): Promise<User>; ... }.

The critical design decision was how to feed these types into Monaco so that TypeScript's compiler can see them. Monaco provides setExtraLibs for declaring ambient types, but we found that files added via setExtraLibs are not visible to TypeScript's module resolution — import type { Types } from "@pyrpc/types" would fail to resolve.

The solution: use monaco.editor.createModel() to create actual editor models at the exact file paths TypeScript expects:

• /node_modules/@pyrpc/types/index.d.ts — Generated type declarations (updated live as server code changes)
• /node_modules/@pyrpc/client/index.d.ts — Static client SDK stubs (createClient, PyRPCClient, etc.)

The client editor model is set with path="/model.ts" so that TypeScript's NodeJs module resolution finds the /node_modules/... models. After updating the types model, a no-op edit (pushEditOperations) forces the TypeScript worker to re-evaluate the program, updating diagnostics and completion data immediately — at compile time, not after clicking Run.

The Omit<PyRPCClient, 'rpc'> type in the stubs hides the internal .rpc property from autocomplete, so client. shows only user-defined methods.

When the user clicks Run, the playground:

1. Extracts client calls — parseClientCalls uses a global matchAll regex to find every client.method(...) call in the client code.
2. Dispatches to mock API — A lightweight proxy (createSandboxClient) sends each call as a POST to /api/sandbox/rpc with the server code in a header.
3. Parses server code — The mock endpoint re-parses the @rpc function signatures and @model fields, then builds mock return values:

• For model return types: creates an object with default-typed fields (e.g., str becomes "Sample fieldName"), overrides with matching parameter values, then overrides with return value literals parsed from the function body (e.g. return User(id=id, name="Core User") sets name to "Core User").
• For primitive return types: returns sensible defaults (int = 42, str = "mock_result", any = computed from input).

Finally, simulateConsoleLogs processes each console.log(...) call — supporting template literals (Hello ${name}), typeof() expressions, dot-path resolution (user.name), and proper handling of nested parentheses — and displays the output in a theme-aware terminal.

The server editor validates code on every keystroke via a useEffect that calls validateServerCode. Detected issues are surfaced as Monaco error markers (red underlines) and also block the Start Server button:

• Unknown decorators — Any @name that isn't @rpc or @model triggers an error.
• Missing return type — @rpc def foo() without a return type annotation is flagged.
• Empty model — A @model class with no typed fields is flagged.

This validation mirrors what pyrpc-core would enforce at runtime, but shifted to edit-time for immediate feedback.

The sandbox simulates pyrpc's behaviour, but there are fundamental differences between the demo and the real framework:

Type System

Execution Model

Protocol & Error Handling

Client SDK