Questions developers ask most often. For step-by-step fixes see the [troubleshooting pages](/help-center); for the full references see the [Schema](/schema/overview) and [Player](/player/overview) sections. ## Format and validation The schema uses JSON Schema draft 2020-12. Import AJV's 2020 build (`require('ajv/dist/2020')`), add `ajv-formats`, and construct it with `strict: false` — the default draft-07 AJV build cannot compile it. See [Validation](/schema/validation). Nearly every object in the schema sets `additionalProperties: false`, so a typo in a property name, a field at the wrong nesting level, or custom data without the `x-` prefix is rejected. Check the property name against the reference page for that object, and note that `x-` extension fields are only allowed at the manifest root, on panels and on extras blocks (the last two since format 1.7). See [Extensions](/schema/extensions) and [Validation Errors](/help-center/troubleshooting/validation-errors). No. The schema directory is named after the **major** version; minor releases are additive and ship in place. Formats 1.1 through 1.7 all validate against `https://panelwave.org/schema/1.0/panelwave.schema.json`, and every valid 1.0 manifest stays valid. See [Versioning](/schema/versioning). No — JSON Schema validation is structural only. Dangling `assetId`s, unknown `characterId`s, or graph edges to missing panels pass validation but break at runtime. Run reference and reachability checks in your pipeline: the [CLI](/schema/cli) adds some warnings, and the CMS runs full [preflight checks](/cms/validation). At the manifest root, on a `Panel` and on an extras block (`ExtraBlock`) you can add any property starting with `x-` (e.g. `x-mytool-state`); the last two since format 1.7. Deeper in the tree most objects are closed, so other nested `x-` keys fail strict validation — use `PluginInstance.props` (any JSON) or `pluginPayload` catalog assets instead. See [Extensions & Plugins](/schema/extensions). ## Player integration `npm install @panelwave/player @ngx-translate/core`. The package is on npm, built and published from [github.com/panelwave/player](https://github.com/panelwave/player) with provenance. You also need `provideHttpClient()`, an ngx-translate loader, the package's UI translation files and the balloon font CSS — see [Installation](/player/installation). Angular 20, 21 and 22 with player **1.2.0**, the current npm release. Player 1.1.0's peer dependencies were `@angular/common`/`@angular/core` `^20`, `@ngx-translate/core` `^17` and `rxjs` `^7.8`; 1.2.0 widens them to `^20 || ^21 || ^22` and `^17 || ^18`. The library is built with Angular 20 and TypeScript 5.8 and verified against fresh Angular 20, 21 and 22 apps, zone.js and zoneless. See [Installation](/player/installation). `manifestUrl` is the shortest path — the shell fetches and validates the JSON itself. Bind a parsed `[manifest]` object when you need to fetch with your own auth or transform the JSON first. Both paths give the same reader: the table of contents and thumbnail strip work either way, and assigning a new URL or object later loads the new work. See [Quickstart: Embed](/player/quickstart-embed). Yes — open the [live demo](https://panelwave.github.io/player/) and use **Open file…** or `?manifest=`. Its dev tools show variables, events and performance, and a debug overlay outlines layers, hotspots and bubbles. See [Demo App](/player/demo-app). Neither. Player state is managed with RxJS `BehaviorSubject`-backed services; components are standalone with OnPush change detection. Persistent-scope variables are stored in `localStorage`. See [State & Conditions](/player/state-and-conditions). `FlowEngineService.getNextPanel()` collects all edges leaving the current panel, evaluates each JSON Logic condition against the flattened variable context (missing condition = always true; evaluation error = fail-closed), sorts survivors by numeric priority with the **highest value winning** (missing priority = 0), and follows the first edge. See [State & Conditions](/player/state-and-conditions). Partly. Persistent-scope variables survive reloads (`localStorage` key `pw-variables-persistent`), and a **bookmark** the reader sets from the toolbar is resumed on the next visit when you pass no start position. Automatic "continue where you stopped" is the host application's job: record the shell's `panelChange` output (it fires once per navigation) and feed the saved position back into `initialChapterId`/`initialPanelId`. See [Saving Progress](/player/saving-progress). Browsers block audible playback before a user gesture (hover doesn't count). The player's `UserGestureService` reports the first real interaction and `AudioEngineService` exposes `resumeContext()`; on-view videos begin muted until a gesture occurs. See [Audio](/player/audio). ## Rendering, assets, and monetization Layers reference catalog items by `assetId`; each item has variants. The player first applies the locale fallback chain, then picks the smallest variant whose width meets the required pixel width (display width × device pixel ratio), preferring modern formats (AVIF before WebP before JPEG). The chosen `src` resolves against the `assets.base` URLs. See [Performance](/player/performance) and [Assets](/concepts/assets). The open-licensed balloon font set ships with the package, but its CSS (`assets/fonts/balloon/balloon-fonts.css`) must be included once in your application's styles. Note that Ames Pro is a commercial font that is not bundled — without a license, balloons fall back to Comic Neue. See [Installation](/player/installation). The CMS editor, where balloons are designed and tested, holds the master copy of `comic-balloon.ts` and `balloon-geometry.ts`; the player holds a synced copy (marked "do not edit") so editor and reader render balloons identically. Geometry fixes land in the CMS master and are synced into the player. See [Balloon Renderer](/player/balloon-renderer). The player treats the reader as anonymous until you tell it what they own. Pass an `[entitlementSnapshot]` (tier, purchased product ids, age verification), or set `entitlementEndpoint` + `readerToken` so the player fetches it. After a purchase during reading, call `refreshEntitlements()` or bind the new snapshot — the shell re-evaluates the gates when `[entitlementSnapshot]` changes. See [Paywall & Entitlement](/player/paywall-entitlement). The manifest declares the rules; your app supplies the reader's entitlements; the player evaluates them locally, stops at a gate, and emits `paywallAction` — with the Buy / Subscribe option the reader picked (`productId`) — so your app runs checkout; the player never talks to a payment provider. Client-side gating is a reading-experience layer, not a security boundary: truly protected content must also be withheld server-side (e.g. signed URLs) until the reader is authorized. See [Monetization](/concepts/monetization). ## AI assistants and MCP The server at `https://mcp.panelwave.org/mcp` speaks stateless Streamable HTTP. It supports the 2026-07-28 protocol revision and serves 2025-06-18 and 2025-11-25 clients as well. There is no SSE-only transport. For stdio clients, use the [local bridge](/cms/integrations/local-bridge) (`npx -y @panelwave/mcp`). Send a personal access token as `Authorization: Bearer pw_pat_…`. Interactive clients should use OAuth instead: the server publishes protected resource metadata, and the authorization server supports dynamic client registration, client ID metadata documents and PKCE. See [Claude Code, Cursor & Others](/cms/integrations/connect-cursor-and-code). Destructive tools never run on the first call. Clients that support elicitation get a yes/no form instead. Other clients should show the message to the user and call the tool again with `confirm: true` once the user agreed. See the [tool reference](/cms/integrations/tool-reference).

Developers FAQ

Format and validation

Player integration

Rendering, assets, and monetization

AI assistants and MCP