WebContainer Failure Triage

Overview

This skill follows a deterministic diagnosis order: browser capability, served headers, lifecycle ownership, runtime events, process exit, dependency compatibility, and preview behavior. It avoids speculative retries and unsafe header weakening.

Prerequisites

• A reproducible URL or local command and the affected browser/version
• Permission to inspect application code, response headers, and bounded browser/runtime logs
• A synthetic reproduction when the failing project contains sensitive data

Tool Discipline

Use Read, Glob, and Grep to find boot calls, headers, runtime events, process handling, and dependency manifests. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only after the failing layer is identified; never retrieve secrets or full user projects for diagnosis.

Current Contract

• A SharedArrayBuffer or crossOriginIsolated failure starts with the actual HTML response's COOP/COEP headers, including 304 behavior.
• A released proxy or duplicate-start failure requires proving whether boot() ran more than once, including under HMR.
• Dependency installs should preserve exit code and bounded output; a lockfile can improve repeatability and startup time.
• Native Node addons are unavailable unless an alternative is implemented in JavaScript or WebAssembly.
• Browser privacy controls can block required Service Worker or third-party storage behavior.
• Preview failures are investigated through process exit plus error, port, and server-ready events.

Authentication

Redact API keys, registry tokens, OAuth details, cookies, source contents, and dynamic preview URLs from shared evidence. For private-package failures, report auth state and package identity without printing credential values.

Workflow

1. Reproduce with the smallest synthetic project and record browser, URL, secure-context, and isolation state.
2. Inspect the final document headers and cached response behavior.
3. Count boot paths and trace HMR, navigation, and teardown ownership.
4. Capture bounded runtime events, spawned command, exit code, and the final useful output lines.
5. Compare the dependency with documented WebContainer constraints, especially native addons and install behavior.
6. Apply one layer-specific fix, repeat the reproduction, and record rollback plus remaining browser variance.

Approval Boundaries

Do not disable browser security, relax COOP/COEP or CSP broadly, clear user browser data, replace dependencies, or change production hosting without explicit authorization. Present the failing layer …

Custom WebContainer Experience Architecture

Overview

This skill converts an IDE-like feature request into a bounded architecture. It keeps the host UI, virtual filesystem, editor models, terminal streams, runtime processes, preview frames, and persistence strategy separate so a prototype does not accidentally become an unsafe monolith.

Prerequisites

• Named user journeys and a target browser application
• A decision that a custom WebContainer experience is preferable to a StackBlitz SDK embed
• Product, licensing, security, and persistence owners for production use

Tool Discipline

Use Read, Glob, and Grep to map the host framework, editor and terminal libraries, application state, persistence, and runtime boundary. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only for a user-approved bounded slice.

Current Contract

• The host application owns a single lifecycle adapter; individual panes do not call boot() or teardown().
• File explorer paths are validated and normalized before virtual-filesystem operations; editor models use stable canonical paths.
• Terminal input/output is explicitly bound to one process and released on disposal.
• Preview URLs come from runtime events and are treated as untrusted application content, not trusted host UI.
• The WebContainer filesystem is not a persistence guarantee. Define an explicit save/export/versioning path before claiming durable work.
• Register error, port, and server readiness observers with bounded logging and unsubscribe ownership.

Authentication

Do not mount host secrets, auth tokens, customer .env files, or ambient browser credentials into user-controlled projects. If private packages are required, use the documented organization auth boundary and disclose which project code can access installed material.

Workflow

1. Define the smallest user journey and decide which panes and runtime capabilities it truly needs.
2. Draw ownership for host state, lifecycle adapter, filesystem, editor models, process/terminal handles, preview, and persistence.
3. Establish a typed message/event contract between panes instead of sharing raw runtime globals.
4. Implement one vertical slice: open a synthetic file, edit it, write it, run a bounded command, and display the emitted preview URL.
5. Add path-policy, process-cancellation, preview isolation, save/export, and permanent-disposal behavior.
6. Verify keyboard/accessibility behavior, HMR ownership, memory cleanup, and recovery from failed startup before expanding features.

Approval Boundaries

Require explicit approval before executing arbitrary user code, persisting o…

StackBlitz Embed Integration

Overview

This skill selects and implements the supported SDK method for an existing StackBlitz project, a public GitHub path, or an inline project. It treats the embed as third-party executable content with explicit loading, persistence, accessibility, and browser-support boundaries.

Prerequisites

• A named host page and the source of the project to embed
• Confirmation that source code is public and safe to send to or execute through StackBlitz
• A static fallback and intended responsive behavior

Tool Discipline

Use Read, Glob, and Grep to inspect the host component, content source, CSP, existing third-party scripts, and responsive patterns. Use WebFetch only for current official StackBlitz documentation. Use Write or Edit after the embed source and trust boundary are confirmed.

Current Contract

• Use embedProjectId for an existing StackBlitz project, embedGithubProject for a public GitHub repository/path, and embedProject for a generated inline project.
• Inline projects live in browser memory unless a user forks them into a StackBlitz account; do not promise automatic persistence.
• Use current EmbedOptions; do not depend on deprecated forceEmbedLayout behavior.
• clickToLoad is a useful consent/performance boundary for expensive or numerous embeds.
• Treat the returned VM instance as an integration capability with an explicit owner and disposal path.
• WebContainer-based embeds have stricter browser constraints than static code fallbacks.

Authentication

Do not embed private repositories, secrets, licensed source, or authenticated application state through a public project method. If enterprise origin or private access is required, stop and obtain the documented organization configuration and security approval.

Workflow

1. Inspect the host page, choose the authoritative project source, and classify its sensitivity.
2. Select one SDK method and a pinned SDK version from the repository lockfile.
3. Define height, view, theme, openFile, and clickToLoad from the user journey; avoid deprecated options.
4. Add a titled container, loading state, error state, and accessible static link or code fallback.
5. Reconcile CSP, privacy disclosure, responsive layout, and browser support with the site owner.
6. Test initial load, user-triggered load, failure, keyboard flow, narrow viewport, and navigation cleanup.

Approval Boundaries

Require explicit authorization before adding a third-party executable embed, changing CSP, loading private code, selecting an enterprise origin, or adding analytics. Show the data/source flow an…

Privacy-Safe WebContainer Diagnostic Bundle

Overview

This skill defines or implements a bounded diagnostic artifact for WebContainer problems. The bundle records state and outcomes, not arbitrary source, environment values, complete terminal output, browser history, cookies, or credential material.

Prerequisites

• A named incident or reproducible failure and an approved output location
• Agreement on who may receive the bundle and how long it may be retained
• Permission to inspect the relevant host configuration and bounded runtime evidence

Tool Discipline

Use Read, Glob, and Grep to locate existing logging, header, boot, event, and process instrumentation. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write for a new approved bundle schema or artifact and Edit for narrow instrumentation changes.

Current Contract

• Record a schema version, capture time, application release, package versions, coarse browser family/version, secure-context state, and crossOriginIsolated boolean.
• Record the presence and normalized values of relevant response headers without unrelated headers or cookies.
• Record lifecycle transitions, event names, process command identity, exit code, duration, and a bounded/redacted output tail.
• Record only filesystem counts and tested synthetic paths; do not enumerate or copy user file contents.
• Record resource symptoms such as out-of-memory errors without inventing a universal numeric memory quota.
• Make every redaction and omitted evidence class visible in the bundle metadata.

Authentication

Never include API-key values, OAuth parameters, registry credentials, cookies, URLs carrying tokens, .env content, private package metadata beyond the minimum identity, or full user-agent/client fingerprint data. Record auth state as a coarse enum when relevant.

Workflow

1. Define the incident ID, audience, retention, schema, byte cap, and redaction rules.
2. Collect static package and hosting configuration from repository evidence.
3. Collect browser capability, served-header, and lifecycle state from the failing session.
4. Add bounded event and process evidence, preserving exit codes and timestamps.
5. Apply automatic redaction, then perform a human review before sharing.
6. Reproduce once with a synthetic fixture and attach the bundle hash plus collection limitations.

Approval Boundaries

Require explicit authorization before adding runtime telemetry, persisting a bundle, collecting user-session evidence, or sending the artifact outside the approved audience. A human must review the final bytes before external disclosure.

Output

Return the schema …

WebContainer Controlled Smoke Test

Overview

This skill adds or plans the smallest useful WebContainer proof: one instance, one deterministic file tree, one bounded dependency install, one server process, and one preview readiness observation. It avoids presenting a tutorial snippet as a production architecture.

Prerequisites

• A browser application already passing the StackBlitz integration preflight
• Cross-origin isolation and HTTPS behavior verified for the target environment
• A small synthetic project that contains no proprietary source or secrets

Tool Discipline

Use Read, Glob, and Grep to establish the application entrypoint, package versions, and existing lifecycle ownership. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit for a user-requested smoke-test implementation after inspection.

Current Contract

• WebContainer.boot() is expensive and permits only one concurrent instance; centralize ownership.
• mount() accepts a FileSystemTree or supported binary snapshot and copies it into the virtual filesystem.
• Check a spawned install process through its exit promise before starting the server.
• Register server-ready, error, and cleanup handlers before relying on a preview URL; retain the unsubscribe functions.
• Use the URL emitted by server-ready rather than constructing a preview host.

Authentication

The smoke test must not contain API keys, registry tokens, cookies, or .env data. If commercial API-key configuration or organization auth is required, consume the existing runtime binding and initialization module without displaying its value or duplicating the flow.

Workflow

1. Confirm the current package and browser support assumptions from repository evidence.
2. Reuse or create a singleton owner for the WebContainer instance.
3. Define a tiny synthetic project with a locked dependency set and explicit start script.
4. Mount the tree, spawn the repository-approved install command, stream bounded status output, and fail on a nonzero exit.
5. Subscribe to readiness and error events, start the server, and attach the emitted URL to the intended preview element.
6. Record cleanup behavior for listeners, processes, and teardown() when the owning view is permanently disposed.

Approval Boundaries

Do not add arbitrary user source, private packages, production secrets, telemetry, or broad network access to the smoke test without explicit authorization and a security review. Do not alter production isolation headers merely to make a local example pass.

Output

Return the…

StackBlitz Integration Preflight

Overview

This skill produces a repo-grounded installation and startup plan for either a custom WebContainer application or a StackBlitz SDK embed. It separates ordinary browser startup from commercial API-key configuration and organization-scoped private-package authentication.

Prerequisites

• A named browser application and permission to inspect its package and hosting configuration
• A decision between @webcontainer/api and @stackblitz/sdk, or evidence that both are needed
• A licensing decision for production commercial use before release

Tool Discipline

Use Read, Glob, and Grep to inspect package manifests, lockfiles, browser entrypoints, headers, and existing secret bindings. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only after the evidence pass, and never place API keys or OAuth material in source files.

Current Contract

• Pin the package version selected by the repository's dependency policy; do not install an unreviewed moving tag.
• Call configureAPIKey before WebContainer.boot() when a commercial license supplies an API key.
• Call auth.init before boot when organization users need private-package access; the user must be logged in, belong to the issuing organization, and authorize the site.
• Match the Cross-Origin-Embedder-Policy response header to the coep boot option. Use HTTPS outside localhost.
• A StackBlitz SDK embed is a separate surface and does not require booting a custom WebContainer in the host application.

Authentication

Public prototypes may not need user authentication, but production commercial use requires a licensing review. Treat the WebContainer API key as a secret runtime binding. Treat the auth client ID and scope as configuration, initialize auth during page loading, and handle need-auth, authorized, and auth-failed explicitly. Never infer that ordinary StackBlitz login grants access to private packages.

Workflow

1. Inspect the framework, package manager, lockfile, client/server boundary, CSP, and current response-header configuration.
2. Choose the minimum package surface and record the installed or proposed pinned version.
3. Decide whether the integration needs a commercial API key, organization auth, neither, or both.
4. Configure consistent COOP/COEP headers and the matching boot option; verify the final HTML response, including cached responses.
5. Add one startup module that orders API-key configuration, auth initialization, and the single boot call correctly.
6. Validate in a supported desktop browser …

WebContainer Local Development Loop

Overview

This skill turns a manually tested WebContainer host into a repeatable local loop. It separates pure file-tree and state-machine tests from browser integration tests that require SharedArrayBuffer, Service Workers, WebAssembly, and real response headers.

Prerequisites

• A named host application with an existing test framework or permission to add focused coverage
• A supported desktop browser available to the project's browser-test runner
• The repository's normal local HTTPS or localhost convention

Tool Discipline

Use Read, Glob, and Grep to locate runtime construction, HMR boundaries, response headers, unit tests, and browser tests. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit for minimal user-requested tests and configuration.

Current Contract

• Unit-test pure transformations such as flat-files-to-FileSystemTree without booting WebContainers.
• Test actual boot, process, Service Worker, and preview behavior in a real browser runner rather than a DOM-only simulator.
• Assert the final document is a secure context and crossOriginIsolated before boot.
• Preserve one boot promise across HMR; a module reload must not create a second concurrent instance.
• Exercise disposal separately from HMR so teardown() does not invalidate an instance still owned by the current page.

Authentication

Use synthetic public dependencies by default. If the browser test requires licensed or private-package access, bind credentials through the CI secret store, restrict the test environment, redact logs, and skip with an explicit reason when authorized credentials are unavailable.

Workflow

1. Map pure logic, browser-only logic, startup ownership, and deployment-header ownership.
2. Add fast unit tests for file-tree validation, state transitions, path policy, and bounded log formatting.
3. Add one browser smoke test that verifies isolation, boots once, mounts a synthetic fixture, observes a zero-exit command, and reaches preview readiness.
4. Trigger the repository's HMR path and confirm the boot owner remains singular.
5. Exercise navigation/disposal and confirm listeners and processes are released without breaking a surviving owner.
6. Run the narrow test first, then the project's normal lint, typecheck, and browser-test gates.

Approval Boundaries

Do not weaken browser security flags, disable isolation checks, commit credentials, or make a flaky integration test silently optional. Changes to shared CI browsers, production headers, or licensed secrets require explicit authorization.

Output

Return the test…

WebContainer Capacity and Constraints

Overview

This skill replaces unsupported universal quota tables with measured application budgets. WebContainer capacity depends on the browser, device, project, dependency graph, concurrent embeds, and hosted runtime; the output records local thresholds and graceful degradation rather than claiming a fixed vendor limit.

Prerequisites

• A named user journey, supported browser/device matrix, and representative synthetic project
• Existing performance or browser-test tooling, or permission to define a measurement plan
• Product thresholds for startup, interaction, failure recovery, and fallback

Tool Discipline

Use Read, Glob, and Grep to inspect mounted inputs, lockfiles, process creation, embeds, cleanup, and existing performance budgets. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only for an approved measurement harness or bounded optimization.

Current Contract

• Only one WebContainer may be booted concurrently on a page; additional experiences must share ownership or defer loading.
• Multiple projects, processes, dependencies, and embeds consume browser memory; out-of-memory behavior is device- and browser-dependent.
• Native addons do not run unless replaced by JavaScript or WebAssembly implementations.
• Including the applicable lockfile can avoid fresh dependency resolution and improve repeatability.
• Mount only required files and prefer one bulk mount() for initial hydration.
• Use lazy or click-to-load embeds and a static fallback when the page contains several interactive examples.

Authentication

Capacity tests use synthetic public packages by default. Never copy private source, tokens, registry credentials, or customer dependency metadata into a benchmark artifact. Licensed enterprise behavior must be tested only in its authorized environment.

Workflow

1. Define the critical journey and measurable startup, install, preview, memory-symptom, and recovery thresholds.
2. Inventory mounted bytes/files, dependency count and lockfile, process count, preview count, and cleanup behavior.
3. Measure a cold run and a repeat run across the supported browser/device matrix.
4. Vary one dimension at a time using synthetic fixtures and record the first degraded or failed state.
5. Apply the smallest optimization: reduce mounted inputs, pin/trim dependencies, reuse lifecycle ownership, defer embeds, or terminate unused processes.
6. Re-measure, set an application-owned budget, and define a user-visible fallback before rollout.

Approval Boundaries

Do not run load experiments against customer projects, weaken browser security, remove required fu…

WebContainer Lifecycle Adapter

Overview

This skill creates or reviews one application-owned boundary around WebContainer startup and capabilities. The adapter makes boot idempotent, exposes explicit runtime states, tracks event unsubscriptions and processes, and prevents UI components from independently manipulating a shared instance.

Prerequisites

• A named repository and the components that currently own runtime behavior
• The installed @webcontainer/api type definitions as the local API authority
• Expected mount, process, preview, export, and disposal use cases

Tool Discipline

Use Read, Glob, and Grep to map imports, boot calls, process ownership, filesystem mutations, event subscriptions, and teardown paths. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit after proposing the adapter boundary and compatibility impact.

Current Contract

• Cache the boot promise, not only the resolved instance, so concurrent callers cannot race into two boots.
• Model at least idle, booting, ready, failed, and disposed states; make invalid transitions visible.
• Retain the unsubscribe function returned by on() and the handles returned by spawn().
• Treat filesystem writes and export() as explicit data operations with caller-owned paths and size bounds.
• teardown() invalidates the instance, processes, and filesystem; call it only at the permanent owner boundary.
• Prefer adding preview instrumentation in the served application; use setPreviewScript only after reviewing its advanced-feature warning and compatibility risk.

Authentication

The adapter may accept already-resolved configuration but must not expose secret values through state, logs, errors, or browser storage. Initialize commercial keys and organization auth before adapter boot through the dedicated preflight layer.

Workflow

1. Inventory every WebContainer import, boot call, event listener, process handle, filesystem writer, and teardown call.
2. Define the adapter's state machine and minimum methods from observed consumers.
3. Centralize a single boot promise and make failed startup recoverable only through an explicit reset or disposal policy.
4. Wrap spawn with exit, output-bound, cancellation, and ownership metadata.
5. Wrap subscriptions so each consumer can unsubscribe and the owner can perform final cleanup.
6. Add focused concurrency, failure, HMR, and teardown tests before migrating consumers incrementally.

Approval Boundaries

Do not migrate all consumers, change persistent/export behavior, terminate active processes, or alter production preview instrumenta…

WebContainer Security Review

Overview

This skill produces a repo-grounded threat model and bounded hardening plan. Browser containment reduces host risk, but it does not make user code trustworthy, prevent all network activity, protect secrets mounted into the runtime, or replace host-page CSP and data-governance controls.

Prerequisites

• A named application, data classification, and intended code/dependency sources
• Identified owners for the host page, runtime lifecycle, auth, preview, persistence, and deployment headers
• Permission to inspect security-sensitive configuration without reading secret values

Tool Discipline

Use Read, Glob, and Grep to trace input, filesystem, process, dependency, network, preview, auth, CSP, and persistence paths. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write for an approved threat model and Edit only for narrow reviewed controls.

Current Contract

• Treat mounted files, spawned commands, installed packages, terminal input, preview messages, and exported artifacts as untrusted flows.
• Never mount host secrets or ambient .env files into user-controlled projects; code running there may read them.
• Validate virtual paths component by component and reject traversal, absolute paths, ambiguous separators, duplicates, and dangerous overwrite targets.
• Pin dependencies and preserve install provenance; browser execution does not remove package supply-chain risk.
• Derive CSP and frame/connect allowances from observed official runtime behavior and the chosen embed mode; do not copy a universal permissive header.
• Match cross-origin isolation headers and iframe requirements without weakening unrelated host protections.
• Define retention and review for any saved or exported user project; the runtime filesystem alone is ephemeral.

Authentication

Keep commercial API keys in existing runtime secret bindings and configure them before boot. Organization auth for private packages is a separate user-authorized flow. Do not log auth parameters, tokens, cookies, private registry settings, or package contents.

Workflow

1. Map assets, actors, entrypoints, trust boundaries, data flows, and privileged operations.
2. Classify code, files, dependencies, terminal input, previews, exports, and auth material by trust level.
3. Identify abuse cases for path traversal, secret exposure, dependency compromise, runaway processes, network exfiltration, preview-to-host messaging, and persistence.
4. Map existing preventive, detective, and recovery controls to each abuse case.
5. Implement only the highest-value bounded control with tests for expected, hostile, and rollback paths.
6. Record re…