@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/hooks/use-view-data.test.tsx

@@ -1,31 +1,32 @@
+import { QueryClient } from "@tanstack/react-query"
 import { renderToStaticMarkup } from "react-dom/server"
 import { describe, expect, it, vi } from "vitest"
+import { toolQueryKey } from "../lib/tool-query.js"
 import { AppQueryProvider } from "../providers/query-provider.js"
-import { useViewData, type ViewDataResult } from "./use-view-data.js"
+import { useViewData, type UseViewDataOptions, type ViewDataResult } from "./use-view-data.js"
 
 type Demo = { n: number }
 type CallTool = (name: string, args: object) => Promise<unknown>
 
+const KEY = ["use-view-data.test"] as const
+const ARGS = { id: 1 }
+
 /** Renders a probe once (SSR, the house path) and hands back the hook's result. */
 function probe(
   initialData: Demo | null,
   ready: boolean,
   callTool: CallTool,
   key: string,
+  options?: UseViewDataOptions<Demo> & { client?: QueryClient; toolNameInQueryKey?: boolean },
 ): ViewDataResult<Demo> {
   let result: ViewDataResult<Demo> | undefined
+  const { client, toolNameInQueryKey, ...hookOptions } = options ?? {}
   function Probe() {
-    result = useViewData<Demo>(
-      initialData,
-      ["use-view-data.test", key],
-      "demo_data",
-      { id: 1 },
-      ready,
-    )
+    result = useViewData<Demo>(initialData, [...KEY, key], "demo_data", ARGS, ready, hookOptions)
     return null
   }
   renderToStaticMarkup(
-    <AppQueryProvider callTool={callTool}>
+    <AppQueryProvider callTool={callTool} client={client} toolNameInQueryKey={toolNameInQueryKey}>
       <Probe />
     </AppQueryProvider>,
   )
@@ -48,6 +49,16 @@ describe("useViewData", () => {
     expect(result).toMatchObject({ data: null, loading: false, error: null })
   })
 
+  it("exposes the query's progress: failureCount, failureReason, isFetching, isPlaceholderData", () => {
+    const result = probe(null, false, vi.fn<CallTool>(), "progress")
+    expect(result).toMatchObject({
+      failureCount: 0,
+      failureReason: null,
+      isFetching: false,
+      isPlaceholderData: false,
+    })
+  })
+
   it("refetch calls the tool again: the retry an error state offers", async () => {
     const callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: { n: 2 } }))
     const result = probe(null, false, callTool, "refetch")
@@ -57,4 +68,102 @@ describe("useViewData", () => {
       expect(callTool).toHaveBeenCalledWith("demo_data", { id: 1 })
     })
   })
+
+  it("enabled: false gates the feed next to ready; a ready feed without data is loading", () => {
+    const client = new QueryClient()
+    expect(probe(null, true, vi.fn<CallTool>(), "gated", { client, enabled: false }).loading).toBe(
+      false,
+    )
+    expect(probe(null, true, vi.fn<CallTool>(), "open", { client }).loading).toBe(true)
+  })
+
+  it("a function gate that says no idles like enabled: false, never an endless skeleton", () => {
+    const client = new QueryClient()
+    const closed = probe(null, true, vi.fn<CallTool>(), "fn-closed", {
+      client,
+      enabled: () => false,
+    })
+    expect(closed).toMatchObject({ data: null, loading: false, error: null })
+    const open = probe(null, true, vi.fn<CallTool>(), "fn-open", { client, enabled: () => true })
+    expect(open.loading).toBe(true)
+    // Not ready keeps it off whatever the gate says.
+    expect(
+      probe(null, false, vi.fn<CallTool>(), "fn-not-ready", { client, enabled: () => true })
+        .loading,
+    ).toBe(false)
+  })
+
+  it("passes TanStack's options through: initialData-free placeholderData shows meanwhile", () => {
+    const client = new QueryClient()
+    const result = probe(null, true, vi.fn<CallTool>(), "placeholder", {
+      client,
+      placeholderData: { n: 0 },
+    })
+    expect(result).toMatchObject({ data: { n: 0 }, isPlaceholderData: true, loading: false })
+  })
+})
+
+describe('useViewData initialDataMode: "seed" (the live standalone view)', () => {
+  const cacheKey = (key: string) => toolQueryKey([...KEY, key], "demo_data", ARGS)
+
+  it("seeds the feed's cache entry with the host's payload and returns it", () => {
+    const client = new QueryClient()
+    const result = probe({ n: 1 }, true, vi.fn<CallTool>(), "seeded", {
+      client,
+      initialDataMode: "seed",
+      initialDataUpdatedAt: 1234,
+    })
+    expect(result).toMatchObject({ data: { n: 1 }, loading: false })
+    expect(client.getQueryData(cacheKey("seeded"))).toEqual({ n: 1 })
+    expect(client.getQueryState(cacheKey("seeded"))?.dataUpdatedAt).toBe(1234)
+  })
+
+  it("with toolNameInQueryKey the seed lands under the key carrying the tool name", () => {
+    const client = new QueryClient()
+    const result = probe({ n: 1 }, true, vi.fn<CallTool>(), "tool-key", {
+      client,
+      initialDataMode: "seed",
+      toolNameInQueryKey: true,
+    })
+    expect(result.data).toEqual({ n: 1 })
+    expect(client.getQueryData([...KEY, "tool-key", "demo_data", ARGS])).toEqual({ n: 1 })
+    expect(client.getQueryData(cacheKey("tool-key")), "never the 2.x key").toBeUndefined()
+  })
+
+  it("static mode never writes the cache", () => {
+    const client = new QueryClient()
+    probe({ n: 1 }, true, vi.fn<CallTool>(), "static", { client })
+    expect(client.getQueryData(cacheKey("static"))).toBeUndefined()
+  })
+
+  it("the cached answer wins over the seed it came from once the feed answered anew", () => {
+    const client = new QueryClient()
+    probe({ n: 1 }, true, vi.fn<CallTool>(), "refetched", { client, initialDataMode: "seed" })
+    client.setQueryData(cacheKey("refetched"), { n: 2 })
+    const remounted = probe({ n: 1 }, true, vi.fn<CallTool>(), "refetched", {
+      client,
+      initialDataMode: "seed",
+      initialDataUpdatedAt: () => 99,
+    })
+    expect(remounted.data, "an old payload never rolls the answer back").toEqual({ n: 2 })
+    const delivered = probe({ n: 3 }, true, vi.fn<CallTool>(), "refetched", {
+      client,
+      initialDataMode: "seed",
+    })
+    expect(delivered.data, "a new delivery wins").toEqual({ n: 3 })
+  })
+
+  it("refetch over a seeded entry reads the feed again", async () => {
+    const client = new QueryClient()
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: { n: 2 } }))
+    const result = probe({ n: 1 }, true, callTool, "seed-refetch", {
+      client,
+      initialDataMode: "seed",
+    })
+    result.refetch()
+    await vi.waitFor(() => {
+      expect(client.getQueryData(cacheKey("seed-refetch"))).toEqual({ n: 2 })
+    })
+    expect(callTool).toHaveBeenCalledWith("demo_data", ARGS)
+  })
 })

package/src/hooks/use-view-data.ts

@@ -1,5 +1,7 @@
-import { useCallback } from "react"
-import { useToolQuery } from "./use-tool-query.js"
+import { useCallback, useState } from "react"
+import { hashKey, useQueryClient } from "@tanstack/react-query"
+import { seedToolQuery, type UseToolQueryOptions } from "../lib/tool-query.js"
+import { useToolQuery, useToolQueryKey } from "./use-tool-query.js"
 
 export interface ViewDataResult<T> {
   data: T | null
@@ -7,23 +9,66 @@ export interface ViewDataResult<T> {
   loading: boolean
   error: Error | null
   /**
-   * Fetch `tool` again: the retry of an error state
-   * (`<ErrorState onRetry={refetch} … />`). Host-pushed data, when present,
-   * stays what `data` returns.
+   * Fetch `tool` again now: the retry of an error state
+   * (`<ErrorState onRetry={refetch} … />`) or a manual refresh — a new read
+   * even while a failed fetch still waits on its retry backoff. In `"static"`
+   * mode host-pushed data, when present, stays what `data` returns.
    */
   refetch: () => void
+  /** Failed attempts of the current fetch (0 once it succeeds). */
+  failureCount: number
+  /**
+   * The current fetch's last failed attempt — set from the first failure on,
+   * while the query still retries (`error` waits for the last retry).
+   */
+  failureReason: Error | null
+  /** A fetch is in flight (the first one or a refetch). */
+  isFetching: boolean
+  /**
+   * `data` is a placeholder (`placeholderData`, e.g. `keepPreviousData`):
+   * the previous args' answer while the current args' fetch runs or failed.
+   */
+  isPlaceholderData: boolean
+}
+
+/**
+ * How {@link useViewData} treats host-pushed `initialData`.
+ *
+ * - `"static"` (default): returned verbatim; the feed query stays off while
+ *   it is present.
+ * - `"seed"`: it becomes the feed query's cached answer, and the query stays
+ *   live (once `ready`): an invalidation after a write, a `refetch` or a
+ *   retry re-reads the feed. A fresh seed is not refetched on mount (it is
+ *   younger than `staleTime`); a payload delivered anew (content not seeded
+ *   for the key before) replaces the cached answer, while a re-rendered or
+ *   remounted old one never rolls a refetched answer back.
+ */
+export type ViewDataMode = "static" | "seed"
+
+/**
+ * Options of {@link useViewData}: TanStack's query options for the feed
+ * (`retry`, `retryDelay`, `staleTime`, `placeholderData` /
+ * `keepPreviousData`, `enabled` as an extra gate next to `ready`, …),
+ * plus how host data seeds it.
+ */
+export type UseViewDataOptions<T> = Omit<UseToolQueryOptions<T>, "initialData" | "select"> & {
+  initialDataMode?: ViewDataMode
 }
 
 /**
  * The seam that lets one widget component serve both modes without a duplicate UI.
  *
  * Standalone (a `*_show_*` widget) the agent's tool result is handed in via
- * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`) and
- * returned verbatim. Embedded in a self-fetching cockpit only scope params are
- * passed, so the component fetches `tool` with `args` under `key` — disabled
- * unless data is absent AND `ready` (i.e. the required id/key is present).
- * Sibling widgets sharing `key` dedupe to a single call, so a composed view of
- * N widgets over one data feed fetches once.
+ * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`).
+ * Embedded in a self-fetching cockpit only scope params are passed, so the
+ * component fetches `tool` with `args` under `key`, gated on `ready` (i.e.
+ * the required id/key is present). Sibling widgets sharing `key` and `args`
+ * dedupe to a single call, so a composed view of N widgets over one data
+ * feed fetches once.
+ *
+ * By default host data is returned verbatim and switches the query off;
+ * `initialDataMode: "seed"` keeps the query live over it instead (see
+ * {@link ViewDataMode}). `options` passes TanStack's query options through.
  */
 export function useViewData<T>(
   initialData: T | null | undefined,
@@ -31,12 +76,77 @@ export function useViewData<T>(
   tool: string,
   args: Record<string, unknown>,
   ready: boolean,
+  options?: UseViewDataOptions<T>,
 ): ViewDataResult<T> {
-  const query = useToolQuery<T>([...key], tool, args, { enabled: !initialData && ready })
-  const data = initialData ?? query.data ?? null
-  const { refetch: refetchQuery } = query
-  const refetch = useCallback(() => {
-    void refetchQuery()
-  }, [refetchQuery])
-  return { data, loading: !data && ready && !query.isError, error: query.error ?? null, refetch }
+  const { initialDataMode = "static", enabled, ...queryOptions } = options ?? {}
+  const seeding = initialDataMode === "seed"
+  const cacheKey = useStableKey(useToolQueryKey(key, tool, args))
+  useSeed(seeding ? initialData : null, cacheKey, queryOptions.initialDataUpdatedAt)
+
+  const active = ready && enabled !== false
+  const fetches = active && (seeding || !initialData)
+  const query = useToolQuery<T>([...key], tool, args, {
+    ...queryOptions,
+    enabled: typeof enabled === "function" ? (q) => fetches && enabled(q) : fetches,
+  })
+  const data = seeding ? (query.data ?? initialData) : (initialData ?? query.data)
+  const refetch = useFreshRefetch(cacheKey, query.refetch)
+  return {
+    data: data ?? null,
+    // The query's own verdict: a function `enabled` that returns false idles
+    // like `enabled: false`, never an endless skeleton.
+    loading: !data && query.isEnabled && !query.isError,
+    error: query.error,
+    refetch,
+    failureCount: query.failureCount,
+    failureReason: query.failureReason,
+    isFetching: query.isFetching,
+    isPlaceholderData: query.isPlaceholderData,
+  }
+}
+
+/** `key`, kept by content: callers build `key`/`args` anew every render. */
+function useStableKey(key: unknown[]): unknown[] {
+  const id = hashKey(key)
+  const [stable, setStable] = useState({ id, key })
+  if (stable.id !== id) setStable({ id, key })
+  return stable.id === id ? stable.key : key
+}
+
+/**
+ * `"seed"` mode: write the host's payload into the feed's cache entry in the
+ * render phase, before the query's observer reads the cache — what TanStack's
+ * own `initialData` does (see {@link seedToolQuery} for when it wins over a
+ * cached answer). The last processed seed skips the content check while the
+ * same object comes in render after render.
+ */
+function useSeed(
+  seed: unknown,
+  cacheKey: unknown[],
+  updatedAt: number | (() => number | undefined) | undefined,
+): void {
+  const client = useQueryClient()
+  const keyId = hashKey(cacheKey)
+  const [seen, setSeen] = useState<{ seed: unknown; keyId: string } | null>(null)
+  if (seed == null || (seen?.seed === seed && seen.keyId === keyId)) return
+  const at = typeof updatedAt === "function" ? updatedAt() : updatedAt
+  const written = seedToolQuery(client, cacheKey, seed, at)
+  // Only a real change re-renders: an equal new object per render must not loop.
+  if (written || seen?.keyId !== keyId) setSeen({ seed, keyId })
+}
+
+/**
+ * A refetch that reads anew at once. TanStack restarts an in-flight fetch only
+ * over data (`cancelRefetch`); a key without data joins the running retry
+ * chain and waits out its backoff. So cancel that chain first, then read.
+ */
+function useFreshRefetch(cacheKey: unknown[], refetchQuery: () => Promise<unknown>): () => void {
+  const client = useQueryClient()
+  return useCallback(() => {
+    if (client.getQueryData(cacheKey) !== undefined) {
+      void refetchQuery()
+      return
+    }
+    void client.cancelQueries({ queryKey: cacheKey, exact: true }).then(() => refetchQuery())
+  }, [client, cacheKey, refetchQuery])
 }

package/src/hooks/use-view-tool-query.ts

@@ -1,10 +1,15 @@
 import { useQuery, type UseQueryResult } from "@tanstack/react-query"
-import { useCallTool } from "../providers/query-provider.js"
+import { useCallTool, useToolNameInQueryKey } from "../providers/query-provider.js"
 import { parseViewToolResult } from "../lib/parse-tool-result.js"
+import { toolQueryOptions, type UseToolQueryOptions } from "../lib/tool-query.js"
+import { useRefetchOnTransport, useToolKeyGuard } from "./use-tool-query.js"
 
-export interface UseViewToolQueryOptions {
-  enabled?: boolean
-}
+/**
+ * Options of {@link useViewToolQuery}: TanStack's query options, passed
+ * through like `useToolQuery`'s (`enabled`, `retry`, `staleTime`,
+ * `placeholderData`, `initialData`, …).
+ */
+export type UseViewToolQueryOptions<T = unknown> = UseToolQueryOptions<T>
 
 /**
  * Self-fetch hook for `*_show_*` widget tools — the envelope-unwrapping sibling
@@ -14,25 +19,26 @@ export interface UseViewToolQueryOptions {
  * envelope; this hook decodes via {@link parseViewToolResult} (single-step →
  * flat data, multi-step → keyed by step id) instead.
  *
- * `args` is appended to the effective query key — same queryKey-vs-args
- * contract as {@link useToolQuery}, so sibling widgets sharing a query key
- * collapse to a single deduped tool call.
+ * Same key and options contract as {@link useToolQuery}: the effective key is
+ * `[...queryKey, args]` (`[...queryKey, toolName, args]` under an
+ * `AppQueryProvider` with `toolNameInQueryKey`), so sibling widgets sharing a
+ * query key and args collapse to a single deduped tool call.
  */
 export function useViewToolQuery<T = unknown>(
-  queryKey: unknown[],
+  queryKey: readonly unknown[],
   toolName: string,
   args: object,
-  opts?: UseViewToolQueryOptions,
+  opts?: UseViewToolQueryOptions<T>,
 ): UseQueryResult<T, Error> {
   const callTool = useCallTool()
-
-  return useQuery<T, Error>({
-    queryKey: [...queryKey, args],
-    queryFn: async () => {
-      if (!callTool) throw new Error("callTool not available")
-      const result = await callTool(toolName, args)
-      return parseViewToolResult<T>(result)
-    },
-    enabled: !!callTool && (opts?.enabled ?? true),
-  })
+  const toolNameInKey = useToolNameInQueryKey()
+  useToolKeyGuard(queryKey, toolName, args)
+  const query = useQuery<T, Error>(
+    toolQueryOptions<T>(queryKey, toolName, args, callTool, opts, {
+      decode: parseViewToolResult,
+      toolNameInKey,
+    }),
+  )
+  useRefetchOnTransport(callTool, query)
+  return query
 }

package/src/i18n-coverage.test.tsx

@@ -17,6 +17,7 @@ import { BuilderBanners } from "./app/builder/BuilderBanners.js"
 import { PipelineStrip } from "./app/builder/PipelineStrip.js"
 import { StatusChip } from "./app/builder/status-chip.js"
 import { Toolbar } from "./app/builder/Toolbar.js"
+import { Workspace } from "./app/builder/Workspace.js"
 import { WidgetCrashFallback, WidgetRenderer } from "./app/widget-renderer.js"
 
 /**
@@ -135,6 +136,26 @@ const CHROME_CASES: { name: string; render: () => ReactElement }[] = [
       />
     ),
   },
+  {
+    name: "ViewPlaceholder blocked (a writing tool, no retry)",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: undefined, canRetry: false, kind: "blocked" }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "ViewPlaceholder blocked (load the view)",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: undefined, canRetry: true, kind: "blocked" }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
   {
     name: "StepErrors without a refresh",
     render: () => (
@@ -167,6 +188,7 @@ const CHROME_CASES: { name: string; render: () => ReactElement }[] = [
         onRefresh={asyncNoop}
         onEnterBuildMode={noop}
         onToggleFullscreen={asyncNoop}
+        dataAsOf="14:32"
       />
     ),
   },
@@ -236,7 +258,7 @@ const CHROME_CASES: { name: string; render: () => ReactElement }[] = [
     ),
   },
   {
-    name: "Builder toolbar",
+    name: "Builder toolbar (advanced, unsaved)",
     render: () => (
       <Toolbar
         L={PSEUDO.builder}
@@ -246,13 +268,93 @@ const CHROME_CASES: { name: string; render: () => ReactElement }[] = [
         liveKeys={2}
         reachableCount={5}
         unreachableCount={1}
+        advanced
+        onToggleAdvanced={noop}
+        unsaved
         onOpenCatalogue={noop}
         onOpenSave={noop}
-        onDone={noop}
+        onDiscard={noop}
+        onApply={noop}
         hasAnyCell
       />
     ),
   },
+  {
+    name: "Builder workspace (titled and untitled palette entries, canvas cells)",
+    render: () => (
+      <Workspace
+        L={PSEUDO.builder}
+        paletteByApp={[
+          [
+            "demo",
+            [
+              {
+                id: "demo:orders",
+                app: "demo",
+                requires: ["demo:key"],
+                size: "full",
+                title: { en: "Orders", de: "Bestellungen" },
+                summary: { de: "Alle offenen Bestellungen." },
+              },
+              { id: "demo:raw", app: "demo", requires: [], size: "half" },
+            ],
+          ],
+        ]}
+        appDisplayByName={new Map()}
+        paletteCount={2}
+        paletteLoading={false}
+        onOpenDataSources={noop}
+        activeRows={[{ row: [{ widget: "demo:orders" }] }, { row: [] }]}
+        focusedRowIndex={0}
+        setFocusedRowIndex={noop}
+        dragOverRow={null}
+        setDragOverRow={noop}
+        onAddRow={noop}
+        onRemoveRow={noop}
+        onMoveRow={noop}
+        onSetCellSpan={noop}
+        onRemoveCell={noop}
+        onAddWidget={noop}
+        onConfigureCell={noop}
+        propsSchemaByWidgetId={new Map([["demo:orders", { type: "object" }]])}
+        displayByWidgetId={new Map([["demo:orders", { title: { de: "Bestellungen" } }]])}
+        advanced
+        widgets={{}}
+        widgetProps={{ keys: {}, context: { keys: {}, steps: {}, errors: [] } }}
+        onAddTab={noop}
+      />
+    ),
+  },
+  ...[true, false].map((paletteLoading) => ({
+    name: `Builder workspace (palette ${paletteLoading ? "loading" : "empty"})`,
+    render: () => (
+      <Workspace
+        L={PSEUDO.builder}
+        paletteByApp={[]}
+        appDisplayByName={new Map()}
+        paletteCount={0}
+        paletteLoading={paletteLoading}
+        onOpenDataSources={noop}
+        activeRows={[{ row: [] }]}
+        focusedRowIndex={0}
+        setFocusedRowIndex={noop}
+        dragOverRow={null}
+        setDragOverRow={noop}
+        onAddRow={noop}
+        onRemoveRow={noop}
+        onMoveRow={noop}
+        onSetCellSpan={noop}
+        onRemoveCell={noop}
+        onAddWidget={noop}
+        onConfigureCell={noop}
+        propsSchemaByWidgetId={new Map()}
+        displayByWidgetId={new Map()}
+        advanced={false}
+        widgets={{}}
+        widgetProps={{ keys: {}, context: { keys: {}, steps: {}, errors: [] } }}
+      />
+    ),
+  })),
   {
     name: "Builder data sources",
     render: () => (

package/src/index.ts

@@ -66,16 +66,40 @@ export {
 // NOTE: the view-tool hooks (`useViewToolQuery`, `useViewData`) are exported
 // from the `./hooks` subpath only — see `packages/ui/src/hooks/index.ts`.
 export { useIsMobile } from "./hooks/use-mobile.js"
-export { useToolQuery, useToolMutation } from "./hooks/use-tool-query.js"
-export type { UseToolQueryOptions } from "./hooks/use-tool-query.js"
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./hooks/use-tool-query.js"
+export type { UseToolQueryOptions, UseToolMutationOptions } from "./hooks/use-tool-query.js"
+// The query layer's contract: the effective cache key, the opt-in retry
+// policy (no retry of a tool's own isError answer), and TanStack's
+// keepPreviousData for `placeholderData`, so a consumer needs no direct
+// @tanstack/react-query import for the common options.
+export { toolQueryKey, shouldRetryToolCall } from "./lib/tool-query.js"
+export { ToolResultError, isToolError } from "./lib/parse-tool-result.js"
+export { keepPreviousData } from "@tanstack/react-query"
 export { useDebouncedValue } from "./hooks/use-debounced-value.js"
 
 // Tone token system — the semantic status tones (ToneVariant + TONE_* maps)
-// behind the tone-aware components below. Pure data + class strings. Three
+// behind the tone-aware components below. Pure data + class strings. ONE
+// vocabulary (TONE_VARIANTS; retired names map through resolveTone). Three
 // roles per tone: colour (TONE_DOT/TONE_BORDER/TONE_ICON), tint (TONE_SOFT,
-// foreground text on it), text on a plain surface (TONE_TEXT, the -ink role).
-export { TONE_SOFT, TONE_DOT, TONE_TEXT, TONE_BORDER, TONE_ICON } from "./lib/tone-utils.js"
-export type { ToneVariant } from "./lib/tone-utils.js"
+// foreground text on it; TONE_TINT alone), text on a plain surface (TONE_INK,
+// the -ink role; TONE_TEXT is its deprecated name).
+export {
+  TONE_VARIANTS,
+  TONE_ALIASES,
+  resolveTone,
+  isToneVariant,
+  TONE_SOFT,
+  TONE_TINT,
+  TONE_DOT,
+  TONE_INK,
+  TONE_TEXT,
+  TONE_BORDER,
+  TONE_ICON,
+} from "./lib/tone-utils.js"
+export type { ToneVariant, ToneAlias, ToneName } from "./lib/tone-utils.js"
+// The type scale (CI §4): text-title/section/body/dense/small utilities, 13 px floor.
+export { TYPE_SCALE, TYPE_STEPS, TYPE_FLOOR_PX, MICRO_LABEL } from "./lib/typography.js"
+export type { TypeStep } from "./lib/typography.js"
 // The kit's opaque focus ring as class strings, for custom controls.
 export { FOCUS_RING, FOCUS_RING_INSET } from "./lib/focus-ring.js"
 
@@ -83,14 +107,24 @@ export { FOCUS_RING, FOCUS_RING_INSET } from "./lib/focus-ring.js"
 // primitives. Pure (React + primitives + cn), so they live in the root barrel.
 export { GridLayout, GridItem } from "./components/GridLayout.js"
 export type { GridLayoutProps, GridItemProps } from "./components/GridLayout.js"
-export { KpiGrid } from "./components/KpiGrid.js"
-export type { KpiGridProps, KpiGridHeader, KpiCell } from "./components/KpiGrid.js"
-export { LivePill, CountPill } from "./components/Pills.js"
-export type { LivePillProps, CountPillProps } from "./components/Pills.js"
+export { KpiGrid, KpiGridSkeleton } from "./components/KpiGrid.js"
+export type {
+  KpiGridProps,
+  KpiGridHeader,
+  KpiCell,
+  KpiGridSkeletonProps,
+} from "./components/KpiGrid.js"
+export { LivePill, CountPill, StatusBadge } from "./components/Pills.js"
+export type {
+  LivePillProps,
+  CountPillProps,
+  StatusBadgeProps,
+  StatusBadgeText,
+} from "./components/Pills.js"
 export { SectionHeading } from "./components/SectionHeading.js"
 export type { SectionHeadingProps } from "./components/SectionHeading.js"
 export { WidgetHeader } from "./components/WidgetHeader.js"
-export type { WidgetHeaderProps } from "./components/WidgetHeader.js"
+export type { WidgetHeaderProps, WidgetHeadingLevel } from "./components/WidgetHeader.js"
 export { GroupCard } from "./components/GroupCard.js"
 export type { GroupCardProps } from "./components/GroupCard.js"
 export { FilterBar } from "./components/FilterBar.js"
@@ -99,6 +133,8 @@ export { DrillButton } from "./components/DrillButton.js"
 export type { DrillButtonProps } from "./components/DrillButton.js"
 export { ListFooter } from "./components/ListFooter.js"
 export type { ListFooterProps } from "./components/ListFooter.js"
+export { PagedListFooter } from "./components/PagedListFooter.js"
+export type { PagedListFooterProps, PagedListState } from "./components/PagedListFooter.js"
 
 // Feedback and states — one pattern each for toasts, empty and error states.
 export { ToastProvider, useToast } from "./components/Toast.js"
@@ -166,6 +202,7 @@ export type {
   BoundTranslate,
   BuilderMessages,
   CommonMessages,
+  FilterBarMessages,
   ListFooterMessages,
   PropsSheetMessages,
   RendererMessages,