| name | juce-webview-runtime |
| description | Advanced JUCE WebView runtime integration, host compatibility, debugging, and QA guidance for plugin UIs. |
Title: JUCE WebView Runtime Skill
Document Type: Skill
Author: APC Codex
Created Date: 2026-02-20
Last Modified Date: 2026-03-01
JUCE WebView Runtime
Use this skill for deep runtime issues in JUCE WebView plugin UIs (interop glitches, input hit-testing issues, host-specific behavior, callback timing, and bridge reliability).
Workflow
- Establish host/runtime matrix (DAW, plugin format, OS, JUCE version).
- Confirm bridge contract and startup ordering.
- Instrument JS/native boundaries and timeout paths.
- Reproduce with a minimal host scenario.
- Apply fix with explicit fallback behavior.
- Validate across targeted host matrix and document residual risks.
Reference Map
references/host-behavior-matrix.md: Host-specific behavior tracking template.references/bridge-contract-and-fallbacks.md: JS/native contract and fallback rules.references/debugging-playbook.md: Diagnostic steps and capture checklist.references/qa-and-evidence.md: Acceptance matrix and evidence requirements.
Backend Scope: WKWebView vs WebView2
WKWebView (Apple) and WebView2 (Windows) must be treated as distinct runtime targets.- Differences that matter for bug triage and QA:
- Process/runtime model and crash isolation behavior.
- JS/native bridge entry points and callback timing semantics.
- Input focus/hit-testing behavior for embedded plugin UIs.
- Storage/session/profile behavior and persistence scope.
- Every runtime bug write-up must include backend, host, plugin format, and reproducible steps.
Execution Rules
- Preserve relay/attachment/member-order constraints in JUCE editor classes.
- Treat bridge timeouts and callback ordering as first-class failure modes.
- Keep browser-preview fallbacks functional for non-host testing.
- Add explicit status/error feedback in UI for native call failures.
- Never ship host-specific hacks without documenting scope and rationale.
Startup Hydration And Sync Contract
- Validate startup sequencing for runtime states that depend on hardware readiness.
- Prefer explicit UI gating (ready/not-ready + manual sync) over implicit startup assumptions.
- Capture bridge ordering and timeout behavior when state transitions involve async device availability.
Deliverables
- Repro steps (host + format + exact action path).
- Root-cause summary across JS and native sides.
- Validation status as
tested, partially tested, or not tested.
