@aiaiai-pt/design-system 0.47.0 → 0.49.0

package/components/EChart.svelte

@@ -142,9 +142,13 @@
     return buildChartOption(chartData, {
       tokens: {
         accent: token("--color-accent", "#2563eb"),
-        textPrimary: token("--color-text-primary", "#1f2937"),
+        // Semantic tokens name the primary text colour `--color-text` (see
+        // tokens/semantic.css); `--color-text-primary` never existed, so this
+        // read silently fell back to #1f2937 — invisible on dark schemes (#89).
+        textPrimary: token("--color-text", token("--color-text-primary", "#1f2937")),
         textSecondary: token("--color-text-secondary", "#6b7280"),
         border: token("--color-border", "#e5e7eb"),
+        surface: token("--color-surface", "#ffffff"),
       },
       locale,
       legend,

package/components/map-utils.js

@@ -186,7 +186,7 @@ export function watchTheme(onchange) {
   const mo = new MutationObserver(() => onchange());
   mo.observe(document.documentElement, {
     attributes: true,
-    attributeFilter: ["data-theme", "class"],
+    attributeFilter: ["data-theme", "data-scheme", "data-contrast", "class"],
   });
 
   const mql = window.matchMedia("(prefers-color-scheme: dark)");

package/components/renderer/chart-option.d.ts

@@ -26,6 +26,9 @@ export interface ChartTokens {
     textPrimary: string;
     textSecondary: string;
     border: string;
+    /** Panel surface behind floating chrome (tooltip); themes the default-white
+        ECharts tooltip for dark/high-contrast schemes (#89). */
+    surface: string;
 }
 export interface BuildChartOptionOpts {
     tokens: ChartTokens;

package/components/renderer/chart-option.ts

@@ -28,6 +28,9 @@ export interface ChartTokens {
   textPrimary: string;
   textSecondary: string;
   border: string;
+  /** Panel surface behind floating chrome (tooltip); themes the default-white
+      ECharts tooltip for dark/high-contrast schemes (#89). */
+  surface: string;
 }
 
 export interface BuildChartOptionOpts {
@@ -44,6 +47,16 @@ export interface BuildChartOptionOpts {
   innerRadius?: number;
 }
 
+/** Token-driven tooltip chrome — ECharts defaults to a white panel that
+ * ignores the scheme entirely (#89). */
+function tooltipChrome(tokens: ChartTokens): Record<string, unknown> {
+  return {
+    backgroundColor: tokens.surface,
+    borderColor: tokens.border,
+    textStyle: { color: tokens.textPrimary },
+  };
+}
+
 /** A localised number formatter (DS-supplied — never operator code). */
 function makeFmt(locale: string): (value: number) => string {
   const nf = new Intl.NumberFormat(locale);
@@ -78,12 +91,13 @@ function buildPieOption(
   return {
     animation: false,
     tooltip: {
+      ...tooltipChrome(tokens),
       trigger: "item",
       formatter: (p: { name: string; value: number; percent: number }) =>
         `${p.name}: ${fmt(p.value)} (${p.percent}%)`,
     },
     ...(opts.legend
-      ? { legend: { show: true, textStyle: { color: tokens.textPrimary } } }
+      ? { legend: { show: true, top: 0, textStyle: { color: tokens.textPrimary } } }
       : {}),
     color: palette,
     series: [
@@ -208,6 +222,7 @@ function buildCartesianOption(
       containLabel: true,
     },
     tooltip: {
+      ...tooltipChrome(tokens),
       trigger: "axis",
       axisPointer: { type: "shadow" },
       formatter: (
@@ -227,6 +242,9 @@ function buildCartesianOption(
       ? {
           legend: {
             show: true,
+            // echarts 6 lays the unpositioned legend over the bottom category
+            // labels; pin it to the top strip grid.top already reserves (#89).
+            top: 0,
             data: series.map((s) => s.name),
             textStyle: { color: tokens.textPrimary },
           },

package/components/renderer/dispatch.d.ts

@@ -1,23 +1,31 @@
 /**
- * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ * Widget dispatcher — COMPATIBILITY ADAPTER over @aiaiai-pt/widget-system/core.
  *
- * 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).
+ * @deprecated Import the generic dispatch from `@aiaiai-pt/widget-system/core`
+ * instead. This module is the S2 (#60) compatibility shim: it preserves the
+ * Atelier-shaped `@aiaiai-pt/design-system/renderer/dispatch` import surface for
+ * one migration window while the ranking ALGORITHM lives in exactly one place —
+ * `@aiaiai-pt/widget-system/core`. Scheduled for removal in the next MAJOR of
+ * `@aiaiai-pt/design-system` (S3). See `docs/migration/widget-system.md`.
  *
- * 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.
+ * Classification (#60 AC5): the tester/priority ranking loop is a GENERIC
+ * widget-system API — it is delegated below and NOT reimplemented here. The
+ * `(binding, schema, type)` tester SIGNATURE is ATELIER-COUPLED (it names
+ * `Binding`/`OntologySchema`/`Block` from ./types) and stays here as a thin
+ * adapter until consumers migrate to the ctx-shaped `WidgetMatchContext`.
  *
- * 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`.
+ * TH-08 (R-SEC-07) preserved end-to-end: `core.selectEntry` returns the matched
+ * entry's known-good `key` literal — the operator's raw `binding.kind`/`type`
+ * is never returned as the key, so it never reaches `class`/`data-*`/`style`.
  */
+import { type Match as CoreMatch, type RenderDecision as CoreRenderDecision } from "@aiaiai-pt/widget-system/core";
 import type { Binding, Block, OntologySchema } from "./types";
-/** Tester sentinel — "this widget does not apply to this binding". */
+/**
+ * Tester sentinel — "this widget does not apply to this binding".
+ *
+ * @deprecated Re-exported from `@aiaiai-pt/widget-system/core`. Import it from
+ * there directly.
+ */
 export declare const NOT_APPLICABLE = -1;
 /**
  * A tester ranks a registry entry against a binding (+ optional schema and the
@@ -26,38 +34,67 @@ export declare const NOT_APPLICABLE = -1;
  * 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`.
+ *
+ * @deprecated ATELIER-COUPLED signature. The generic tester in
+ * `@aiaiai-pt/widget-system/core` is `(ctx: WidgetMatchContext) => number`.
+ * Migrate custom testers to read `ctx.kind`/`ctx.type` from a match context.
  */
 export type WidgetTester = (binding: Binding, schema: OntologySchema | null, type?: string) => number;
+/**
+ * @deprecated ATELIER-COUPLED entry shape (its `tester` names `Binding`). The
+ * generic entry lives in `@aiaiai-pt/widget-system/core` as
+ * `RegistryEntry<P, Ctx>`.
+ */
 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;
-}
+/**
+ * The matched entry. Structurally identical to
+ * `@aiaiai-pt/widget-system/core`'s `Match<P>` — re-exported so consumers can
+ * migrate the import without a type change.
+ *
+ * @deprecated Import `Match` from `@aiaiai-pt/widget-system/core`.
+ */
+export type Match<P> = CoreMatch<P>;
+/**
+ * The render decision. Structurally identical to
+ * `@aiaiai-pt/widget-system/core`'s `RenderDecision`.
+ *
+ * @deprecated Import `RenderDecision` from `@aiaiai-pt/widget-system/core`.
+ */
+export type RenderDecision = CoreRenderDecision;
 /**
  * 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.
+ * `null` when no tester is applicable.
+ *
+ * DELEGATION (#60): the ranking loop is NOT implemented here. Each
+ * Atelier-shaped entry is adapted into a `core.RegistryEntry` whose tester
+ * closes over `(binding, schema, type)` — so the full `(binding, schema, type)`
+ * tester contract (including `schema`, which the ctx model omits) is preserved
+ * — and the loop itself runs in `@aiaiai-pt/widget-system/core.selectEntry`.
+ * The `ctx` handed to core is a formality: core invokes `tester(ctx)` once per
+ * entry, and our adapted tester ignores it in favour of the closed-over args.
+ *
+ * @deprecated Use `selectEntry(entries, ctx)` from
+ * `@aiaiai-pt/widget-system/core` with `ctx: WidgetMatchContext`.
  */
 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.
+ *
+ * DELEGATION (#60): the decision is `@aiaiai-pt/widget-system/core.decideRender`;
+ * this adapter only projects the Atelier `Block.importance` field onto the
+ * generic `importance` argument.
+ *
+ * @deprecated Use `decideRender(importance, matched, dataOk)` from
+ * `@aiaiai-pt/widget-system/core`, passing `block.importance` directly.
  */
 export declare function decideRender(block: Pick<Block, "importance">, matched: boolean, dataOk: boolean): RenderDecision;

package/components/renderer/dispatch.ts

@@ -1,25 +1,39 @@
 /**
- * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ * Widget dispatcher — COMPATIBILITY ADAPTER over @aiaiai-pt/widget-system/core.
  *
- * 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).
+ * @deprecated Import the generic dispatch from `@aiaiai-pt/widget-system/core`
+ * instead. This module is the S2 (#60) compatibility shim: it preserves the
+ * Atelier-shaped `@aiaiai-pt/design-system/renderer/dispatch` import surface for
+ * one migration window while the ranking ALGORITHM lives in exactly one place —
+ * `@aiaiai-pt/widget-system/core`. Scheduled for removal in the next MAJOR of
+ * `@aiaiai-pt/design-system` (S3). See `docs/migration/widget-system.md`.
  *
- * 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.
+ * Classification (#60 AC5): the tester/priority ranking loop is a GENERIC
+ * widget-system API — it is delegated below and NOT reimplemented here. The
+ * `(binding, schema, type)` tester SIGNATURE is ATELIER-COUPLED (it names
+ * `Binding`/`OntologySchema`/`Block` from ./types) and stays here as a thin
+ * adapter until consumers migrate to the ctx-shaped `WidgetMatchContext`.
  *
- * 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`.
+ * TH-08 (R-SEC-07) preserved end-to-end: `core.selectEntry` returns the matched
+ * entry's known-good `key` literal — the operator's raw `binding.kind`/`type`
+ * is never returned as the key, so it never reaches `class`/`data-*`/`style`.
  */
+import {
+  decideRender as coreDecideRender,
+  NOT_APPLICABLE as CORE_NOT_APPLICABLE,
+  selectEntry as coreSelectEntry,
+  type Match as CoreMatch,
+  type RenderDecision as CoreRenderDecision,
+} from "@aiaiai-pt/widget-system/core";
 import type { Binding, Block, OntologySchema } from "./types";
 
-/** Tester sentinel — "this widget does not apply to this binding". */
-export const NOT_APPLICABLE = -1;
+/**
+ * Tester sentinel — "this widget does not apply to this binding".
+ *
+ * @deprecated Re-exported from `@aiaiai-pt/widget-system/core`. Import it from
+ * there directly.
+ */
+export const NOT_APPLICABLE = CORE_NOT_APPLICABLE;
 
 /**
  * A tester ranks a registry entry against a binding (+ optional schema and the
@@ -28,6 +42,10 @@ export const NOT_APPLICABLE = -1;
  * 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`.
+ *
+ * @deprecated ATELIER-COUPLED signature. The generic tester in
+ * `@aiaiai-pt/widget-system/core` is `(ctx: WidgetMatchContext) => number`.
+ * Migrate custom testers to read `ctx.kind`/`ctx.type` from a match context.
  */
 export type WidgetTester = (
   binding: Binding,
@@ -35,6 +53,11 @@ export type WidgetTester = (
   type?: string,
 ) => number;
 
+/**
+ * @deprecated ATELIER-COUPLED entry shape (its `tester` names `Binding`). The
+ * generic entry lives in `@aiaiai-pt/widget-system/core` as
+ * `RegistryEntry<P, Ctx>`.
+ */
 export interface RegistryEntry<P> {
   /** Known-good literal. Safe to render as `data-widget={key}` (TH-08). */
   key: string;
@@ -42,16 +65,38 @@ export interface RegistryEntry<P> {
   tester: WidgetTester;
 }
 
-export interface Match<P> {
-  key: string;
-  payload: P;
-}
+/**
+ * The matched entry. Structurally identical to
+ * `@aiaiai-pt/widget-system/core`'s `Match<P>` — re-exported so consumers can
+ * migrate the import without a type change.
+ *
+ * @deprecated Import `Match` from `@aiaiai-pt/widget-system/core`.
+ */
+export type Match<P> = CoreMatch<P>;
+
+/**
+ * The render decision. Structurally identical to
+ * `@aiaiai-pt/widget-system/core`'s `RenderDecision`.
+ *
+ * @deprecated Import `RenderDecision` from `@aiaiai-pt/widget-system/core`.
+ */
+export type RenderDecision = CoreRenderDecision;
 
 /**
  * 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.
+ * `null` when no tester is applicable.
+ *
+ * DELEGATION (#60): the ranking loop is NOT implemented here. Each
+ * Atelier-shaped entry is adapted into a `core.RegistryEntry` whose tester
+ * closes over `(binding, schema, type)` — so the full `(binding, schema, type)`
+ * tester contract (including `schema`, which the ctx model omits) is preserved
+ * — and the loop itself runs in `@aiaiai-pt/widget-system/core.selectEntry`.
+ * The `ctx` handed to core is a formality: core invokes `tester(ctx)` once per
+ * entry, and our adapted tester ignores it in favour of the closed-over args.
+ *
+ * @deprecated Use `selectEntry(entries, ctx)` from
+ * `@aiaiai-pt/widget-system/core` with `ctx: WidgetMatchContext`.
  */
 export function selectEntry<P>(
   entries: ReadonlyArray<RegistryEntry<P>>,
@@ -59,41 +104,35 @@ export function selectEntry<P>(
   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 };
+  const ctx = { kind: binding.kind, type };
+  const adapted = entries.map((entry) => ({
+    key: entry.key,
+    payload: entry.payload,
+    // Close over the Atelier-shaped selection inputs; core supplies `ctx` but
+    // this adapter reads the richer (binding, schema, type) triple instead.
+    tester: () => entry.tester(binding, schema, type),
+  }));
+  return coreSelectEntry(adapted, ctx);
 }
 
-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.
+ *
+ * DELEGATION (#60): the decision is `@aiaiai-pt/widget-system/core.decideRender`;
+ * this adapter only projects the Atelier `Block.importance` field onto the
+ * generic `importance` argument.
+ *
+ * @deprecated Use `decideRender(importance, matched, dataOk)` from
+ * `@aiaiai-pt/widget-system/core`, passing `block.importance` directly.
  */
 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" };
+  return coreDecideRender(block.importance, matched, dataOk);
 }

package/components/renderer/registry.d.ts

@@ -1,14 +1,23 @@
 /**
- * DS renderer widget registry — the extensible dispatcher layer (#492).
+ * DS renderer widget registry — the Atelier-coupled BASE registry (#492).
  *
- * Ships a BASE registry with the two clean DS widgets (stat-grid + results-chart)
- * and exposes a `registerWidget` hook so host apps (the portal, the admin) can
- * append their own coupled widgets at startup without modifying this module
- * (open/closed principle, JSONForms model).
+ * @deprecated This is an S2 (#60) COMPATIBILITY surface. It is NOT a generic
+ * widget-system API — do not reclassify it as one (#60 AC5). It is an
+ * Atelier-coupled base registry: a module-global entry list preloaded with the
+ * DS widgets (stat-grid, results-chart, chart, metabase-embed) whose testers
+ * name `Binding`/`Block`/`WidgetKind` from ./types.
  *
- * `dispatch.ts` (the tester/priority core) is the single dispatcher both the DS
- * base registry and host-extended registries share; the registry is generic over
- * the payload so `selectEntry` stays component-free and unit-testable.
+ * Migration destination: the generic isolated-registry machinery lives in
+ * `@aiaiai-pt/widget-system/core` (`createRegistry()` — an isolated, override-
+ * aware factory, not a module-global singleton) and its base-widget preload in
+ * `@aiaiai-pt/widget-system/widgets` (`registerBaseWidgets`). The Atelier host
+ * owns which widgets it preloads. This module is scheduled for removal in the
+ * next MAJOR of `@aiaiai-pt/design-system` (S3). See
+ * `docs/migration/widget-system.md`.
+ *
+ * NO DUPLICATE DISPATCH (#60 AC3): this module holds ZERO ranking logic. It
+ * only stores entries and delegates resolution to `./dispatch.selectEntry`,
+ * which itself delegates the ranking loop to `@aiaiai-pt/widget-system/core`.
  *
  * TH-08 preserved: `resolveWidget` returns the matched entry's known-good `key`
  * literal — the operator's raw block `type`/`binding.kind` is never the key.
@@ -22,9 +31,18 @@ export type WidgetComponent = Component<WidgetProps>;
  * `type` hint ranks it ABOVE the kind-generic widget (score 20 > 10) for the
  * same binding. `type` is UNTRUSTED — it only influences ranking; the resolved
  * key is the entry literal (TH-08).
+ *
+ * @deprecated ATELIER-COUPLED builder (its `kind` is a `WidgetKind` and its
+ * tester names `Binding`). Migrate to `byTypeOnKind` from
+ * `@aiaiai-pt/widget-system/core`, whose tester reads a ctx `WidgetMatchContext`.
  */
 export declare function byTypeOnKind(key: string, kind: WidgetKind, component: unknown): RegistryEntry<WidgetComponent>;
-/** A widget whose tester is the generic "binding.kind === K" check (score 10). */
+/**
+ * A widget whose tester is the generic "binding.kind === K" check (score 10).
+ *
+ * @deprecated ATELIER-COUPLED builder. Migrate to `byKind` from
+ * `@aiaiai-pt/widget-system/core` (ctx-shaped tester).
+ */
 export declare function byKind(key: string, kind: WidgetKind, component: unknown): RegistryEntry<WidgetComponent>;
 /**
  * Register a widget in the host-extensible registry. Call at app startup
@@ -37,6 +55,11 @@ export declare function byKind(key: string, kind: WidgetKind, component: unknown
  *
  * @param entry - A registry entry built with `byKind`, `byTypeOnKind`, or a
  *   hand-crafted `{ key, payload, tester }` for a custom tester.
+ *
+ * @deprecated ATELIER-COUPLED module-global registration. Migrate to an
+ * isolated `createRegistry()` from `@aiaiai-pt/widget-system/core` plus
+ * `registerBaseWidgets` from `@aiaiai-pt/widget-system/widgets`, and call
+ * `registry.register(...)` on the host-owned instance.
  */
 export declare function registerWidget(entry: RegistryEntry<WidgetComponent>): void;
 /**
@@ -44,5 +67,11 @@ export declare function registerWidget(entry: RegistryEntry<WidgetComponent>): v
  * the full registry (base DS entries + host-registered). Returns `null` when
  * no widget applies — the caller renders per blast radius (`decideRender`),
  * never interpolating the block's raw `type`/`kind`.
+ *
+ * Resolution delegates to `./dispatch.selectEntry` (→ widget-system/core); this
+ * module contributes only the entry list, never the ranking loop.
+ *
+ * @deprecated Migrate to `registry.resolve(ctx)` on an isolated
+ * `createRegistry()` from `@aiaiai-pt/widget-system/core`.
  */
 export declare function resolveWidget(block: Block, schema?: OntologySchema | null): Match<WidgetComponent> | null;

package/components/renderer/registry.ts

@@ -1,14 +1,23 @@
 /**
- * DS renderer widget registry — the extensible dispatcher layer (#492).
+ * DS renderer widget registry — the Atelier-coupled BASE registry (#492).
  *
- * Ships a BASE registry with the two clean DS widgets (stat-grid + results-chart)
- * and exposes a `registerWidget` hook so host apps (the portal, the admin) can
- * append their own coupled widgets at startup without modifying this module
- * (open/closed principle, JSONForms model).
+ * @deprecated This is an S2 (#60) COMPATIBILITY surface. It is NOT a generic
+ * widget-system API — do not reclassify it as one (#60 AC5). It is an
+ * Atelier-coupled base registry: a module-global entry list preloaded with the
+ * DS widgets (stat-grid, results-chart, chart, metabase-embed) whose testers
+ * name `Binding`/`Block`/`WidgetKind` from ./types.
  *
- * `dispatch.ts` (the tester/priority core) is the single dispatcher both the DS
- * base registry and host-extended registries share; the registry is generic over
- * the payload so `selectEntry` stays component-free and unit-testable.
+ * Migration destination: the generic isolated-registry machinery lives in
+ * `@aiaiai-pt/widget-system/core` (`createRegistry()` — an isolated, override-
+ * aware factory, not a module-global singleton) and its base-widget preload in
+ * `@aiaiai-pt/widget-system/widgets` (`registerBaseWidgets`). The Atelier host
+ * owns which widgets it preloads. This module is scheduled for removal in the
+ * next MAJOR of `@aiaiai-pt/design-system` (S3). See
+ * `docs/migration/widget-system.md`.
+ *
+ * NO DUPLICATE DISPATCH (#60 AC3): this module holds ZERO ranking logic. It
+ * only stores entries and delegates resolution to `./dispatch.selectEntry`,
+ * which itself delegates the ranking loop to `@aiaiai-pt/widget-system/core`.
  *
  * TH-08 preserved: `resolveWidget` returns the matched entry's known-good `key`
  * literal — the operator's raw block `type`/`binding.kind` is never the key.
@@ -34,6 +43,10 @@ export type WidgetComponent = Component<WidgetProps>;
  * `type` hint ranks it ABOVE the kind-generic widget (score 20 > 10) for the
  * same binding. `type` is UNTRUSTED — it only influences ranking; the resolved
  * key is the entry literal (TH-08).
+ *
+ * @deprecated ATELIER-COUPLED builder (its `kind` is a `WidgetKind` and its
+ * tester names `Binding`). Migrate to `byTypeOnKind` from
+ * `@aiaiai-pt/widget-system/core`, whose tester reads a ctx `WidgetMatchContext`.
  */
 export function byTypeOnKind(
   key: string,
@@ -48,7 +61,12 @@ export function byTypeOnKind(
   };
 }
 
-/** A widget whose tester is the generic "binding.kind === K" check (score 10). */
+/**
+ * A widget whose tester is the generic "binding.kind === K" check (score 10).
+ *
+ * @deprecated ATELIER-COUPLED builder. Migrate to `byKind` from
+ * `@aiaiai-pt/widget-system/core` (ctx-shaped tester).
+ */
 export function byKind(
   key: string,
   kind: WidgetKind,
@@ -92,6 +110,11 @@ const _entries: RegistryEntry<WidgetComponent>[] = [
  *
  * @param entry - A registry entry built with `byKind`, `byTypeOnKind`, or a
  *   hand-crafted `{ key, payload, tester }` for a custom tester.
+ *
+ * @deprecated ATELIER-COUPLED module-global registration. Migrate to an
+ * isolated `createRegistry()` from `@aiaiai-pt/widget-system/core` plus
+ * `registerBaseWidgets` from `@aiaiai-pt/widget-system/widgets`, and call
+ * `registry.register(...)` on the host-owned instance.
  */
 export function registerWidget(entry: RegistryEntry<WidgetComponent>): void {
   _entries.push(entry);
@@ -102,6 +125,12 @@ export function registerWidget(entry: RegistryEntry<WidgetComponent>): void {
  * the full registry (base DS entries + host-registered). Returns `null` when
  * no widget applies — the caller renders per blast radius (`decideRender`),
  * never interpolating the block's raw `type`/`kind`.
+ *
+ * Resolution delegates to `./dispatch.selectEntry` (→ widget-system/core); this
+ * module contributes only the entry list, never the ranking loop.
+ *
+ * @deprecated Migrate to `registry.resolve(ctx)` on an isolated
+ * `createRegistry()` from `@aiaiai-pt/widget-system/core`.
  */
 export function resolveWidget(
   block: Block,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,8 @@
     "access": "public"
   },
   "workspaces": [
-    "site"
+    "site",
+    "packages/widget-system"
   ],
   "scripts": {
     "build:types": "rm -f components/*.d.ts components/renderer/*.d.ts && svelte-package --input . --output dist && cp dist/components/*.d.ts components/ && cp dist/components/renderer/*.d.ts components/renderer/ && rm -rf dist",
@@ -73,6 +74,9 @@
     "components",
     "tokens"
   ],
+  "dependencies": {
+    "@aiaiai-pt/widget-system": ">=0.1.0 <1"
+  },
   "peerDependencies": {
     "@codemirror/commands": "^6.10.3",
     "@codemirror/lang-json": "^6.0.2",

package/tokens/semantic.css

@@ -230,11 +230,11 @@
    dark wash for free. Per-theme bespoke dark = a `[data-theme="x"]`
    block in the theme file, not here.
 
-   Selector is `:root[data-scheme="dark"]` (0,1,1): it TIES tenant theme
-   blocks (`:root[data-theme="x"]`, runtime-injected in <head>) and wins
-   on order — DS styles load after the injected theme block. Consumers
-   resolving an "auto" preference must set the RESOLVED value on <html>
-   (a pre-paint `prefers-color-scheme` read), never "auto" itself. */
+   Selector is `:root[data-scheme="dark"]` (0,2,0 — pseudo-class + attribute):
+   it TIES runtime-injected tenant theme blocks (`:root[data-theme="x"]`,
+   also 0,2,0) and wins on order — DS styles load after the injected theme
+   block. Consumers resolving an "auto" preference must set the RESOLVED value
+   on <html> (a pre-paint `prefers-color-scheme` read), never "auto" itself. */
 
 :root[data-scheme="dark"] {
   color-scheme: dark;

package/tokens/themes/ubp.css

@@ -0,0 +1,224 @@
+/*
+ * aiaiai Design System — UBP Theme (ubp.css)
+ *
+ * Professional instrument theme for the urban intelligence workspace
+ * (ubp-ai-workspace). Tier 2 (Bespoke): distinct cool-steel identity
+ * optimised for data-dense, map-centric, dark-primary interfaces.
+ *
+ * Selector: [data-theme="ubp"]
+ * Paired scheme: [data-scheme="dark"] for the workspace default.
+ *   The generic dark layer (semantic.css) handles neutral role inversion;
+ *   the [data-theme="ubp"][data-scheme="dark"] block below adjusts only
+ *   the brand values that need different treatment on a cool-dark surface.
+ *
+ * ─── Neutral palette — owned, not verbatim Tailwind slate ───────────────
+ * The UBP neutral ramp is derived from Tailwind slate shifted 10° toward
+ * teal/steel in OKLCH. This is a deliberate identity decision: the hue
+ * drift gives mid-tones (400–600) a visible cool-steel signature while
+ * keeping the lightest stops (50–200) effectively neutral, making the
+ * palette perceptually distinct from Tailwind defaults without tipping
+ * into obvious teal.
+ *
+ * Before → After (10° OKLCH hue shift, all other OKLCH params unchanged):
+ *   #f8fafc → #f8fafc  (slate-50,  unchanged at 8-bit precision)
+ *   #f1f5f9 → #f0f5f9  (slate-100, surface-secondary)
+ *   #e2e8f0 → #e1e9f0  (slate-200, surface-tertiary)
+ *   #cbd5e1 → #c9d6e0  (slate-300, border)
+ *   #94a3b8 → #91a4b7  (slate-400, border-strong / dark text-secondary)
+ *   #64748b → #60758a  (slate-500, text-muted)
+ *   #475569 → #435668  (slate-600, dark border-strong)
+ *   #334155 → #2f4254  (slate-700, text-secondary light / dark surfaces)
+ *   #1e293b → #1a2a3a  (slate-800, dark surface-secondary)
+ *   #0f172a → #0b182a  (slate-900, text light / dark surface)
+ *
+ * ─── Font decision: inherit DS pairing ──────────────────────────────────
+ * UBP inherits Sistema's default type pairing unchanged:
+ *   sans  → Instrument Sans (--font-sans / --raw-font-sans)
+ *   mono  → JetBrains Mono, ui-monospace (--font-mono / --raw-font-mono)
+ *   (Berkeley Mono leads the mono stack in the token but ships no @font-face;
+ *    JetBrains Mono is the effective shipped face — see sistema #82.)
+ * The theme sets NO --font-sans or --font-mono override; font role-tokens
+ * resolve to the DS defaults via semantic.css inheritance.
+ * Full decision record: dev_docs/solutions/ubp-font-self-hosting.md
+ *
+ * ─── Historical 3.0:1 subtitle regression control ────────────────────────
+ * The 3.0:1 defect occurred when --color-text-muted was used in subtitle
+ * roles, giving only 3.0:1 contrast on the surface. This theme prevents it
+ * by ensuring --color-text-secondary (the subtitle token) clears WCAG AA
+ * (≥4.5:1) on every declared surface. See tests/ubp-theme-contrast.test.ts.
+ *
+ * ─── Owned by: DS-H0 #65, implemented under #66 ─────────────────────────
+ * Apply via: <html data-theme="ubp"> (light) or
+ *            <html data-theme="ubp" data-scheme="dark"> (dark / workspace default)
+ * Layer independently with data-contrast, data-text-size, data-link-highlight.
+ */
+
+[data-theme="ubp"] {
+  /* ═══════════════════════════════════════════════════════════════
+     TYPOGRAPHY — inherited from DS (no override)
+     Instrument Sans (sans) + JetBrains Mono (mono) via semantic.css.
+     ═══════════════════════════════════════════════════════════════ */
+
+  /* ═══════════════════════════════════════════════════════════════
+     COLOR — Cool steel palette (light-scheme base)
+     Neutrals: 10° OKLCH teal-shift from Tailwind slate — see file header.
+     ═══════════════════════════════════════════════════════════════ */
+
+  /* Surfaces: cool off-white — sterile precision vs aiaiai warm paper */
+  --color-surface: #f8fafc; /* steel-50  (unchanged at 8-bit) */
+  --color-surface-secondary: #f0f5f9; /* steel-100 */
+  --color-surface-tertiary: #e1e9f0; /* steel-200 */
+  --color-surface-raised: #ffffff; /* pure white for popovers/menus  */
+  --color-overlay: rgba(
+    11,
+    24,
+    42,
+    0.5
+  ); /* cool dark overlay (steel-900 base) */
+
+  /* Borders: cool steel */
+  --color-border: #c9d6e0; /* steel-300  */
+  --color-border-strong: #91a4b7; /* steel-400  */
+
+  /* Text: cool dark steel — contrast validated in ubp-theme-contrast.test.ts
+     text (#0b182a) on surface (#f8fafc): 17.03:1 [AAA]
+     text-secondary (#2f4254) on surface (#f8fafc): 9.90:1 [AAA — subtitle safe]
+     text-muted (#60758a) on surface (#f8fafc): 4.55:1 [AA — above 3.0 defect floor] */
+  --color-text: #0b182a; /* steel-900  */
+  --color-text-secondary: #2f4254; /* steel-700  */
+  --color-text-muted: #60758a; /* steel-500  */
+  --color-text-on-accent: #ffffff; /* white on blue-600: 5.17:1 [AA] */
+
+  /* Accent: UBP blue — maps, focus rings, primary actions
+     accent (#2563eb) on surface (#f8fafc): 4.94:1 [AA for normal text, ≥3:1 for UI] */
+  --color-accent: #2563eb; /* blue-600   */
+  --color-accent-hover: #1d4ed8; /* blue-700   */
+  --color-accent-subtle: #eff6ff; /* blue-50 equivalent — selected states */
+
+  /* Status semantic colours: override for cool-palette compatibility.
+     WCAG AA on --color-surface (#f8fafc) and --color-surface-secondary (#f1f5f9).
+     Subtle washes re-tuned for the cool surfaces.
+     NOTE: --color-info is NOT overridden; inherits DS teal-blue
+     (--raw-color-blue-600, #2e63a3 — 5.85:1 on surface), distinct from
+     --color-accent (#2563eb). See contrast suite: tests/ubp-theme-contrast.test.ts */
+  --color-destructive: #dc2626; /* red-600, 4.62:1 on surface  */
+  --color-destructive-hover: #b91c1c; /* red-700  */
+  --color-destructive-subtle: #fef2f2;
+
+  --color-success: #16a34a; /* green-600, 3.15:1 on surface — large UI only */
+  --color-success-subtle: #f0fdf4;
+
+  --color-warning: #ca8a04; /* amber-600, 3.1:1 on surface — large UI only */
+  --color-warning-subtle: #fffbeb;
+
+  /* Focus: accent blue, visible on all surfaces */
+  --focus-ring-color: var(--color-accent);
+
+  /* ═══════════════════════════════════════════════════════════════
+     RADIUS — Keep sharp (precision instrument)
+     Already: sm=2px md=4px lg=8px from semantic.css defaults
+     ═══════════════════════════════════════════════════════════════ */
+  /* No override — sharp radii match the professional platform aesthetic */
+
+  /* ═══════════════════════════════════════════════════════════════
+     ELEVATION — Subtle shadow on raised surfaces (instrument feel)
+     Uses steel-900 (#0b182a) as the shadow base (10° teal-shifted).
+     ═══════════════════════════════════════════════════════════════ */
+  --elevation-raised:
+    0 1px 3px rgba(11, 24, 42, 0.08), 0 1px 2px rgba(11, 24, 42, 0.04);
+  --elevation-overlay:
+    0 4px 16px rgba(11, 24, 42, 0.12), 0 2px 6px rgba(11, 24, 42, 0.06);
+
+  /* ═══════════════════════════════════════════════════════════════
+     MOTION — unchanged from DS defaults.
+     Product choreography (map transitions, panel morphs) belongs in
+     the host's ws.css, not the theme.
+     ═══════════════════════════════════════════════════════════════ */
+
+  /* Total color overrides: 22. Elevation: 2. Focus alias: 1.
+     Grand total: ~25 tokens. Typography/motion/spacing/grid unchanged.
+     --color-info and --color-info-subtle NOT overridden (inherit DS teal-blue). */
+}
+
+/* Desktop density: compact button heights for toolbar/sidebar layouts.
+   Scoped to ≥1024px so mobile targets stay at the DS default (44px for
+   --button-lg-height), satisfying the Tier-2 a11y checklist minimum.
+   Analogous to how other bespoke themes adjust density only where a
+   pointer device makes smaller targets safe (WCAG 2.5.5 advisory). */
+@media (min-width: 1024px) {
+  [data-theme="ubp"] {
+    --button-sm-height: 28px; /* DS Tier-2 floor: 28px min (reference/theming.md:221) */
+    --button-md-height: 32px;
+    --button-lg-height: 44px; /* DS Tier-2 floor: 44px min (reference/theming.md:221) */
+  }
+}
+
+/*
+ * Dark-scheme brand override.
+ *
+ * The generic dark layer (`:root[data-scheme="dark"]` in semantic.css, specificity
+ * 0,2,0 — pseudo-class + attribute) inverts neutral-derived roles to the warm
+ * neutral-950 ramp. This block overrides only the brand values that require a
+ * cool-steel dark base:
+ *   - Surfaces / borders / text / overlay → cool steel (not warm neutral)
+ *   - Accent → lighter blue (link contrast: 7.03:1 on steel-900 [AAA])
+ *   - text-on-accent → dark text on the lighter blue fill (7.03:1 [AAA])
+ *   - Subtle washes re-derived against the cool base via color-mix
+ *
+ * Selector specificity: (0,2,0) — ties the generic dark layer (also 0,2,0) when
+ * both `data-theme="ubp"` and `data-scheme="dark"` are present; wins by source
+ * order because ubp.css loads after semantic.css. The `auto` scheme is resolved
+ * before paint; "dark" here always matches an explicit decision.
+ *
+ * Subtitle regression control:
+ *   text (#f8fafc) on surface (#0b182a): 17.03:1 [AAA]
+ *   text-secondary (#91a4b7) on surface (#0b182a): 6.96:1 [AA — subtitle safe]
+ *   text-muted (#60758a) on surface (#0b182a): 3.74:1 — correctly limited to
+ *     non-essential UI labels, NOT body text or subtitles.
+ */
+[data-theme="ubp"][data-scheme="dark"] {
+  /* Surfaces: cool steel (deeper than the warm neutral-950 generic layer)
+     10° OKLCH teal-shift from Tailwind slate — see file header for before/after. */
+  --color-surface: #0b182a; /* steel-900  */
+  --color-surface-secondary: #1a2a3a; /* steel-800  */
+  --color-surface-tertiary: #2f4254; /* steel-700  */
+  --color-surface-raised: #1a2a3a; /* steel-800  */
+  --color-overlay: rgba(0, 0, 0, 0.7);
+
+  /* Borders */
+  --color-border: #2f4254; /* steel-700  */
+  --color-border-strong: #435668; /* steel-600  */
+
+  /* Text */
+  --color-text: #f8fafc; /* steel-50:  17.03:1 on surface [AAA] */
+  --color-text-secondary: #91a4b7; /* steel-400:  6.96:1 on surface [AA]  */
+  --color-text-muted: #60758a; /* steel-500:  3.74:1 — non-essential only */
+
+  /* Accent: blue-400 lifts to 7.03:1 on steel-900, clearing AAA for link text.
+     Dual-use: as a fill, dark text (#0b182a) on blue-400 gives 7.03:1 [AAA]. */
+  --color-accent: #60a5fa; /* blue-400  */
+  --color-accent-hover: #93c5fd; /* blue-300  */
+  --color-text-on-accent: #0b182a; /* steel-900 on blue-400: 7.03:1 [AAA] */
+
+  /* Accent subtle: re-derived for the cool-steel base */
+  --color-accent-subtle: color-mix(in srgb, #60a5fa 16%, #0b182a);
+
+  /* Status subtles: re-derived for cool-steel surface */
+  --color-destructive-subtle: color-mix(
+    in srgb,
+    var(--color-destructive) 14%,
+    #0b182a
+  );
+  --color-success-subtle: color-mix(in srgb, var(--color-success) 14%, #0b182a);
+  --color-warning-subtle: color-mix(in srgb, var(--color-warning) 14%, #0b182a);
+  --color-info-subtle: color-mix(in srgb, var(--color-info) 14%, #0b182a);
+
+  /* Elevation: more dramatic on dark */
+  --elevation-raised:
+    0 1px 4px rgba(0, 0, 0, 0.4), 0 1px 2px rgba(0, 0, 0, 0.3);
+  --elevation-overlay:
+    0 8px 24px rgba(0, 0, 0, 0.5), 0 3px 8px rgba(0, 0, 0, 0.3);
+
+  /* Focus ring: accent blue, visible on all dark surfaces */
+  --focus-ring-color: var(--color-accent);
+}

package/tokens/utilities.css

@@ -1056,6 +1056,15 @@
   letter-spacing: var(--type-caption-tracking);
 }
 
+.type-overline {
+  font-family: var(--type-overline-font);
+  font-size: var(--type-overline-size);
+  font-weight: var(--type-overline-weight);
+  line-height: var(--type-overline-leading);
+  letter-spacing: var(--type-overline-tracking);
+  text-transform: uppercase;
+}
+
 /* ═══════════════════════════════════════════════
    TYPOGRAPHY UTILITIES
    ═══════════════════════════════════════════════ */