Playground Specification

Purpose

The playground gives you a reference editor for ArchLex source. It combines Monaco, live diagnostics, a rendered SVG preview, provider examples, settings, and export tools in one browser application.

Layout and examples

Desktop screens use a resizable editor and preview split. Narrow screens use Editor and Preview tabs. The command bar exposes examples, direction, validation, theme, documentation, import, export, and fullscreen controls.

“Explore examples” opens a searchable architecture library. Filter by provider (AWS, Cloudflare, Google Cloud, or Kubernetes) and use case, or search titles, descriptions, and services. Selecting an entry renders a diagram preview without changing the editor; Load example replaces the current editor contents. The dialog fits its content with a bounded scrolling results area. Desktop shows the preview beside results only after selecting an example. On mobile, select a result to open its preview and use Back to examples to return. Escape closes the dialog. Cloudflare examples cover a Workers and R2 application, a public edge to AWS, a Tunnel into Kubernetes on GCP, and AWS/GCP origin steering. Kubernetes examples cover microservices ingress, stateful storage, scheduled batch work, autoscaling and disruption protection, and namespace RBAC.

Language support

Monaco highlights directives, scope keywords, relationships, comments, and provider resources.

The editor provides context-aware completions backed by the language service:

• Catalog-driven suggestions: AWS, Cloudflare, Google Cloud, and Kubernetes resources, with relationships and containment rules
• Human-readable search: Type “elastic kubernetes” to find Amazon EKS, or “relational” for RDS and Aurora
• Grammar-aware filtering: Different suggestions after : (resource kinds), [ (relationships), or in directive positions
• Symbol visibility: Declared identifiers appear as relationship targets
• Semantic ranking: Results ordered by prefix match, search relevance, and relationship compatibility
• Canonical insertion: Always inserts lowercase kebab-case syntax (eks, cloud-run, statefulset)

Completions trigger automatically on :, ., [, - or manually with Ctrl+Space. The suggestion widget shows human-readable display names (e.g., “Amazon EKS”) while inserting canonical syntax (e.g., eks).

Kubernetes support includes cluster, namespace, and resource aliases such as deploy, svc, and pvc.

The editor shows parse, structural, and provider diagnostics at their source spans. Code actions can apply supported remediation edits. Hover documentation provides directive and service descriptions.

Progressive rendering

Source and setting changes debounce before rendering. Each operation prepares the source once, starts the base render, and loads missing provider icons in parallel.

The playground displays the base SVG as soon as layout finishes. The status bar shows Ready with base render duration while a separate Loading icons… message tracks hydration. When icon loading finishes, renderPrepared() reuses cached geometry and replaces only the SVG artwork.

Each operation owns an AbortController and operation ID. A stale base render or icon hydration result cannot replace newer output. An icon failure keeps the base diagram and clears the loading state.

Selection and persistence

SVG selection uses data-archlex-id and ElementMapping to reveal source. Cursor movement highlights the narrowest mapped element. Selection styling does not enter exported SVG.

Opening /?code= hydrates the editor from the URL-encoded ArchLex source. MCP playground_url values use this query. A present code parameter wins over versioned local state. Without code, the playground restores the last persisted source, or the first bundled example.

Versioned local state stores source, example or custom mode, explicit settings, theme, and pane sizes. Invalid JSON and unsupported versions fall back to the default source and layout.

Import and export

You can import source from a file or URL. Copy and download actions use the latest successful SVG. PNG export rasterizes that SVG. Exported output includes theme and accessibility data but excludes playground selection state.

Sharing

Share creates a public link for the current source and opens a dialog with two copy options: the playground link and a Markdown embed containing the SVG image and playground link. A share is created before either option is copied, so you can choose the format that fits where you are sharing it.

Accessibility

Keyboard users can reach controls, resize panes, switch narrow-screen tabs, and navigate SVG elements. Stationary pointer clicks select SVG elements; drag gestures capture the pointer for panning. Uncaptured presses are canceled when they leave the viewport, so returning after an outside release cannot pan the diagram. Fullscreen entry focuses its exit control even when the first diagram arrives after entry. Focus survives hydrated SVG replacement. Diagnostic counts use live announcements without replaying the full list after each edit.

Browser verification targets

pnpm test:browser builds and tests the local playground, including endpoint smoke checks. To test an existing deployment explicitly, set PLAYGROUND_URL:

PLAYGROUND_URL=https://playground.archlex.dev pnpm test:browser tests/browser/deployed-playground.spec.mjs

Endpoint smoke tests operate the rendered Monaco editor with keyboard paste; the hidden native input is not a textarea. Local runs use deterministic icon fixtures. Explicit deployment runs retain the deployed endpoint’s real artwork requests and do not publish or deploy changes.