@mosaicast/plugin-sdk 0.3.0 → 0.5.0

package/README.md

@@ -29,7 +29,11 @@ src/testing.ts     TS:  @mosaicast/plugin-sdk/testing — makeMockCtx
 
 The contract version is a **single SemVer anchor** mirrored in four places that MUST move together
 (CI enforces it): `build.gradle.kts` · `package.json` · `PlatformApi.VERSION` · `PLATFORM_API_VERSION`.
-A breaking change is a major bump; the host rejects plugins with an incompatible `platformApi` at startup.
+
+**How the host matches it:** core compares `major.minor` **exactly**. A plugin declaring `0.3.x` is
+rejected the moment the host runs `0.5.0` — with the reason shown in the admin log viewer. While the SDK
+is pre-1.0 a breaking change is therefore a **minor** bump (`0.4.0` → `0.5.0`), not a major one; from
+`1.0.0` on, normal SemVer applies and breaking means major.
 
 ## Build & test
 ```bash
@@ -45,8 +49,8 @@ npm ci && npm run build               # TypeScript: src → dist (.js + .d.ts)
   - Released: from **GitHub Packages** (see below).
   ```kotlin
   dependencies {
-      compileOnly("dev.mosaicast:plugin-api:0.3.0")           // contract, provided by the host
-      testImplementation("dev.mosaicast:plugin-testkit:0.3.0") // test doubles only
+      compileOnly("dev.mosaicast:plugin-api:0.5.0")           // contract, provided by the host
+      testImplementation("dev.mosaicast:plugin-testkit:0.5.0") // test doubles only
   }
   ```
   Sources + Javadoc JARs give IDE hover docs automatically.
@@ -95,21 +99,205 @@ DELETE /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}
 | upsert | `store().put(scope, key, value)` | `ctx.api.put('data/…/{key}', value)` |
 | remove | `store().delete(scope, key)` → `boolean` | `ctx.api.delete('data/…/{key}')` |
 
-- `scopeType` is `site | feed | season | episode` and `scopeId` is that entity's id — mirroring `Scope`/`ScopeType`, the same addressing the backend uses. **`site`'s `scopeId` is always `main`** (`Scope.SITE_ID`): there is only one site, so both the SDK and the host normalize every site scope to that singleton — `Scope.site()` and `…/data/site/main/{key}` address the same document, and the path always has four non-empty segments.
-- `key` must match `DocStore.KEY_PATTERN` = `^[A-Za-z0-9._:-]{1,200}$` and is the final path segment, verbatim — no `/`, and no percent-encoded slash either (servlet containers reject `%2F` there). Structure keys with `:` / `.` / `-` instead, e.g. `mark:userId:cell`. The host answers 400 on a bad key, and `InMemoryDocStore` throws `IllegalArgumentException` — so it fails in your tests, not in production.
+- `scopeType` is `site | feed | season | episode | user` and `scopeId` is that entity's id — mirroring `Scope`/`ScopeType`, the same addressing the backend uses. Two are **singletons** whose id the SDK and the host both pin: `site`'s is always `main` (`Scope.SITE_ID`, one site) and `user`'s always `me` (`Scope.SELF_ID`, the calling user). So `Scope.site()` and `…/data/site/main/{key}` address the same document, and the path always has four non-empty segments.
+- `key` must match `DocStore.KEY_PATTERN` = `^[A-Za-z0-9._:-]{1,200}$` and is the final path segment, verbatim — no `/`, and no percent-encoded slash either (servlet containers reject `%2F` there). Structure keys with `:` / `.` / `-` instead, e.g. `mark:s2e04:b3` (entity ids are slugs, not UUIDs). The host answers 400 on a bad key, and `InMemoryDocStore` throws `IllegalArgumentException` — so it fails in your tests, not in production.
 - The list is **paginated** (core's standard `PagedResponse` envelope) and **carries keys** (`DocEntry`), because neither end can address a doc without one.
 - `delete` is **idempotent**: removing an absent doc is not an error. The Java call returns whether anything was actually removed.
 
+### Per-user data — the `user` scope (since 0.5.0)
+
+**Per-user data belongs in the `user` scope, never in the key.** A key is client-supplied, so the convention this README used to suggest — `mark:<userId>:cell` under an episode scope — was an access-control decision the host could not enforce: any caller past the plugin's read floor could address someone else's key directly, and scope ids are public slugs, so nothing had to be guessed.
+
+`Scope.user()` / `…/data/user/me/{key}` fixes that by construction:
+
+- The id is always the sentinel `me` (`Scope.SELF_ID`), resolved **server-side from the session**. The canonical `Scope` constructor normalizes any `USER` id to it, so there is no expression in the Java API that names another person's partition — and there is deliberately **no `Scope.user(String)` overload**.
+- Naming any other `user` id over HTTP is a **400**, never a silent substitution. An anonymous `user` request is a **401** whatever the read floor says: no session, no partition.
+- The partition is **flat** — one per user, not one per user and entity — so the entity goes in the key: `mark:<episodeSlug>:cell`.
+- `readableBy` does not apply to it. No floor makes someone else's partition readable.
+
+**A backend has no calling user**, so every `DocStore` method throws `UnsupportedOperationException` for a `USER` scope — reads included, since resolving "me" without a caller would have to pick someone. Aggregate instead:
+
+```java
+// Backend-only, read-only, and no HTTP surface: no visitor's request can reach another's data.
+List<OwnedDocEntry> marks = ctx.store().queryAcrossUsers("mark:");
+// record OwnedDocEntry(UUID userId, String key, JsonNode value) — the owner is host-resolved, never
+// a value the browser supplied, which is what makes a leaderboard built from it true.
+```
+
+Write the aggregate back to an entity scope (`…/data/episode/s2e04/leaderboard`) and let the component read it there. In tests, `InMemoryDocStore.asUser(uuid)` stands in for the host resolving `me`, so you can seed what a frontend would have written and then assert on `queryAcrossUsers`.
+
 **The two ends see one store.** The doc a backend writes with `ctx.store().put(scope, key, value)` is exactly what the frontend reads at `GET /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}`.
 
 **What the host enforces**, so a plugin doesn't have to:
 - Data is **hard-scoped to the plugin id** — a plugin can only ever see its own data.
-- **Reads** are gated by the slot's `visibleTo`; **writes** require the mapped role. The host validates that the scope exists (and that the feed is enabled). `ctx.api` carries the user's auth (session or personal access token).
+- **Access is what the manifest declares**, not what the slots imply: `"data": { "readableBy": "fan", "writableBy": "podcaster" }`. Values are `anonymous | fan | podcaster | admin`; `writableBy` may not be `anonymous`, and an absent block defaults `readableBy` to the **write** floor rather than to anonymous — saying nothing gets the safe answer. A slot's `visibleTo` governs **rendering only**; deriving the data floor from unrelated UI slots is what once let a plugin with one anonymous slot expose its whole store.
+- The host validates that the scope exists (and that the feed is enabled). `ctx.api` carries the user's auth (session or personal access token).
 
 **No request-time server logic.** A write is plain persistence — no plugin code runs on the request. Anything derived, validated or aggregated server-side is **precomputed** in `register`/`onSchedule` and read back from the store.
 
 > Roadmap: custom plugin-defined server routes may arrive in a later `platformApi` version; plugins use the doc store.
 
+## Relational storage — `ctx.schema()` (since 0.4.0)
+
+The doc store is the default and covers nearly everything. Declare a **schema** when you need what a JSON
+document cannot give you: full-text search, revisions, backlinks. Any plugin may; most declare nothing.
+
+You declare entities and fields in the manifest, and the **platform** provisions namespaced tables
+(`plugin_<id>_*`) through its managed migration runner, dropping them when an admin purges the plugin.
+**The plugin never writes DDL and never names a table:**
+
+```json
+"storage": { "schema": { "page": {
+    "slug": "string:indexed:unique", "title": "string",
+    "markdown": "text:fulltext", "updatedAt": "timestamp:indexed" } } }
+```
+
+```java
+record Page(long id, String slug, String title, String markdown, Instant updatedAt) {}
+
+SchemaStore schema = ctx.schema();                      // null unless the manifest declares one
+
+long id = schema.insert("page", Map.of(
+        "slug", "getting-started", "title", "Getting started",
+        "markdown", "# Hello", "updatedAt", Instant.now()));
+
+Optional<Page> byId = schema.find("page", id, Page.class);
+List<Page> recent   = schema.select("page",
+        Criteria.all().orderBy("updatedAt", Direction.DESC).limit(20), Page.class);
+List<Page> hits     = schema.search("page", "markdown", "lighthouse", Criteria.all(), Page.class);
+long total          = schema.count("page", Criteria.all());
+schema.update("page", id, Map.of("markdown", "# Hello again"));
+schema.delete("page", Criteria.where("slug", Op.EQ, "getting-started"));
+```
+
+- Everything is addressed by **declared entity and field name — never SQL, never a table**. That is the
+  scoping guarantee: reaching another plugin's tables isn't blocked, it's inexpressible. The host binds
+  every value as a JDBC parameter and checks every field name against your manifest.
+- Rows map to **your own record types**, component names matching field names — the same convention as
+  `store().get(...)` and `config().get(...)`. Each entity carries a platform-assigned `long id`.
+- `Criteria` is immutable; predicates combine with **AND** (no `or` in 0.4.0). `search` needs a field
+  declared `:fulltext`; for a plain match use `Op.LIKE` with `select`.
+- Naming an undeclared entity or field throws `IllegalArgumentException` — against the test kit too, so a
+  manifest that drifted from the code fails in your tests.
+
+Test it with `FakeSchemaStore`, declaring the same entities your manifest does. Its `search` is a
+substring match, **not** Postgres full-text: no stemming, no ranking. Assert on which rows come back, not
+on their order.
+
+## Logging — `ctx.logger()` / `ctx.log()` (since 0.4.0)
+
+```java
+ctx.logger().info("indexed {} pages", count);          // org.slf4j.Logger, named plugin.<pluginId>
+```
+```ts
+ctx.log('warn', `no board for episode ${ctx.scope.id}`);
+```
+
+A plain SLF4J `Logger` on the backend: authors know the API, and parameterised messages and throwables
+come free. **Attribution rides in the logger name**, which is why the host hands you a named logger rather
+than offering `log(level, message)` — the name travels with the event, so output is still attributed to
+your plugin from a thread you started or from an `onSchedule` task, where a thread-local MDC arrives
+empty. Don't build your own `LoggerFactory.getLogger(...)`: it won't sit under the `plugin.` prefix and
+the host can't attribute it.
+
+The host stores `info` and above, surfaces `warn` and above in the admin log viewer, and **rate-limits**
+this path. On the frontend, `ctx.log` replaces POSTing to `/api/plugins/{id}/log` through `ctx.api`.
+`FakePluginContext.logger()` returns a `RecordingLogger`, so a test asserts on logging the way it asserts
+on stored documents; `makeMockCtx` collects `ctx.logs`.
+
+## Consent & the manifest (core-owned schema)
+
+Core runs **banner-free** — strictly necessary cookies need no consent. The only reason a visitor sees a
+consent prompt is a plugin that asked for one, so treat it as the cost it is.
+
+### `ctx.consent` (frontend)
+
+```ts
+if (ctx.consent.has('analytics')) mountChart(root);
+else button.onclick = async () => {
+  if (await ctx.consent.request('analytics')) mountChart(root);   // from a user gesture, never on mount
+};
+
+const off = ctx.consent.onChange(() => rerender());               // fires on every change
+return off;                                                       // detach on cleanup
+```
+
+`request(category)` opens the host's settings for that one purpose and resolves with the visitor's answer
+(`false` if dismissed). `granted()` lists everything currently granted. `onChange` fires on **every**
+change — including a withdrawal made in the settings page while you are mounted — and returns an
+unsubscribe. Since 0.4.0 `filter`, `route`, `locale` and `player.on` return one too.
+
+**Services describe, categories decide.** The manifest is per-service (`provider`, `privacyUrl`,
+`thirdCountryTransfer`, each `storage[]` item) but every `ctx.consent` method takes a **category**. The
+per-service detail exists so the notice can name who stores what for how long; what the visitor toggles is
+the category. So if two plugins each declare an `analytics` service with different providers, the visitor
+sees **one** decision listing both plugins, and granting it grants both — there is no way to accept one
+provider and refuse the other. If you need your own services to be refusable independently, declare them
+under **different categories** (a plugin-declared category is fine; the shell just has no translated label
+for it). That is the only lever the contract gives you.
+
+**`necessary` is never asked about.** `has('necessary')` is always `true` and the host never prompts for
+it — it is the category the core itself uses, and a banner-free site stays banner-free. Declaring a
+service `necessary` means "this loads unconditionally"; use it only for what genuinely cannot be refused.
+
+**Concurrent `request()` calls.** A page of plugin tiles will produce them, so the contract is explicit:
+there is **one consent surface host-wide** (a second call joins the one in flight rather than opening
+another); the visitor decides **all** categories in one interaction, so other categories may move too;
+every call resolves exactly once and is never dropped; and grants are **shared across plugins** — another
+plugin's accepted `request('analytics')` resolves yours too. Don't serialize calls or build a queue, and
+re-read `has(...)` after a change instead of caching what a request resolved with.
+
+### `consent.services[]` in `plugin.json`
+
+The manifest type is **core-owned** — the SDK has no manifest type and will not grow one — but this is
+where plugin authors look, so the required shape is documented here. **From `0.4.0` the legacy
+`{ "categories": [...], "externalSources": [...] }` form is rejected** and the plugin will not load.
+
+```json
+"consent": {
+  "services": [{
+    "id": "plausible",
+    "name": "Plausible Analytics",
+    "provider": "Plausible Insights OÜ",
+    "category": "necessary | functional | analytics | <plugin-declared>",
+    "privacyUrl": "https://plausible.io/privacy",
+    "hosts": ["https://plausible.example"],
+    "thirdCountryTransfer": false,
+    "storage": [
+      { "name": "plausible_ignore", "type": "cookie | localStorage | sessionStorage",
+        "purpose": "Remembers that you opted out of statistics", "duration": "persistent | session | 12 months" }
+    ]
+  }]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable identifier for this service within your plugin. |
+| `name` | The service as a visitor would recognise it, e.g. "Plausible Analytics". |
+| `provider` | The **legal entity** operating it — the company name, not your plugin's. |
+| `category` | The consent category the service falls under; what `ctx.consent.has(...)` gates on. **`necessary` is always granted and never prompted for.** Two services sharing a category are decided together. |
+| `privacyUrl` | The provider's own privacy policy. |
+| `hosts` | Every origin the service is contacted on. **Also the CSP allow-list** — see below. |
+| `thirdCountryTransfer` | Whether personal data leaves the EU/EEA. |
+| `storage[]` | Each item the service stores on the device: `name`, `type`, `purpose`, `duration`. |
+
+**Why the shape changed.** A cookie notice that satisfies §25 TDDDG / Art. 5(3) ePD has to name each
+stored item, what it is for, how long it lasts, who the provider is, and whether data leaves the country.
+Category slugs and bare hostnames cannot produce that — and they force the notice to talk about "plugins"
+to visitors who only care about cookies and named companies.
+
+**`hosts` doubles as the CSP allow-list.** Core widens `script-src` / `frame-src` / `connect-src` by
+exactly these origins. An origin you did not declare **stays blocked even after consent is given** — if a
+third-party embed silently fails to load with consent granted, an undeclared host is the first thing to
+check.
+
+**Authoring help:** the SDK exports `ConsentServiceDeclaration` (and `ConsentStorageDeclaration`) as a
+**documentation-only** type. Nothing in the SDK reads `plugin.json` or validates it — the host owns and
+enforces the manifest — but typing a literal against it gives you completion and catches a typo before
+core rejects the plugin at load, which is otherwise your first feedback. If the type and core ever
+disagree, **core wins**; treat the mismatch as an SDK bug. The manifest as a whole stays core-owned.
+
 ## Releasing (maintainers)
 Publishing is automated and fires on a **published GitHub Release**, not on PR merge
 (`.github/workflows/release.yml`).

package/dist/index.d.ts

@@ -11,19 +11,65 @@
  * The plugin contract version (SemVer).
  *
  * Mirror of the Java `dev.mosaicast.plugin.api.PlatformApi.VERSION` constant and the npm package
- * version. The host rejects a plugin whose manifest `platformApi` is incompatible with this value
- * (ARCHITECTURE §7.2). **These move together — a breaking change is a major bump.**
+ * version — **these move together**, and CI fails the build if they drift.
+ *
+ * The host compares a plugin manifest's `platformApi` against this value on **`major.minor` exactly** and
+ * rejects a mismatch at startup (ARCHITECTURE §7.2). While the SDK is pre-1.0 a breaking change is
+ * therefore a *minor* bump; from `1.0.0` on, breaking means major.
  */
-export declare const PLATFORM_API_VERSION: '0.3.0';
+export declare const PLATFORM_API_VERSION: '0.5.0';
 /** A user's role (ARCHITECTURE §8.5). Anonymous visitors have no role (`user` is `null`). */
 export type Role = 'admin' | 'podcaster' | 'fan';
-/** The level plus concrete entity a view is scoped to (ARCHITECTURE §6.1). */
+/**
+ * The severity of a {@link PluginContext.log} call.
+ *
+ * Mirrors the SLF4J levels a plugin backend gets through the Java `ctx.logger()`, minus `trace` — a
+ * browser has no use for it, and the host would drop it anyway.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Unsubscribes a callback registered through one of the `onChange` handles.
+ *
+ * Call it when your component tears down — the cleanup callback returned from your
+ * {@link MosaicastRender} is the natural place. A subscription that outlives its render keeps a
+ * reference to a detached DOM tree and keeps firing into it.
+ */
+export type Unsubscribe = () => void;
+/**
+ * The level plus concrete entity a view is scoped to (ARCHITECTURE §6.1).
+ *
+ * This is the **slot** scope — the page your component was mounted on. It never carries the `user` level
+ * of {@link DataScopeType}: a slot lives in a named region of a page, and there is no user page. A
+ * component reading per-user data addresses `data/user/me/…` explicitly while `ctx.scope` stays whatever
+ * page it is on.
+ */
 export interface Scope {
     /** The scope level. */
     type: 'site' | 'feed' | 'season' | 'episode';
-    /** The id of the entity at that level (e.g. the `EpisodeRef` id for `episode`). */
+    /** The id of the entity at that level (e.g. the `EpisodeRef` slug for `episode`). */
     id: string;
 }
+/**
+ * The scope levels the host's **data** surface addresses — the four page levels of {@link Scope} plus
+ * `user`, the caller's own private partition (`ScopeType` in the Java SDK).
+ *
+ * Deliberately a second type: `user` is a storage partition, never a slot scope, so it can appear in a
+ * `data/{scopeType}/{scopeId}/…` path but never in `ctx.scope`.
+ *
+ * @since 0.5.0
+ */
+export type DataScopeType = Scope['type'] | 'user';
+/**
+ * The id every `user` data path carries: the literal `me`, mirroring the Java `Scope.SELF_ID`.
+ *
+ * The host resolves it from the session, so `data/user/me/{key}` reaches the calling user's partition and
+ * no one else's. **Any other `user` id is a 400**, never a silent substitution, and an anonymous request
+ * to a `user` path is a 401 — with no session there is no partition. Per-user data belongs here rather
+ * than in a key like `mark:<userId>:cell`, which the host cannot enforce because the client supplies it.
+ *
+ * @since 0.5.0
+ */
+export declare const SELF_SCOPE_ID: 'me';
 /**
  * The host-owned filter axes for the current view (ARCHITECTURE §6.1).
  *
@@ -117,38 +163,73 @@ export interface PagedDocs<T = unknown> {
  *          → remove; idempotent
  * ```
  *
- * `scopeType` is `site | feed | season | episode` and `scopeId` the id of that entity — i.e. the
- * {@link Scope} the backend addresses with. For `site` the id is the literal `main` (one site, one
- * singleton scope), so the path always has four non-empty segments. `key` must match
+ * `scopeType` is a {@link DataScopeType} and `scopeId` the id of that entity — i.e. the `Scope` the
+ * backend addresses with. Two of them are singletons whose id is fixed: `site` is always the literal
+ * `main` (one site), and `user` always {@link SELF_SCOPE_ID} (`me`), which the host resolves to the
+ * calling user. So the path always has four non-empty segments. `key` must match
  * `^[A-Za-z0-9._:-]{1,200}$` — the host answers 400 otherwise — and is the final path segment verbatim:
- * no `/`, so structure keys with `:` / `.` / `-` (e.g. `mark:userId:cell`). The list is paginated
- * ({@link PagedDocs}) and carries each doc's key ({@link DocEntry}), since you cannot address a doc
- * without it.
+ * no `/`, so structure keys with `:` / `.` / `-` (e.g. `mark:s2e04:b3`; entity ids are slugs). The list
+ * is paginated ({@link PagedDocs}) and carries each doc's key ({@link DocEntry}), since you cannot
+ * address a doc without it.
  *
  * The doc a backend writes with `ctx.store().put(scope, key, value)` is the one read here at
- * `GET /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}`: one store, two ends.
+ * `GET /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}`: one store, two ends. The `user` scope is the
+ * exception — it exists only here. A backend has no calling user, so it cannot write a user partition at
+ * all and reads them only in aggregate, through the Java `DocStore.queryAcrossUsers(prefix)`.
+ *
+ * ## Where per-user data goes
+ *
+ * **In the `user` scope, not in the key.** A key is client-supplied, so the older convention
+ * `mark:<userId>:cell` under an episode scope was an access-control decision the host could not check:
+ * any caller past the plugin's read floor could address someone else's key, and scope ids are public
+ * slugs, so nothing had to be guessed. `data/user/me/…` is resolved from the session instead — the only
+ * partition a caller can name is their own. Any other `user` id is a **400**; an anonymous `user` request
+ * is a **401**, whatever the read floor says. The partition is flat, so the entity goes in the key:
+ * `mark:<episodeSlug>:cell`.
+ *
+ * ## What the host enforces
+ *
+ * Data is hard-scoped to the plugin id — a plugin only ever sees its own — and the host validates that the
+ * scope exists. Access is what your **manifest** declares:
  *
- * Data is hard-scoped to the plugin id — a plugin can only ever see its own. Reads are gated by the
- * slot's `visibleTo`, writes require the mapped {@link Role}, and the host validates that the scope
- * exists. A write is plain persistence: no plugin code runs at request time, so anything derived or
- * validated server-side must be precomputed in the backend's `register`/`onSchedule` and read back from
- * the store.
+ * ```json
+ * "data": { "readableBy": "fan", "writableBy": "podcaster" }
+ * ```
+ *
+ * Values are `anonymous | fan | podcaster | admin` ({@link Role} plus `anonymous`, the absence of one);
+ * `writableBy` may not be `anonymous`, and if the block is absent `readableBy` falls back to the *write*
+ * floor rather than to anonymous — saying nothing gets the safe answer. A slot's `visibleTo` governs
+ * **rendering only**; it never governed data access, and inferring the data floor from unrelated UI slots
+ * is exactly what once let a plugin with one anonymous slot expose its whole store. Watch the default: a
+ * plugin with an anonymous slot and no `data` block loses its anonymous reads (403) until it declares
+ * `"readableBy": "anonymous"`. **Neither floor applies to the `user` scope:** no floor makes someone
+ * else's partition readable, none stands between a caller and their own, and `writableBy` does not gate it
+ * either — a write floor protects the *shared* surface, and a user partition is unshared. Any
+ * authenticated caller reads and writes their own `data/user/me/…` whatever the manifest declares.
+ *
+ * A write is plain persistence: no plugin code runs at request time, so anything derived or validated
+ * server-side must be precomputed in the backend's `register`/`onSchedule` and read back from the store.
  *
  * Custom plugin-defined server routes may arrive in a later `platformApi` version; v1 plugins use the
  * doc store.
  *
  * @example Read, list, write and remove docs from a Web Component
  * ```ts
- * const base = `data/${ctx.scope.type}/${ctx.scope.id}`;   // scope.id is `main` on the site scope
- * const key = `board:${ctx.user!.id}`;                     // no `/` in keys
+ * const mine = `data/user/${SELF_SCOPE_ID}`;               // the caller's own partition
+ * const shared = `data/${ctx.scope.type}/${ctx.scope.id}`; // scope.id is `main` on the site scope
+ * const key = `mark:${ctx.scope.id}`;                      // no `/` in keys
  *
- * const board = await ctx.api.get<Board>(`${base}/${key}`);   // rejects with a 404 problem if absent
- * await ctx.api.put(`${base}/${key}`, { ...board, marked });  // upsert, last-write-wins
+ * const marks = await ctx.api.get<Marks>(`${mine}/${key}`);   // rejects with a 404 problem if absent
+ * await ctx.api.put(`${mine}/${key}`, { ...marks, b3: true }); // upsert, last-write-wins
  *
- * const page = await ctx.api.get<PagedDocs<Board>>(`${base}?prefix=board:&page=0&size=50`);
+ * const page = await ctx.api.get<PagedDocs<Marks>>(`${mine}?prefix=mark:&page=0&size=50`);
  * page.items.forEach(({ key, value }) => render(key, value));
  *
- * await ctx.api.delete(`${base}/${key}`);                     // idempotent
+ * await ctx.api.delete(`${mine}/${key}`);                     // idempotent
+ *
+ * // A leaderboard is not built here: the backend aggregates every user's marks with
+ * // queryAcrossUsers(...) and writes the result to `${shared}/leaderboard` for this component to read.
+ * const board = await ctx.api.get<Leaderboard>(`${shared}/leaderboard`);
  * ```
  */
 export interface PluginApiClient {
@@ -200,15 +281,230 @@ export interface DisplaySnapshot {
  * @returns the resolved artwork URL, or `undefined` when neither the episode nor the feed declares one
  */
 export declare function resolveArtwork(snapshot: DisplaySnapshot): string | undefined;
+/**
+ * The consent gate for anything that stores data on the visitor's device or talks to a third party
+ * (ARCHITECTURE §12.5).
+ *
+ * Consent is **denied until granted**. The core itself runs banner-free — strictly necessary cookies need
+ * no consent — so the only reason a visitor ever sees a consent prompt is a plugin that asked for one.
+ * Treat that as the cost it is.
+ *
+ * The categories are declared per service in your manifest's `consent.services[]` (`necessary`,
+ * `functional`, `analytics`, or one you declare yourself). The host builds the cookie notice from those
+ * declarations, and the `hosts` you list there are also the CSP allow-list: **an origin you did not
+ * declare stays blocked even after consent is given.**
+ *
+ * ## The decision is per category, not per service
+ *
+ * `consent.services[]` is richly per-service — `provider`, `privacyUrl`, `thirdCountryTransfer`, each
+ * `storage[]` item — but every method here takes a **category**. That asymmetry is deliberate and worth
+ * stating plainly, because the schema implies otherwise: **services describe, categories decide.** The
+ * per-service detail exists so the notice can name who stores what for how long; the thing a visitor
+ * actually toggles is the category.
+ *
+ * The consequence: if two plugins each declare a service under `analytics` with different providers, the
+ * visitor sees **one** decision listing both plugins, and granting it grants both. There is no way to
+ * consent to one provider and withhold the other. Do not build a UI that implies otherwise, and don't
+ * assume `has('analytics')` says anything about *which* provider was accepted — it says the category was.
+ *
+ * If you need a visitor to be able to accept one of your services and refuse another, declare them under
+ * **different categories** (a plugin-declared category is allowed, it just has no translated label in the
+ * shell). That is the only lever the contract gives you.
+ *
+ * ## `necessary` is never asked about
+ *
+ * `has('necessary')` is **always `true`** and the host never prompts for it — it is the category the core
+ * itself uses, and a banner-free site stays banner-free. Declaring a service as `necessary` therefore
+ * means "this loads unconditionally"; use it only for what genuinely cannot be refused, and expect
+ * `request('necessary')` to resolve `true` without showing the visitor anything.
+ *
+ * @example The click-to-load placeholder this exists for
+ * ```ts
+ * function render({ ctx, root }: { ctx: PluginContext; root: HTMLElement }) {
+ *   if (ctx.consent.has('analytics')) {
+ *     mountChart(root);
+ *     return;
+ *   }
+ *
+ *   const button = document.createElement('button');
+ *   button.textContent = 'Load chart (sets a cookie)';
+ *   button.onclick = async () => {
+ *     if (await ctx.consent.request('analytics')) mountChart(root);
+ *   };
+ *   root.append(button);
+ *
+ *   // Someone may flip the purpose in the settings page while this is mounted.
+ *   return ctx.consent.onChange(() => rerender());
+ * }
+ * ```
+ */
+export interface ConsentApi {
+    /**
+     * Whether the visitor has granted a consent category.
+     *
+     * Check it before every load of a consent-requiring resource, not once at startup — consent can be
+     * withdrawn mid-session from the host's settings page.
+     *
+     * @param category the consent category, as declared on a service in your manifest
+     * @returns `true` if the category is currently granted
+     */
+    has(category: string): boolean;
+    /**
+     * Every category currently granted.
+     *
+     * For rendering a summary ("statistics: on, embeds: off"). Prefer {@link has} for a single gate.
+     *
+     * Includes `necessary`, which is always granted. These are categories, not service ids — a granted
+     * category covers every service declared under it, across all plugins.
+     *
+     * @returns the granted category names, in no guaranteed order
+     */
+    granted(): string[];
+    /**
+     * Asks the visitor to grant a category, and resolves with their answer.
+     *
+     * The host opens its consent settings for this one purpose and resolves once the visitor decides;
+     * dismissing it resolves `false`. **Call this from a user gesture** — the click on your placeholder —
+     * and never on mount: an unprompted call turns a banner-free site into one with a banner, which is
+     * exactly what §12.5 is arranged to avoid.
+     *
+     * Resolving `true` means the category is granted from that moment on; it does not load anything for
+     * you. Load the resource yourself afterwards.
+     *
+     * ## What a caller may rely on
+     *
+     * A page full of plugin tiles will produce concurrent calls, so the contract is explicit about them:
+     *
+     * - **There is one consent surface, host-wide.** Calling this does not open a dialog of your own, and a
+     *   second call while one is already open does not open a second — it joins the one in flight. You are
+     *   asking the host to surface *its* settings, not opening a modal.
+     * - **The visitor decides every category at once.** The host's settings cover all declared categories,
+     *   so one interaction can change several. Your promise still resolves with the state of *the category
+     *   you asked for* — but other categories may have moved too, which is why {@link onChange} fires for
+     *   every change rather than only yours.
+     * - **Every call resolves exactly once, and always.** Concurrent calls are never dropped or left
+     *   pending: each resolves when the visitor completes the decision, including calls made while the
+     *   surface was already open.
+     * - **Grants are shared across plugins.** If another plugin's `request('analytics')` is what the
+     *   visitor accepted, your pending `request('analytics')` resolves `true` too — the decision is per
+     *   category and site-wide, not per plugin (see the note on granularity above).
+     *
+     * So: don't serialize your calls, don't build a queue, and don't assume the visitor only answered you.
+     * Re-read {@link has} after any change rather than caching what a request resolved with.
+     *
+     * @param category the consent category to ask for
+     * @returns whether the category is granted after the visitor decided
+     */
+    request(category: string): Promise<boolean>;
+    /**
+     * Subscribes to consent changes.
+     *
+     * Fires on **every** change to any category — including one made in the settings page while your
+     * component is mounted, and including a withdrawal. It carries no payload: re-read {@link has} or
+     * {@link granted} for the current state.
+     *
+     * @param cb called after each change
+     * @returns an {@link Unsubscribe} — return it from your render callback so the subscription dies with
+     *          the component
+     */
+    onChange(cb: () => void): Unsubscribe;
+}
+/**
+ * One item a service stores on the visitor's device, as declared in `plugin.json`.
+ *
+ * Part of {@link ConsentServiceDeclaration} — see the caveats there before using either type.
+ */
+export interface ConsentStorageDeclaration {
+    /** The cookie or storage key exactly as it appears on the device, e.g. `plausible_ignore`. */
+    name: string;
+    /** Where it is stored. */
+    type: 'cookie' | 'localStorage' | 'sessionStorage';
+    /** What it is for, in language a visitor reads — not an internal description. */
+    purpose: string;
+    /** How long it lasts: `session`, `persistent`, or a human duration such as `12 months`. */
+    duration: string;
+}
+/**
+ * The shape of one entry in your manifest's `consent.services[]`.
+ *
+ * **This type is documentation, not enforcement.** The manifest is owned and validated by the host — the
+ * SDK does not read `plugin.json`, and nothing here runs at build or load time. It exists so an author
+ * writing the declaration gets IDE completion and catches a typo before core rejects the plugin at load,
+ * which is otherwise the first feedback you get. Two consequences worth knowing:
+ *
+ * - **The host is authoritative.** If this type and core disagree, core wins. It is kept in step by hand,
+ *   so treat a mismatch as a bug in the SDK rather than permission to ignore the host.
+ * - **It is not a manifest type.** The manifest as a whole stays core-owned and the SDK will not grow one;
+ *   this covers a single nested shape that got deep enough in 0.4.0 to be worth typing.
+ *
+ * Use it by typing a literal you keep next to your manifest, or as a reference while writing the JSON:
+ *
+ * ```ts
+ * const services: ConsentServiceDeclaration[] = [{
+ *   id: 'plausible',
+ *   name: 'Plausible Analytics',
+ *   provider: 'Plausible Insights OÜ',
+ *   category: 'analytics',
+ *   privacyUrl: 'https://plausible.io/privacy',
+ *   hosts: ['https://plausible.example'],
+ *   thirdCountryTransfer: false,
+ *   storage: [{
+ *     name: 'plausible_ignore', type: 'localStorage',
+ *     purpose: 'Remembers that you opted out of statistics', duration: 'persistent',
+ *   }],
+ * }];
+ * ```
+ */
+export interface ConsentServiceDeclaration {
+    /** Stable identifier for this service within your plugin. */
+    id: string;
+    /** The service as a visitor would recognise it, e.g. `Plausible Analytics`. */
+    name: string;
+    /** The **legal entity** operating the service — the company, not your plugin. */
+    provider: string;
+    /**
+     * The consent category this service falls under, and therefore what {@link ConsentApi.has} gates on.
+     *
+     * `necessary` is never prompted for and always granted. Remember that the category — not the service —
+     * is what the visitor decides: two services sharing a category are accepted or refused together.
+     */
+    category: 'necessary' | 'functional' | 'analytics' | (string & {});
+    /** The provider's own privacy policy. */
+    privacyUrl: string;
+    /**
+     * Every origin the service is contacted on, scheme included (`https://plausible.example`).
+     *
+     * **Also the CSP allow-list**: core widens `script-src`/`frame-src`/`connect-src` by exactly these, so
+     * an undeclared or bare-hostname origin stays blocked even after consent is given.
+     */
+    hosts: string[];
+    /** Whether personal data leaves the EU/EEA. */
+    thirdCountryTransfer: boolean;
+    /** Each item the service stores on the visitor's device. */
+    storage: ConsentStorageDeclaration[];
+}
 /**
  * Everything a frontend plugin is given, set by the host on the mounted custom element
  * (ARCHITECTURE §7.5). This is the **entire** interface a plugin author must learn.
  */
 export interface PluginContext {
-    /** The scope this plugin instance is mounted in. */
+    /**
+     * The scope this plugin instance is mounted in. For the `episode` scope, `scope.id` is the episode's
+     * **public slug** (e.g. `the-sample-cast-s01e06`) — the same id used in its URL and as the doc-store
+     * partition (`data/episode/{slug}/…`), not the internal UUID.
+     */
     scope: Scope;
-    /** The `EpisodeRef` ids in scope, resolved (and access-filtered) by the host. */
+    /**
+     * The episode ids in scope, resolved (and access-filtered) by the host — the public **slugs** (the same
+     * values used in URLs and doc-store paths). Pair with {@link episodeLabels} for display.
+     */
     episodes: string[];
+    /**
+     * Human-readable labels for {@link episodes}, keyed by slug (e.g. `"S01E06 · The Lighthouse…"`). The host
+     * builds them from the feed's season/episode + title; use them in pickers so users see titles, not slugs.
+     * Optional: absent (or partial) when the host does not provide a label for a given episode.
+     */
+    episodeLabels?: Record<string, string>;
     /** Present on the `episode` scope: lifecycle status of the current episode. */
     episode?: {
         status: 'PLANNED' | 'PUBLISHED' | 'WITHDRAWN';
@@ -224,31 +520,68 @@ export interface PluginContext {
      * uses via `ctx.store()`. See {@link PluginApiClient} for the endpoint shape and access rules.
      */
     api: PluginApiClient;
-    /** Cookie/consent gate for third-party resources (ARCHITECTURE §12.5). */
-    consent: {
-        has(cat: string): boolean;
-        onChange(cb: () => void): void;
-    };
-    /** Read-only access to the host's URL filter state (ARCHITECTURE §6.1). */
+    /**
+     * Writes one line to the host's log, attributed to this plugin.
+     *
+     * The counterpart of the backend's `ctx.logger()`, and the **only** supported way for a frontend
+     * component to log to the host — do not POST to `/api/plugins/{id}/log` through {@link api}, which is a
+     * data endpoint. The host attributes the entry to your plugin, stores `info` and above, surfaces `warn`
+     * and above in the admin log viewer, and rate-limits this path: a render loop logging per frame will be
+     * throttled, not stored.
+     *
+     * Messages are read by site operators, not by you — they land next to core's own output. Keep them
+     * short, and keep personal data out of them.
+     *
+     * @param level   the severity
+     * @param message the message; already-formatted, since there is no placeholder syntax here
+     *
+     * @example
+     * ```ts
+     * ctx.log('warn', `no board for episode ${ctx.scope.id}`);
+     * ```
+     */
+    log(level: LogLevel, message: string): void;
+    /** Cookie/consent gate for third-party resources — see {@link ConsentApi} (ARCHITECTURE §12.5). */
+    consent: ConsentApi;
+    /**
+     * Read-only access to the host's URL filter state (ARCHITECTURE §6.1).
+     *
+     * Plugins *consume* filters, they never define them: the axes (season, tags, sorting) belong to the
+     * host and live in the URL. `onChange` returns an {@link Unsubscribe}.
+     */
     filter: {
         current(): FilterState;
-        onChange(cb: (f: FilterState) => void): void;
+        onChange(cb: (f: FilterState) => void): Unsubscribe;
     };
-    /** Player position + control, for sync plugins (ARCHITECTURE §6.5). */
+    /**
+     * Player position + control, for sync plugins (ARCHITECTURE §6.5).
+     *
+     * `on` returns an {@link Unsubscribe} — player events outlive a single render, so detaching matters
+     * here more than anywhere else on this context.
+     */
     player: {
         currentTime(): number;
         seekTo(s: number): void;
-        on(ev: string, cb: (...args: unknown[]) => void): void;
+        on(ev: string, cb: (...args: unknown[]) => void): Unsubscribe;
     };
-    /** The subpath under `/p/<pluginId>/`, for deep-linkable plugin content (ARCHITECTURE §6.4). */
+    /**
+     * The subpath under `/p/<pluginId>/`, for deep-linkable plugin content (ARCHITECTURE §6.4).
+     *
+     * `onChange` returns an {@link Unsubscribe}.
+     */
     route: {
         path: string;
-        onChange(cb: (p: string) => void): void;
+        onChange(cb: (p: string) => void): Unsubscribe;
     };
-    /** The active UI locale (ARCHITECTURE §12.7). */
+    /**
+     * The active UI locale (ARCHITECTURE §12.7).
+     *
+     * `onChange` returns an {@link Unsubscribe}. {@link createPluginI18n} subscribes to this for you and
+     * hands back a `dispose` to undo it.
+     */
     locale: {
         current(): string;
-        onChange(cb: (l: string) => void): void;
+        onChange(cb: (l: string) => void): Unsubscribe;
     };
     /** Core listening progress in seconds, or `null` if unknown (ARCHITECTURE §6.5). */
     progress: {
@@ -306,6 +639,14 @@ export interface PluginI18n {
     t(key: string, params?: Record<string, string | number>): string;
     /** The currently active locale code. */
     readonly locale: string;
+    /**
+     * Detaches the translator from `ctx.locale`.
+     *
+     * A translator subscribes to locale changes for its whole life. Call this when the component that owns
+     * it goes away — from the cleanup callback your render returns — or the subscription keeps a dead
+     * translator alive.
+     */
+    dispose(): void;
 }
 /**
  * Creates a plugin-local translator bound to the host's active locale (ARCHITECTURE §12.7).
@@ -314,6 +655,9 @@ export interface PluginI18n {
  * change — the same convention as the shell, no extra i18n library required. English (`en`) is the
  * source language and the fallback.
  *
+ * The translator subscribes to `locale.onChange` for as long as it lives — call {@link PluginI18n.dispose}
+ * from your render's cleanup callback when the component goes away.
+ *
  * @param catalogs catalogs keyed by locale code
  * @param locale   the host locale handle, i.e. `ctx.locale`; its `onChange` drives re-selection
  * @returns a translator whose `t` and `locale` reflect the currently active locale

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -13,10 +13,24 @@
  * The plugin contract version (SemVer).
  *
  * Mirror of the Java `dev.mosaicast.plugin.api.PlatformApi.VERSION` constant and the npm package
- * version. The host rejects a plugin whose manifest `platformApi` is incompatible with this value
- * (ARCHITECTURE §7.2). **These move together — a breaking change is a major bump.**
+ * version — **these move together**, and CI fails the build if they drift.
+ *
+ * The host compares a plugin manifest's `platformApi` against this value on **`major.minor` exactly** and
+ * rejects a mismatch at startup (ARCHITECTURE §7.2). While the SDK is pre-1.0 a breaking change is
+ * therefore a *minor* bump; from `1.0.0` on, breaking means major.
  */
-export const PLATFORM_API_VERSION = '0.3.0';
+export const PLATFORM_API_VERSION = '0.5.0';
+/**
+ * The id every `user` data path carries: the literal `me`, mirroring the Java `Scope.SELF_ID`.
+ *
+ * The host resolves it from the session, so `data/user/me/{key}` reaches the calling user's partition and
+ * no one else's. **Any other `user` id is a 400**, never a silent substitution, and an anonymous request
+ * to a `user` path is a 401 — with no session there is no partition. Per-user data belongs here rather
+ * than in a key like `mark:<userId>:cell`, which the host cannot enforce because the client supplies it.
+ *
+ * @since 0.5.0
+ */
+export const SELF_SCOPE_ID = 'me';
 /**
  * The artwork to display for an episode: its own {@link DisplaySnapshot.imageUrl} if present, otherwise
  * the {@link DisplaySnapshot.feedImageUrl feed cover}, otherwise `undefined`.
@@ -120,19 +134,27 @@ function interpolate(template, params) {
  * change — the same convention as the shell, no extra i18n library required. English (`en`) is the
  * source language and the fallback.
  *
+ * The translator subscribes to `locale.onChange` for as long as it lives — call {@link PluginI18n.dispose}
+ * from your render's cleanup callback when the component goes away.
+ *
  * @param catalogs catalogs keyed by locale code
  * @param locale   the host locale handle, i.e. `ctx.locale`; its `onChange` drives re-selection
  * @returns a translator whose `t` and `locale` reflect the currently active locale
  */
 export function createPluginI18n(catalogs, locale) {
     let active = locale.current();
-    locale.onChange((l) => {
+    const unsubscribe = locale.onChange((l) => {
         active = l;
     });
     return {
         get locale() {
             return active;
         },
+        dispose() {
+            // Optional call: a host built against 0.3.x returns nothing here, and a translator that cannot be
+            // disposed is better than one that throws while a component is tearing down.
+            unsubscribe?.();
+        },
         t(key, params) {
             const template = catalogs[active]?.[key] ?? catalogs[SOURCE_LOCALE]?.[key] ?? key;
             return interpolate(template, params);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -6,7 +6,14 @@
  *
  * @packageDocumentation
  */
-import type { PluginApiClient, PluginContext, ThemeTokens } from './index.js';
+import type { ConsentApi, LogLevel, PluginApiClient, PluginContext, ThemeTokens } from './index.js';
+/** One recorded {@link PluginContext.log} call. */
+export interface LogRecord {
+    /** The severity it was logged at. */
+    level: LogLevel;
+    /** The logged message. */
+    message: string;
+}
 /** One recorded {@link MockApiClient} call. */
 export interface RecordedCall {
     /** HTTP method, lowercase. */
@@ -26,8 +33,66 @@ export interface MockApiClient extends PluginApiClient {
      */
     responses: Record<string, unknown>;
 }
+/** A {@link ConsentApi} whose grants a test can drive. */
+export interface MockConsent extends ConsentApi {
+    /** Grants a category and notifies subscribers. Granting an already-granted category does nothing. */
+    grant(category: string): void;
+    /**
+     * Withdraws a category and notifies subscribers, as the host's settings page can mid-session.
+     *
+     * Revoking `necessary` does nothing — the host cannot withdraw it either.
+     */
+    revoke(category: string): void;
+    /** Every category passed to {@link ConsentApi.request}, in order. */
+    readonly requests: string[];
+    /**
+     * What {@link ConsentApi.request} resolves with — i.e. what the visitor decides.
+     *
+     * `false` by default: the visitor says no. Set it to `true` to test the accepted path, which also
+     * grants the category as the host would.
+     */
+    autoGrantOnRequest: boolean;
+}
+/**
+ * Builds a {@link ConsentApi} for tests, **denying everything** unless told otherwise.
+ *
+ * Deny is the default on purpose. The host denies until granted, so a component written against a
+ * permissive mock is a component whose placeholder path was never exercised — and that path is the entire
+ * point of the consent contract (ARCHITECTURE §12.5).
+ *
+ * The one exception is `necessary`, which is granted from the start and cannot be revoked in the host
+ * either — it is the category the core itself uses.
+ *
+ * @param initial categories granted from the start, on top of `necessary`
+ * @returns a consent double with `grant`/`revoke` and a recorded `requests` list
+ *
+ * @example
+ * ```ts
+ * const consent = makeMockConsent();
+ * const ctx = makeMockCtx({ consent });
+ *
+ * mount(ctx);                      // renders the click-to-load placeholder
+ * consent.autoGrantOnRequest = true;
+ * await clickPlaceholder();
+ * expect(consent.requests).toEqual(['analytics']);
+ *
+ * consent.revoke('analytics');     // fires onChange; the component should go back to the placeholder
+ * ```
+ */
+export declare function makeMockConsent(initial?: string[]): MockConsent;
 /** Default theme tokens (neutral light values) used when a test does not override them. */
 export declare const DEFAULT_THEME: ThemeTokens;
+/** A {@link PluginContext} wired for tests: the mock `api` and the recorded `log` calls are reachable. */
+export type MockPluginContext = PluginContext & {
+    /** The recording client every `api` call goes through. */
+    api: MockApiClient;
+    /**
+     * Every {@link PluginContext.log} call, in order.
+     *
+     * Stays empty if you override `log` yourself — the recording lives in the default implementation.
+     */
+    logs: LogRecord[];
+};
 /** Overrides accepted by {@link makeMockCtx}. */
 export interface MockCtxOverrides extends Partial<Omit<PluginContext, 'api'>> {
     /** Canned responses for the mock `api`, keyed as described on {@link MockApiClient.responses}. */
@@ -38,14 +103,18 @@ export interface MockCtxOverrides extends Partial<Omit<PluginContext, 'api'>> {
 /**
  * Builds a {@link PluginContext} wired with in-memory doubles for unit tests.
  *
- * Defaults: `site` scope, no episodes, anonymous user, all consent denied, empty filter, a player
+ * Defaults: `site` scope, no episodes, anonymous user, **all consent denied** (a {@link makeMockConsent}
+ * double — pass your own to drive grants), empty filter, a player
  * parked at 0s, empty route, `en` locale, unknown progress, and {@link DEFAULT_THEME}. Pass overrides to
- * change any field; the returned `api` is a {@link MockApiClient} recording every call.
+ * change any field; the returned `api` is a {@link MockApiClient} recording every call, and `logs`
+ * collects every `ctx.log(...)`.
+ *
+ * `episodeLabels` is deliberately **absent** by default. It is optional on the real context and the host
+ * may supply it partially, so a component that renders labels has to survive their absence — the mock
+ * makes you face that unless you pass labels in.
  *
  * @param overrides partial context plus optional `apiResponses`
- * @returns a full context whose `api` is a {@link MockApiClient}
+ * @returns a full context whose `api` is a {@link MockApiClient} and whose `log` calls are recorded
  */
-export declare function makeMockCtx(overrides?: MockCtxOverrides): PluginContext & {
-    api: MockApiClient;
-};
+export declare function makeMockCtx(overrides?: MockCtxOverrides): MockPluginContext;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAC/B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAoBD,2FAA2F;AAC3F,eAAO,MAAM,aAAa,EAAE,WAS3B,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAC3E,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,kFAAkF;IAClF,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,gBAAqB,GAAG,aAAa,GAAG;IAAE,GAAG,EAAE,aAAa,CAAA;CAAE,CAoBpG"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EAEV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAC/B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAuBD,0DAA0D;AAC1D,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,qGAAqG;IACrG,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,MAAM,EAAO,GAAG,WAAW,CAwCnE;AAED,2FAA2F;AAC3F,eAAO,MAAM,aAAa,EAAE,WAS3B,CAAC;AAEF,0GAA0G;AAC1G,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,0DAA0D;IAC1D,GAAG,EAAE,aAAa,CAAC;IACnB;;;;OAIG;IACH,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAC3E,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,kFAAkF;IAClF,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,gBAAqB,GAAG,iBAAiB,CA2B/E"}

package/dist/testing.js

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 The Mosaicast Authors
+/** The unsubscribe returned by the inert `onChange` doubles — there is nothing to detach. */
+const noop = () => { };
 function makeMockApi(responses) {
     const calls = [];
     const resolve = (method, path, body) => {
@@ -17,6 +19,72 @@ function makeMockApi(responses) {
     };
     return api;
 }
+/**
+ * Builds a {@link ConsentApi} for tests, **denying everything** unless told otherwise.
+ *
+ * Deny is the default on purpose. The host denies until granted, so a component written against a
+ * permissive mock is a component whose placeholder path was never exercised — and that path is the entire
+ * point of the consent contract (ARCHITECTURE §12.5).
+ *
+ * The one exception is `necessary`, which is granted from the start and cannot be revoked in the host
+ * either — it is the category the core itself uses.
+ *
+ * @param initial categories granted from the start, on top of `necessary`
+ * @returns a consent double with `grant`/`revoke` and a recorded `requests` list
+ *
+ * @example
+ * ```ts
+ * const consent = makeMockConsent();
+ * const ctx = makeMockCtx({ consent });
+ *
+ * mount(ctx);                      // renders the click-to-load placeholder
+ * consent.autoGrantOnRequest = true;
+ * await clickPlaceholder();
+ * expect(consent.requests).toEqual(['analytics']);
+ *
+ * consent.revoke('analytics');     // fires onChange; the component should go back to the placeholder
+ * ```
+ */
+export function makeMockConsent(initial = []) {
+    // `necessary` is what the core itself uses: always granted, never prompted for. Seeding it means a
+    // component gated on it behaves in tests the way it will in the host.
+    const granted = new Set(['necessary', ...initial]);
+    const subscribers = new Set();
+    const requests = [];
+    const notify = () => {
+        subscribers.forEach((cb) => cb());
+    };
+    return {
+        requests,
+        autoGrantOnRequest: false,
+        has: (category) => granted.has(category),
+        granted: () => [...granted],
+        request(category) {
+            requests.push(category);
+            if (this.autoGrantOnRequest && !granted.has(category)) {
+                granted.add(category);
+                notify();
+            }
+            return Promise.resolve(granted.has(category));
+        },
+        grant(category) {
+            if (!granted.has(category)) {
+                granted.add(category);
+                notify();
+            }
+        },
+        revoke(category) {
+            // The host cannot withdraw `necessary`, so neither can the double.
+            if (category !== 'necessary' && granted.delete(category)) {
+                notify();
+            }
+        },
+        onChange(cb) {
+            subscribers.add(cb);
+            return () => subscribers.delete(cb);
+        },
+    };
+}
 /** Default theme tokens (neutral light values) used when a test does not override them. */
 export const DEFAULT_THEME = {
     bg: '#ffffff',
@@ -31,30 +99,43 @@ export const DEFAULT_THEME = {
 /**
  * Builds a {@link PluginContext} wired with in-memory doubles for unit tests.
  *
- * Defaults: `site` scope, no episodes, anonymous user, all consent denied, empty filter, a player
+ * Defaults: `site` scope, no episodes, anonymous user, **all consent denied** (a {@link makeMockConsent}
+ * double — pass your own to drive grants), empty filter, a player
  * parked at 0s, empty route, `en` locale, unknown progress, and {@link DEFAULT_THEME}. Pass overrides to
- * change any field; the returned `api` is a {@link MockApiClient} recording every call.
+ * change any field; the returned `api` is a {@link MockApiClient} recording every call, and `logs`
+ * collects every `ctx.log(...)`.
+ *
+ * `episodeLabels` is deliberately **absent** by default. It is optional on the real context and the host
+ * may supply it partially, so a component that renders labels has to survive their absence — the mock
+ * makes you face that unless you pass labels in.
  *
  * @param overrides partial context plus optional `apiResponses`
- * @returns a full context whose `api` is a {@link MockApiClient}
+ * @returns a full context whose `api` is a {@link MockApiClient} and whose `log` calls are recorded
  */
 export function makeMockCtx(overrides = {}) {
     const { apiResponses, api, ...rest } = overrides;
     const mockApi = api ?? makeMockApi(apiResponses ?? {});
     const filter = rest.filter?.current() ?? {};
+    const logs = [];
     const base = {
         scope: { type: 'site', id: 'main' },
         episodes: [],
         user: null,
         api: mockApi,
-        consent: { has: () => false, onChange: () => { } },
-        filter: { current: () => filter, onChange: () => { } },
-        player: { currentTime: () => 0, seekTo: () => { }, on: () => { } },
-        route: { path: '', onChange: () => { } },
-        locale: { current: () => 'en', onChange: () => { } },
+        logs,
+        log: (level, message) => {
+            logs.push({ level, message });
+        },
+        consent: makeMockConsent(),
+        // The no-op handles still return a working unsubscribe, so a component that detaches on cleanup
+        // behaves the same against the mock as against the host.
+        filter: { current: () => filter, onChange: () => noop },
+        player: { currentTime: () => 0, seekTo: () => { }, on: () => noop },
+        route: { path: '', onChange: () => noop },
+        locale: { current: () => 'en', onChange: () => noop },
         progress: { get: () => Promise.resolve(null) },
         theme: DEFAULT_THEME,
     };
-    return { ...base, ...rest, api: mockApi };
+    return { ...base, ...rest, api: mockApi, logs };
 }
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicast/plugin-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Versioned plugin contract for Mosaicast: the frontend PluginContext types, a Web Component base helper, an i18n helper, plus a test kit under the /testing subpath.",
   "license": "Apache-2.0",
   "repository": {