@aiaiai-pt/design-system 0.33.0 → 0.34.0

package/components/renderer/ResultsChartWidget.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+  import ResultsChart from "../ResultsChart.svelte";
+  import type { WidgetProps } from "./types";
+  import { toRankedItems } from "./aggregate";
+
+  // `results-chart` widget (#105 Phase 4) — a bar chart over a public aggregate
+  // VIEW that SHIPS its data table (ARTE #3/#6: a chart is never the only
+  // encoding). Type-ranked on `kind: "aggregate"` (out-ranks the board default)
+  // so a `type: "results-chart"` block renders the chart while the bare kind
+  // renders the board. Vertical-agnostic: `props.label_field` / `value_field`
+  // name the view columns; `props.label_header` / `value_header` localise the
+  // table headers. Soft-empty on no rows (optional slot). Flush band.
+  let { data, props, ownsH1, locale }: WidgetProps = $props();
+
+  const rows = $derived(
+    data && typeof data === "object" && Array.isArray((data as { items?: unknown }).items)
+      ? ((data as { items: Record<string, unknown>[] }).items)
+      : [],
+  );
+
+  const labelField = $derived(
+    typeof props.label_field === "string" && props.label_field
+      ? props.label_field
+      : "label",
+  );
+  const valueField = $derived(
+    typeof props.value_field === "string" && props.value_field
+      ? props.value_field
+      : "value",
+  );
+  const limit = $derived(
+    typeof props.limit === "number" && props.limit > 0 ? props.limit : 0,
+  );
+
+  const items = $derived(
+    toRankedItems(rows, { labelField, valueField, limit }),
+  );
+
+  const heading = $derived(
+    typeof props.title === "string" && props.title ? props.title : "",
+  );
+  const caption = $derived(heading || "Results");
+  const labelHeader = $derived(
+    typeof props.label_header === "string" && props.label_header
+      ? props.label_header
+      : "Item",
+  );
+  const valueHeader = $derived(
+    typeof props.value_header === "string" && props.value_header
+      ? props.value_header
+      : "Value",
+  );
+</script>
+
+{#if items.length > 0}
+  <section class="widget-band">
+    {#if heading}
+      {#if ownsH1}<h1>{heading}</h1>{:else}<h2>{heading}</h2>{/if}
+    {/if}
+    <ResultsChart
+      {items}
+      {caption}
+      {labelHeader}
+      {valueHeader}
+      locale={locale ?? "en"}
+    />
+  </section>
+{/if}
+
+<style>
+  .widget-band {
+    width: 100%;
+    max-width: var(--content-width-narrow);
+    margin-inline: auto;
+    padding-inline: var(--content-padding-x);
+  }
+</style>

package/components/renderer/ResultsChartWidget.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { WidgetProps } from "./types";
+declare const ResultsChartWidget: import("svelte").Component<WidgetProps, {}, "">;
+type ResultsChartWidget = ReturnType<typeof ResultsChartWidget>;
+export default ResultsChartWidget;

package/components/renderer/StatGridWidget.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+  import StatGrid from "../StatGrid.svelte";
+  import StatCard from "../StatCard.svelte";
+  import type { WidgetProps } from "./types";
+
+  // `kpi` widget — public stat grid (counts, KPIs). Adapts a list of stat
+  // items into DS StatCards inside a StatGrid. The public KPI read endpoint is
+  // not wired yet (resolveData fails closed for `kind: "kpi"`); registered here
+  // and fed once a slice adds the surface. Defensive over `data` (live) /
+  // `props` (seeded preview).
+  let { data, props }: WidgetProps = $props();
+
+  interface Stat {
+    label?: string;
+    value?: string;
+    variant?: string;
+  }
+
+  const view = $derived((data ?? {}) as Record<string, unknown>);
+  const stats = $derived<Stat[]>(
+    (Array.isArray(view.stats)
+      ? view.stats
+      : Array.isArray(props.stats)
+        ? props.stats
+        : []) as Stat[],
+  );
+</script>
+
+<StatGrid>
+  {#each stats as stat (stat.label)}
+    <StatCard label={stat.label} value={stat.value} variant={stat.variant} />
+  {/each}
+</StatGrid>

package/components/renderer/StatGridWidget.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { WidgetProps } from "./types";
+declare const StatGridWidget: import("svelte").Component<WidgetProps, {}, "">;
+type StatGridWidget = ReturnType<typeof StatGridWidget>;
+export default StatGridWidget;

package/components/renderer/aggregate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Aggregate-view row shaping (#105 Phase 4) — PURE, vertical-agnostic.
+ *
+ * Turns the rows of a public aggregate VIEW (served by the BFF public-view lane,
+ * #250 M3 — `{ items: [{ <label_field>, <value_field>, … }] }`) into the
+ * `{ label, value }` shape the DS `RankingBoard` / `ResultsChart` render, sorted
+ * by value descending and optionally capped. Nothing here is civic-specific:
+ * the label/value columns are config (`label_field` / `value_field`), so any
+ * `group_by + count/sum` view (votes per proposal, reports per category,
+ * consumption per meter) becomes a chart/board from config alone.
+ *
+ * Coercion is deliberate and fail-soft: a missing/blank label falls back to the
+ * empty string (the widget decides whether to drop it), a non-numeric value
+ * coerces to 0 — an aggregate read never throws on a stray row.
+ */
+export interface RankedItem {
+    label: string;
+    value: number;
+}
+export interface ToRankedOptions {
+    /** Key in each row holding the category label. Default `label`. */
+    labelField?: string;
+    /** Key holding the numeric aggregate. Default `value`. */
+    valueField?: string;
+    /** Cap the result to the top-N after sorting. 0/absent → no cap. */
+    limit?: number;
+    /** Drop rows whose label coerces to empty. Default true. */
+    dropBlankLabels?: boolean;
+}
+/**
+ * Map raw view rows → sorted `{ label, value }`. Stable sort by value desc
+ * (ties keep input order); rows are never mutated.
+ */
+export declare function toRankedItems(rows: ReadonlyArray<Record<string, unknown>>, opts?: ToRankedOptions): RankedItem[];

package/components/renderer/aggregate.ts

@@ -0,0 +1,72 @@
+/**
+ * Aggregate-view row shaping (#105 Phase 4) — PURE, vertical-agnostic.
+ *
+ * Turns the rows of a public aggregate VIEW (served by the BFF public-view lane,
+ * #250 M3 — `{ items: [{ <label_field>, <value_field>, … }] }`) into the
+ * `{ label, value }` shape the DS `RankingBoard` / `ResultsChart` render, sorted
+ * by value descending and optionally capped. Nothing here is civic-specific:
+ * the label/value columns are config (`label_field` / `value_field`), so any
+ * `group_by + count/sum` view (votes per proposal, reports per category,
+ * consumption per meter) becomes a chart/board from config alone.
+ *
+ * Coercion is deliberate and fail-soft: a missing/blank label falls back to the
+ * empty string (the widget decides whether to drop it), a non-numeric value
+ * coerces to 0 — an aggregate read never throws on a stray row.
+ */
+
+export interface RankedItem {
+  label: string;
+  value: number;
+}
+
+export interface ToRankedOptions {
+  /** Key in each row holding the category label. Default `label`. */
+  labelField?: string;
+  /** Key holding the numeric aggregate. Default `value`. */
+  valueField?: string;
+  /** Cap the result to the top-N after sorting. 0/absent → no cap. */
+  limit?: number;
+  /** Drop rows whose label coerces to empty. Default true. */
+  dropBlankLabels?: boolean;
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+/**
+ * Map raw view rows → sorted `{ label, value }`. Stable sort by value desc
+ * (ties keep input order); rows are never mutated.
+ */
+export function toRankedItems(
+  rows: ReadonlyArray<Record<string, unknown>>,
+  opts: ToRankedOptions = {},
+): RankedItem[] {
+  const labelField = opts.labelField || "label";
+  const valueField = opts.valueField || "value";
+  const dropBlank = opts.dropBlankLabels !== false;
+
+  const mapped = rows.map((row) => ({
+    label: row[labelField] == null ? "" : String(row[labelField]),
+    value: toNumber(row[valueField]),
+  }));
+
+  const kept = dropBlank ? mapped.filter((it) => it.label !== "") : mapped;
+
+  // Stable desc sort: decorate with the original index so equal values keep
+  // their input order (Array.prototype.sort is spec-stable, but the index tie-
+  // break documents the intent and is robust to value-equality edge cases).
+  const sorted = kept
+    .map((it, i) => ({ it, i }))
+    .sort((a, b) => b.it.value - a.it.value || a.i - b.i)
+    .map(({ it }) => it);
+
+  return opts.limit && opts.limit > 0
+    ? sorted.slice(0, Math.floor(opts.limit))
+    : sorted;
+}

package/components/renderer/data-provider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * DataProvider — the host-injected data transport seam (#492 P0).
+ *
+ * Each host (portal, admin) owns its own DataProvider. The portal constructs a
+ * `createPublicDataProvider` that routes through the auth-optional `/bff` proxy.
+ * A future admin host constructs its own provider over the RLS-authenticated
+ * entity-proxy lane. `resolveData` depends only on this interface, never on
+ * the proxy prefix or the tenant/app segment directly.
+ */
+import type { Binding } from "./types";
+import type { FetchLike } from "./resolve-data";
+import type { VoteReadConfig } from "./vote";
+export interface DataUrlOpts {
+    /** Calendar window injected from `now` (73e) — applied only for the `calendar` kind. */
+    calendarWindow?: {
+        start: string;
+        end: string;
+    };
+    /** URL facet/search params forwarded from the page URL (#308) — applied for `list`/`map`. */
+    filterParams?: Record<string, string>;
+}
+/**
+ * SECURITY INVARIANT (never remove this comment):
+ * Each host owns its own DataProvider and its own security boundary. The
+ * portal's DataProvider routes through the public /bff proxy (auth-optional,
+ * SSRF-pinned to /{app}/public/). A future admin DataProvider routes through
+ * the RLS-authenticated entity-proxy lane. NEVER share one transport across
+ * both hosts. NEVER let a public widget read through an authed token, nor
+ * expose the authed lane through the public proxy. A "simplification" that
+ * collapses the two providers is a tenant/RLS leak.
+ */
+export interface DataProvider {
+    /**
+     * The raw data path for the binding, with calendar window and filter params
+     * applied. Returns `null` for unmappable bindings (caller fails closed).
+     * The path is the PAGEABLE surface: widgets re-fetch it client-side with
+     * `?after=` for "load more". It does NOT include the proxy prefix — the
+     * provider's `fetch` adds the prefix on the outbound call.
+     */
+    dataUrl(binding: Binding, opts?: DataUrlOpts): string | null;
+    /**
+     * The entity schema path for the binding. Returns `null` for kinds that
+     * carry no schema (content, map, calendar, …). The path does NOT include
+     * the proxy prefix.
+     */
+    schemaUrl(binding: Binding): string | null;
+    /**
+     * The authed account lane URL for the given path segment.
+     * Returns `/me/{segment}` — NO `/bff` prefix. This is a different security
+     * boundary (require_auth + OWN-scoped) from the public `/bff` surface.
+     */
+    accountUrl(segment: string): string;
+    /**
+     * The option-view read URL (for subscription scope dropdowns, #252).
+     * Returns the FULL URL including the proxy prefix.
+     */
+    optionViewUrl(view: string, limit: number): string;
+    /** Edition read path for the `vote` ballot composer. Full URL. */
+    voteEditionUrl(cfg: VoteReadConfig, editionId: string): string;
+    /** Options read path for the `vote` ballot composer. Full URL. */
+    voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string;
+    /** The fetch transport. Accepts any URL returned by the methods above. */
+    fetch: FetchLike;
+}
+/**
+ * Construct the portal's public DataProvider.
+ *
+ * Reproduces today's `resolveData` URL behavior byte-for-byte:
+ *   - `dataUrl` / `schemaUrl` return the raw `/{app}/public/...` path (no
+ *     `/bff` prefix). The provider's `fetch` adds `/bff` on the outbound call
+ *     so the raw path is also the pageable `dataPath` the widgets store.
+ *   - `accountUrl` returns `/me/{segment}` — the authed lane, never proxied
+ *     through `/bff`. The provider's `fetch` passes `/me/...` through as-is.
+ *   - `optionViewUrl`, `voteEditionUrl`, `voteOptionsUrl` return the full URL
+ *     already including `/bff`. The provider's `fetch` passes them through.
+ *
+ * The `fetch` wrapper decides by prefix: `/bff/` and `/me/` are passed
+ * through unchanged; anything else (raw `/{app}/public/...` paths) gets
+ * `/bff` prepended. This keeps the `fetch` self-contained in the provider —
+ * `resolveData` never sees or constructs a proxy prefix.
+ */
+export declare function createPublicDataProvider(app: string, fetchImpl: FetchLike): DataProvider;

package/components/renderer/data-provider.ts

@@ -0,0 +1,162 @@
+/**
+ * DataProvider — the host-injected data transport seam (#492 P0).
+ *
+ * Each host (portal, admin) owns its own DataProvider. The portal constructs a
+ * `createPublicDataProvider` that routes through the auth-optional `/bff` proxy.
+ * A future admin host constructs its own provider over the RLS-authenticated
+ * entity-proxy lane. `resolveData` depends only on this interface, never on
+ * the proxy prefix or the tenant/app segment directly.
+ */
+
+import type { Binding } from "./types";
+import type { FetchLike } from "./resolve-data";
+import type { VoteReadConfig } from "./vote";
+import {
+  bffPathForBinding,
+  schemaPathForBinding,
+  appendQuery,
+} from "./resolve-data";
+import { editionReadPath, optionsReadPath } from "./vote";
+
+export interface DataUrlOpts {
+  /** Calendar window injected from `now` (73e) — applied only for the `calendar` kind. */
+  calendarWindow?: { start: string; end: string };
+  /** URL facet/search params forwarded from the page URL (#308) — applied for `list`/`map`. */
+  filterParams?: Record<string, string>;
+}
+
+/**
+ * SECURITY INVARIANT (never remove this comment):
+ * Each host owns its own DataProvider and its own security boundary. The
+ * portal's DataProvider routes through the public /bff proxy (auth-optional,
+ * SSRF-pinned to /{app}/public/). A future admin DataProvider routes through
+ * the RLS-authenticated entity-proxy lane. NEVER share one transport across
+ * both hosts. NEVER let a public widget read through an authed token, nor
+ * expose the authed lane through the public proxy. A "simplification" that
+ * collapses the two providers is a tenant/RLS leak.
+ */
+export interface DataProvider {
+  /**
+   * The raw data path for the binding, with calendar window and filter params
+   * applied. Returns `null` for unmappable bindings (caller fails closed).
+   * The path is the PAGEABLE surface: widgets re-fetch it client-side with
+   * `?after=` for "load more". It does NOT include the proxy prefix — the
+   * provider's `fetch` adds the prefix on the outbound call.
+   */
+  dataUrl(binding: Binding, opts?: DataUrlOpts): string | null;
+
+  /**
+   * The entity schema path for the binding. Returns `null` for kinds that
+   * carry no schema (content, map, calendar, …). The path does NOT include
+   * the proxy prefix.
+   */
+  schemaUrl(binding: Binding): string | null;
+
+  /**
+   * The authed account lane URL for the given path segment.
+   * Returns `/me/{segment}` — NO `/bff` prefix. This is a different security
+   * boundary (require_auth + OWN-scoped) from the public `/bff` surface.
+   */
+  accountUrl(segment: string): string;
+
+  /**
+   * The option-view read URL (for subscription scope dropdowns, #252).
+   * Returns the FULL URL including the proxy prefix.
+   */
+  optionViewUrl(view: string, limit: number): string;
+
+  /** Edition read path for the `vote` ballot composer. Full URL. */
+  voteEditionUrl(cfg: VoteReadConfig, editionId: string): string;
+
+  /** Options read path for the `vote` ballot composer. Full URL. */
+  voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string;
+
+  /** The fetch transport. Accepts any URL returned by the methods above. */
+  fetch: FetchLike;
+}
+
+function enc(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/**
+ * Construct the portal's public DataProvider.
+ *
+ * Reproduces today's `resolveData` URL behavior byte-for-byte:
+ *   - `dataUrl` / `schemaUrl` return the raw `/{app}/public/...` path (no
+ *     `/bff` prefix). The provider's `fetch` adds `/bff` on the outbound call
+ *     so the raw path is also the pageable `dataPath` the widgets store.
+ *   - `accountUrl` returns `/me/{segment}` — the authed lane, never proxied
+ *     through `/bff`. The provider's `fetch` passes `/me/...` through as-is.
+ *   - `optionViewUrl`, `voteEditionUrl`, `voteOptionsUrl` return the full URL
+ *     already including `/bff`. The provider's `fetch` passes them through.
+ *
+ * The `fetch` wrapper decides by prefix: `/bff/` and `/me/` are passed
+ * through unchanged; anything else (raw `/{app}/public/...` paths) gets
+ * `/bff` prepended. This keeps the `fetch` self-contained in the provider —
+ * `resolveData` never sees or constructs a proxy prefix.
+ */
+export function createPublicDataProvider(
+  app: string,
+  fetchImpl: FetchLike,
+): DataProvider {
+  /**
+   * Portal fetch transport. Paths that already carry their proxy prefix
+   * (`/bff/...` for the public lane, `/me/...` for the authed account lane)
+   * are forwarded unchanged. Raw `/{app}/public/...` paths (returned by
+   * `dataUrl` and `schemaUrl`) are proxied through `/bff`.
+   */
+  const fetch: FetchLike = (url: string) => {
+    if (url.startsWith("/bff/") || url.startsWith("/me/")) {
+      return fetchImpl(url);
+    }
+    return fetchImpl(`/bff${url}`);
+  };
+
+  return {
+    dataUrl(binding: Binding, opts?: DataUrlOpts): string | null {
+      const path = bffPathForBinding(binding, app);
+      if (path === null) return null;
+      let url = path;
+      // Calendar requires start/end (73e); the window is pre-computed in
+      // resolveData from `now` and passed in via opts.
+      if (binding.kind === "calendar" && opts?.calendarWindow) {
+        const { start, end } = opts.calendarWindow;
+        url = `${path}?start=${start}&end=${end}`;
+      }
+      // Forward URL facet/search params (#308) for list + map feeds so the
+      // SSR result is server-FILTERED. The BFF drops undeclared params.
+      if (
+        (binding.kind === "list" || binding.kind === "map") &&
+        opts?.filterParams
+      ) {
+        url = appendQuery(url, opts.filterParams);
+      }
+      return url;
+    },
+
+    schemaUrl(binding: Binding): string | null {
+      return schemaPathForBinding(binding, app);
+    },
+
+    accountUrl(segment: string): string {
+      return `/me/${segment}`;
+    },
+
+    optionViewUrl(view: string, limit: number): string {
+      return `/bff/${enc(app)}/public/${enc(view)}?limit=${limit}`;
+    },
+
+    voteEditionUrl(cfg: VoteReadConfig, editionId: string): string {
+      // Delegates to the unchanged vote.ts helper — guarantees byte-identical
+      // vote URLs (vote.ts must NOT be modified, spec §P0).
+      return editionReadPath(app, cfg, editionId);
+    },
+
+    voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string {
+      return optionsReadPath(app, cfg, editionId);
+    },
+
+    fetch,
+  };
+}

package/components/renderer/dispatch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ *
+ * Generalises the admin app's XSS-hardened layout registry
+ * (`admin/src/lib/renderer-layouts/resolve.ts`) from form-row LayoutKeys to
+ * widget `kind`s. Each entry carries a `tester(binding, schema) → score`; the
+ * highest score wins. A more specific tester (e.g. "list of `occurrence`")
+ * outranks the generic "any list" and overrides one widget for one entity
+ * WITHOUT editing the catalog (open/closed).
+ *
+ * The ranking core here is generic over the payload `P` so it stays
+ * component-free and fully unit/mutation-testable; the real registry (73b)
+ * instantiates it with Svelte `Component`s.
+ *
+ * TH-08 (R-SEC-07) preserved: the resolved `key` is a known-good literal from
+ * the matched entry — the operator's raw `binding.kind`/`entity`/block `type`
+ * is NEVER returned as the key, so it never reaches `class`/`data-*`/`style`.
+ */
+import type { Binding, Block, OntologySchema } from "./types";
+/** Tester sentinel — "this widget does not apply to this binding". */
+export declare const NOT_APPLICABLE = -1;
+/**
+ * A tester ranks a registry entry against a binding (+ optional schema and the
+ * block's authoring `type` hint). JSONForms model: testers see the full
+ * element, so a type-specific widget (e.g. `filter-bar`) can out-rank the
+ * generic kind widget (`entity-list`) for the SAME `binding.kind` without
+ * editing the kind entry. `type` is UNTRUSTED — it only influences ranking; the
+ * resolved `key` still comes from the matched entry (TH-08), never from `type`.
+ */
+export type WidgetTester = (binding: Binding, schema: OntologySchema | null, type?: string) => number;
+export interface RegistryEntry<P> {
+    /** Known-good literal. Safe to render as `data-widget={key}` (TH-08). */
+    key: string;
+    payload: P;
+    tester: WidgetTester;
+}
+export interface Match<P> {
+    key: string;
+    payload: P;
+}
+/**
+ * Run every tester against the binding; the highest applicable score wins.
+ * Ties resolve to the first-registered entry (stable, deterministic). Returns
+ * `null` when no tester is applicable — the caller fails closed per blast
+ * radius; nothing about the binding is interpolated.
+ */
+export declare function selectEntry<P>(entries: ReadonlyArray<RegistryEntry<P>>, binding: Binding, schema: OntologySchema | null, type?: string): Match<P> | null;
+export type RenderDecision = {
+    render: "widget";
+} | {
+    render: "empty";
+} | {
+    render: "error";
+};
+/**
+ * Fail-closed per blast radius (§14.8). Given whether a widget matched AND
+ * whether its data resolved, decide how the slot renders:
+ *   - matched + data ok        → render the widget
+ *   - failed, optional slot    → soft-empty (render nothing)
+ *   - failed, structural slot  → visible error (MUST NOT silently vanish)
+ * The operator's raw `type`/`kind` is never interpolated in any branch.
+ */
+export declare function decideRender(block: Pick<Block, "importance">, matched: boolean, dataOk: boolean): RenderDecision;

package/components/renderer/dispatch.ts

@@ -0,0 +1,99 @@
+/**
+ * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ *
+ * Generalises the admin app's XSS-hardened layout registry
+ * (`admin/src/lib/renderer-layouts/resolve.ts`) from form-row LayoutKeys to
+ * widget `kind`s. Each entry carries a `tester(binding, schema) → score`; the
+ * highest score wins. A more specific tester (e.g. "list of `occurrence`")
+ * outranks the generic "any list" and overrides one widget for one entity
+ * WITHOUT editing the catalog (open/closed).
+ *
+ * The ranking core here is generic over the payload `P` so it stays
+ * component-free and fully unit/mutation-testable; the real registry (73b)
+ * instantiates it with Svelte `Component`s.
+ *
+ * TH-08 (R-SEC-07) preserved: the resolved `key` is a known-good literal from
+ * the matched entry — the operator's raw `binding.kind`/`entity`/block `type`
+ * is NEVER returned as the key, so it never reaches `class`/`data-*`/`style`.
+ */
+import type { Binding, Block, OntologySchema } from "./types";
+
+/** Tester sentinel — "this widget does not apply to this binding". */
+export const NOT_APPLICABLE = -1;
+
+/**
+ * A tester ranks a registry entry against a binding (+ optional schema and the
+ * block's authoring `type` hint). JSONForms model: testers see the full
+ * element, so a type-specific widget (e.g. `filter-bar`) can out-rank the
+ * generic kind widget (`entity-list`) for the SAME `binding.kind` without
+ * editing the kind entry. `type` is UNTRUSTED — it only influences ranking; the
+ * resolved `key` still comes from the matched entry (TH-08), never from `type`.
+ */
+export type WidgetTester = (
+  binding: Binding,
+  schema: OntologySchema | null,
+  type?: string,
+) => number;
+
+export interface RegistryEntry<P> {
+  /** Known-good literal. Safe to render as `data-widget={key}` (TH-08). */
+  key: string;
+  payload: P;
+  tester: WidgetTester;
+}
+
+export interface Match<P> {
+  key: string;
+  payload: P;
+}
+
+/**
+ * Run every tester against the binding; the highest applicable score wins.
+ * Ties resolve to the first-registered entry (stable, deterministic). Returns
+ * `null` when no tester is applicable — the caller fails closed per blast
+ * radius; nothing about the binding is interpolated.
+ */
+export function selectEntry<P>(
+  entries: ReadonlyArray<RegistryEntry<P>>,
+  binding: Binding,
+  schema: OntologySchema | null,
+  type?: string,
+): Match<P> | null {
+  let best: RegistryEntry<P> | null = null;
+  let bestScore: number = NOT_APPLICABLE;
+  for (const entry of entries) {
+    const score = entry.tester(binding, schema, type);
+    // Strictly greater → first registered wins ties.
+    if (score > bestScore) {
+      bestScore = score;
+      best = entry;
+    }
+  }
+  if (best === null) return null;
+  // TH-08: key from the matched entry, never from the binding/block.
+  return { key: best.key, payload: best.payload };
+}
+
+export type RenderDecision =
+  | { render: "widget" }
+  | { render: "empty" }
+  | { render: "error" };
+
+/**
+ * Fail-closed per blast radius (§14.8). Given whether a widget matched AND
+ * whether its data resolved, decide how the slot renders:
+ *   - matched + data ok        → render the widget
+ *   - failed, optional slot    → soft-empty (render nothing)
+ *   - failed, structural slot  → visible error (MUST NOT silently vanish)
+ * The operator's raw `type`/`kind` is never interpolated in any branch.
+ */
+export function decideRender(
+  block: Pick<Block, "importance">,
+  matched: boolean,
+  dataOk: boolean,
+): RenderDecision {
+  if (matched && dataOk) return { render: "widget" };
+  return block.importance === "structural"
+    ? { render: "error" }
+    : { render: "empty" };
+}