| name | lit-webview-architecture |
| description | Design or refactor a Lit webview's package boundary, Effect service contract, host adapter, lifecycle, registration, or browser bundle. Use for VS Code webviews that separate browser-safe UI from extension-host APIs and message protocols. |
| review | never |
Lit webview architecture
Boundary: UI owns presentation, browser-safe state/actions, and lifecycle coordination; host owns VS Code APIs, transport, metadata/network authorities, and localization.
Browser-safe contract
- Immutable view state, UI actions, and typed errors from Effect Schemas. Tagged/literal unions instead of loose primitives, enums, or duplicated constants when invalid states matter.
- Directional host-to-UI and UI-to-host message schemas. Handler variant added with its behavior; exhaustive
Match; no opposite-direction placeholder arms.
- Unknown data validated at entry. DOM
CustomEvent: structural type/detail guard, then Schema validation of detail; inherited DOM accessors do not form a plain schema struct.
- Required localized labels injected by the host; no defaults hiding missing localization.
- No VS Code, JSforce, extension service, or extension-message imports in the browser-safe package. Host data normalized and validated before UI state.
- Only subpaths with known consumers exported; no root/testing barrels. Type-only dependencies in
devDependencies with import type.
Effect lifecycle
- 1 service contract: initial state, state stream, typed action dispatch. Extension-owned live layer plus deterministic test layers.
- 1 composition-root-owned scoped fiber per mounted webview: controller, queues, subscriptions, DOM listeners, finalizers.
- Listeners/subscriptions acquired and released as scoped resources. Disconnect interrupts and awaits the session fiber.
- Fiber-identity guard on finalizer cleanup; an old disconnect cannot clear a newer rapid reconnection.
- Components only render state and dispatch intent—no runtimes, scattered
Effect.runFork/Effect.runPromise, or host calls.
Registration and bundling
- Explicit host-called custom-element registration; every
customElements.define guarded by customElements.get; no registration import side effects.
- New entries built with shared browser esbuild config. IIFE retained while HTML loads a classic deferred script; ESM requires matching script/resource-rewrite changes.
- Non-published UI workspaces marked
private and excluded from publication/versioning. Contract tests scan source and bundles for host imports and Effect execution in presentation code.
- Compile/bundle/test order expressed in Wireit; browser tests consume the intended emitted application.
Examples: packages/soql-builder-ui/src/application.ts, packages/soql-builder-ui/src/register.ts, packages/soql-builder-ui/test/package-contract.test.mjs, packages/salesforcedx-vscode-soql/src/soql-builder-ui/lit/.
