Skip to content

The agent that grows with you

feat(desktop): app-owned Kanban card badge slot in the plugin SDK

Tekniume1ed59ca33b0
diff --git a/apps/desktop/src/contrib/kanban-card-badges.test.ts b/apps/desktop/src/contrib/kanban-card-badges.test.ts
new file mode 100644
index 00000000000..3154e94f216
--- /dev/null
+++ b/apps/desktop/src/contrib/kanban-card-badges.test.ts
@@ -0,0 +1,160 @@
+/**
+ * The Kanban card-badge contract (#140026): plugins contribute small text
+ * badges per card through `KANBAN_CARD_AREAS.badges`; the host validates,
+ * orders, caps and paints them. These drive the REAL plugin context and
+ * registry: what a plugin can register, and what the host will accept.
+ */
+import {
+ KANBAN_CARD_AREAS,
+ KANBAN_CARD_BADGE_HUES,
+ KANBAN_CARD_BADGE_LIMITS,
+ type KanbanCard,
+ type KanbanCardBadgeContribution
+} from '@hermes/plugin-sdk'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { resolveKanbanCardBadges } from './kanban-card-badges'
+import { createPluginContext } from './plugin'
+import { registry } from './registry'
+
+const card: KanbanCard = { assignee: 'alice', id: 't_1', status: 'ready', tenant: 'acme' }
+
+const loaded: Array<() => void> = []
+
+/** Load a plugin the way the loader does: its disposers are collected and run
+ * together on unload/disable. Returns that unload. */
+function loadPlugin(id: string, contributions: Record<string, KanbanCardBadgeContribution['decorate']>) {
+ const disposers: Array<() => void> = []
+ const ctx = createPluginContext(id, dispose => disposers.push(dispose))
+
+ for (const [localId, decorate] of Object.entries(contributions)) {
+ ctx.register({ area: KANBAN_CARD_AREAS.badges, data: { decorate }, id: localId })
+ }
+
+ const unload = () => disposers.splice(0).forEach(dispose => dispose())
+ loaded.push(unload)
+
+ return unload
+}
+
+const badgesFor = (target: KanbanCard = card) =>
+ resolveKanbanCardBadges(registry.getArea(KANBAN_CARD_AREAS.badges), target)
+
+afterEach(() => {
+ loaded.splice(0).forEach(unload => unload())
+ vi.restoreAllMocks()
+})
+
+describe('kanban card badges: ordering and arbitration', () => {
+ it('orders badges by plugin id, not by load order or a plugin-chosen `order`', () => {
+ const disposers: Array<() => void> = []
+ const zeta = createPluginContext('zeta', d => disposers.push(d))
+ const alpha = createPluginContext('alpha', d => disposers.push(d))
+ loaded.push(() => disposers.splice(0).forEach(d => d()))
+
+ // zeta loads first AND bids for the front of the row; neither moves it.
+ zeta.register({ area: KANBAN_CARD_AREAS.badges, data: { decorate: () => ({ label: 'Z' }) }, id: 'b', order: -1e9 })
+ alpha.register({ area: KANBAN_CARD_AREAS.badges, data: { decorate: () => ({ label: 'A' }) }, id: 'b' })
+
+ expect(badgesFor().map(b => b.label)).toEqual(['A', 'Z'])
+ })
+
+ it('caps each plugin across all of its contributions, without starving other plugins', () => {
+ loadPlugin('noisy', {
+ one: () => [{ label: 'n1' }, { label: 'n2' }],
+ two: () => [{ label: 'n3' }, { label: 'n4' }]
+ })
+ loadPlugin('quiet', { tag: () => ({ label: 'q1' }) })
+
+ const badges = badgesFor()
+
+ expect(badges.filter(b => b.source === 'plugin:noisy')).toHaveLength(KANBAN_CARD_BADGE_LIMITS.perPlugin)
+ expect(badges.map(b => b.label)).toContain('q1')
+ })
+
+ it('a decorator that throws declines; the rest of the row still paints', () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ loadPlugin('broken', {
+ bad: () => {
+ throw new Error('boom')
+ }
+ })
+ loadPlugin('fine', { tag: () => ({ label: 'ok' }) })
+
+ expect(badgesFor().map(b => b.label)).toEqual(['ok'])
+ })
+
+ it('passes each decorator a frozen, minimal view of the card the host renders', () => {
+ let seen: unknown
+ loadPlugin('peek', {
+ tag: c => {
+ seen = c
+
+ return null
+ }
+ })
+
+ badgesFor({ ...card, title: 'secret prose', body: 'more prose' } as unknown as KanbanCard)
+
+ expect(seen).toEqual(card)
+ expect(Object.isFrozen(seen)).toBe(true)
+ })
+})
+
+describe('kanban card badges: what a plugin can put on a card', () => {
+ it('keeps text only: trims, strips control and bidi characters, and caps the length', () => {
+ loadPlugin('text', {
+ tag: () => [{ label: ` \u202Eevil\u0007 ${'x'.repeat(80)} `, tooltip: `tip\u0000 ${'y'.repeat(400)}` }]
+ })
+
+ const [badge] = badgesFor()
+
+ expect(badge.label.startsWith('evil x')).toBe(true)
+ expect([...badge.label].length).toBeLessThanOrEqual(KANBAN_CARD_BADGE_LIMITS.labelChars)
+ expect(['\u202E', '\u0007'].some(ch => badge.label.includes(ch))).toBe(false)
+ expect([...(badge.tooltip ?? '')].length).toBeLessThanOrEqual(KANBAN_CARD_BADGE_LIMITS.tooltipChars)
+ expect(badge.tooltip?.includes('\u0000')).toBe(false)
+ })
+
+ it('accepts only palette tones; anything else paints neutral', () => {
+ loadPlugin('tones', {
+ tag: () => [
+ { label: 'hue', tone: KANBAN_CARD_BADGE_HUES[3] },
+ { label: 'css', tone: 'red; background:url(x)' as never }
+ ]
+ })
+
+ expect(badgesFor().map(b => b.tone)).toEqual([KANBAN_CARD_BADGE_HUES[3], 'neutral'])
+ })
+
+ it('ignores non-text payloads: no label, a non-string label, or extra render fields', () => {
+ loadPlugin('junk', {
+ tag: () =>
+ [
+ { label: '' },
+ { label: { toString: () => 'obj' } },
+ { html: '<b>x</b>', label: 'kept', render: () => 'node' },
+ 'bare string',
+ null
+ ] as never
+ })
+
+ const badges = badgesFor()
+
+ expect(badges.map(b => b.label)).toEqual(['kept'])
+ expect(Object.keys(badges[0]).sort()).toEqual(['key', 'label', 'source', 'tone', 'tooltip'])
+ })
+})
+
+describe('kanban card badges: teardown', () => {
+ it('unloading a plugin removes every badge it contributed and leaves the others', () => {
+ const unloadA = loadPlugin('a', { one: () => ({ label: 'from a' }), two: () => ({ label: 'also a' }) })
+ loadPlugin('b', { one: () => ({ label: 'from b' }) })
+
+ expect(badgesFor().map(b => b.label)).toEqual(['from a', 'also a', 'from b'])
+
+ unloadA()
+
+ expect(badgesFor().map(b => b.label)).toEqual(['from b'])
+ })
+})
diff --git a/apps/desktop/src/contrib/kanban-card-badges.tsx b/apps/desktop/src/contrib/kanban-card-badges.tsx
new file mode 100644
index 00000000000..b5c40b4cd53
--- /dev/null
+++ b/apps/desktop/src/contrib/kanban-card-badges.tsx
@@ -0,0 +1,258 @@
+import { useStore } from '@nanostores/react'
+import { type CSSProperties, type ReactElement, useMemo } from 'react'
+
+import { Tip } from '@/components/ui/tooltip'
+import { PROFILE_SWATCHES } from '@/lib/profile-color'
+import { cn } from '@/lib/utils'
+
+import { $pluginRecords } from './plugins-store'
+import { useContributions } from './react/use-contributions'
+import type { Contribution } from './types'
+
+/**
+ * Kanban card badges — small text labels a plugin puts on Kanban card tiles
+ * (a tenant, a CI state, an estimate) without touching the board's markup.
+ *
+ * data kind (`data`): kanban.card.badges (KanbanCardBadgeContribution)
+ *
+ * The host owns everything visible: the card, the badge row's place in it,
+ * the chip's look and its tooltip. A plugin only answers `decorate(card)` with
+ * text and a palette tone; the host validates, orders and caps the answers
+ * and paints them. Plugins cannot reorder, hide or restyle each other.
+ */
+export const KANBAN_CARD_AREAS = { badges: 'kanban.card.badges' } as const
+
+/** The badge palette: the app's twelve identity hues (`PROFILE_SWATCHES`), in
+ * hue order, so `KANBAN_CARD_BADGE_HUES[hash % 12]` spreads values evenly. */
+export const KANBAN_CARD_BADGE_HUES = [
+ 'red',
+ 'orange',
+ 'yellow',
+ 'lime',
+ 'green',
+ 'mint',
+ 'cyan',
+ 'sky',
+ 'blue',
+ 'violet',
+ 'magenta',
+ 'pink'
+] as const
+
+export type KanbanCardBadgeHue = (typeof KANBAN_CARD_BADGE_HUES)[number]
+export type KanbanCardBadgeTone = 'neutral' | KanbanCardBadgeHue
+
+/** What the host accepts per card. Over-long text is shortened, never refused;
+ * badges past a plugin's cap are dropped. */
+export const KANBAN_CARD_BADGE_LIMITS = { labelChars: 24, perPlugin: 2, tooltipChars: 160 } as const
+
+/** What a decorator gets to branch on: the card's identity and routing fields,
+ * never its prose (title, body, summaries, comments, run output). Frozen.
+ * Every field is a standing compatibility promise. */
+export interface KanbanCard {
+ readonly assignee: null | string
+ /** The task id (`t_…`): the key to look up your own per-card data by. */
+ readonly id: string
+ /** The column the card is in (`triage`, `ready`, `running`, …). */
+ readonly status: string
+ readonly tenant: null | string
+}
+
+export interface KanbanCardBadge {
+ /** Plain text, shown as-is (no markup). Trimmed; control and bidi
+ * characters removed; shortened past `labelChars`. */
+ label: string
+ /** A palette hue, or `'neutral'` (the default; also what anything else
+ * becomes). */
+ tone?: KanbanCardBadgeTone
+ /** Plain-text hover line. The host always adds the plugin's name under it. */
+ tooltip?: string
+}
+
+/** Payload of a `kanban.card.badges` data contribution. Return a badge, a few
+ * badges, or `null` for cards you have nothing to say about. Keep it a pure
+ * lookup: it runs while the board renders. */
+export interface KanbanCardBadgeContribution {
+ decorate: (card: KanbanCard) => KanbanCardBadge | null | readonly KanbanCardBadge[] | undefined
+}
+
+export interface ResolvedKanbanCardBadge {
+ key: string
+ label: string
+ /** Provenance of the contribution (`plugin:<id>`), stamped by the host. */
+ source: string
+ tone: KanbanCardBadgeTone
+ tooltip: null | string
+}
+
+const TONES = new Set<string>(['neutral', ...KANBAN_CARD_BADGE_HUES])
+
+// Controls, format characters (bidi overrides, zero-width joiners) and line
+// separators: invisible text a label could use to spoof or reflow the card.
+const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\u2028\u2029]/gu
+
+function plainText(value: unknown, maxChars: number): null | string {
+ if (typeof value !== 'string') {
+ return null
+ }
+
+ const text = value.replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').trim()
+ const chars = [...text]
+
+ if (chars.length === 0) {
+ return null
+ }
+
+ return chars.length > maxChars
+ ? `${chars
+ .slice(0, maxChars - 1)
+ .join('')
+ .trimEnd()}…`
+ : text
+}
+
+function toBadge(raw: unknown): null | Omit<ResolvedKanbanCardBadge, 'key' | 'source'> {
+ if (!raw || typeof raw !== 'object') {
+ return null
+ }
+
+ const { label, tone, tooltip } = raw as Record<string, unknown>
+ const text = plainText(label, KANBAN_CARD_BADGE_LIMITS.labelChars)
+
+ if (!text) {
+ return null
+ }
+
+ return {
+ label: text,
+ tone: typeof tone === 'string' && TONES.has(tone) ? (tone as KanbanCardBadgeTone) : 'neutral',
+ tooltip: plainText(tooltip, KANBAN_CARD_BADGE_LIMITS.tooltipChars)
+ }
+}
+
+// Code-unit order, not localeCompare: the row must read the same in every locale.
+const compare = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0)
+
+// Plugin id, then contribution id. A contribution's own `order` is ignored
+// here on purpose: letting plugins bid for the front of the row is exactly
+// the contention this area exists to remove.
+const byProvenance = (a: Contribution, b: Contribution) =>
+ compare(a.source ?? 'core', b.source ?? 'core') || compare(a.id, b.id)
+
+const warned = new Set<string>()
+
+/** The badges a card shows, in row order. Pure over the area's contributions:
+ * each plugin gets at most `perPlugin` badges across all its contributions,
+ * and a decorator that throws or answers garbage simply contributes nothing. */
+export function resolveKanbanCardBadges(
+ contributions: readonly Contribution[],
+ card: KanbanCard
+): ResolvedKanbanCardBadge[] {
+ const view: KanbanCard = Object.freeze({
+ assignee: card.assignee ?? null,
+ id: card.id,
+ status: card.status,
+ tenant: card.tenant ?? null
+ })
+
+ const used = new Map<string, number>()
+ const badges: ResolvedKanbanCardBadge[] = []
+
+ for (const contribution of [...contributions].sort(byProvenance)) {
+ const source = contribution.source ?? 'core'
+ let count = used.get(source) ?? 0
+
+ if (count >= KANBAN_CARD_BADGE_LIMITS.perPlugin) {
+ continue
+ }
+
+ try {
+ const answer = (contribution.data as Partial<KanbanCardBadgeContribution> | undefined)?.decorate?.(view)
+ const list: readonly unknown[] = Array.isArray(answer) ? answer : answer ? [answer] : []
+
+ for (let index = 0; index < list.length && count < KANBAN_CARD_BADGE_LIMITS.perPlugin; index += 1) {
+ const badge = toBadge(list[index])
+
+ if (badge) {
+ badges.push({ key: `${contribution.id}:${index}`, source, ...badge })
+ count += 1
+ }
+ }
+ } catch (error) {
+ if (!warned.has(contribution.id)) {
+ warned.add(contribution.id)
+ console.warn(`[${KANBAN_CARD_AREAS.badges}] ${contribution.id} decorate() threw; its badges are skipped`, error)
+ }
+ }
+
+ used.set(source, count)
+ }
+
+ return badges
+}
+
+/** The fields of a board task the badge row reads. */
+export interface KanbanCardBadgesProps {
+ card: { assignee?: null | string; id: string; status: string; tenant?: null | string }
+}
+
+const HUE_STYLE =
+ 'bg-[color-mix(in_srgb,var(--kanban-badge-hue)_16%,transparent)] text-[color-mix(in_oklab,var(--kanban-badge-hue)_40%,var(--ui-text-primary,currentColor))] shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--kanban-badge-hue)_45%,transparent)]'
+
+// Only the host's own palette reaches `style`; no plugin string ever does.
+const hueVar = (tone: KanbanCardBadgeTone): CSSProperties | undefined => {
+ const index = KANBAN_CARD_BADGE_HUES.indexOf(tone as KanbanCardBadgeHue)
+
+ return index < 0 ? undefined : ({ '--kanban-badge-hue': PROFILE_SWATCHES[index] } as CSSProperties)
+}
+
+const pluginName = (source: string, records: ReturnType<typeof $pluginRecords.get>) => {
+ const id = source.startsWith('plugin:') ? source.slice('plugin:'.length) : source
+
+ return records[id]?.name || id
+}
+
+/** The badge row a Kanban card renders above its title. Renders nothing when
+ * no plugin has a badge for this card, so an unused area costs no space. */
+export function KanbanCardBadges({ card }: KanbanCardBadgesProps): null | ReactElement {
+ const contributions = useContributions(KANBAN_CARD_AREAS.badges)
+ const records = useStore($pluginRecords)
+ const { assignee = null, id, status, tenant = null } = card
+
+ const badges = useMemo(
+ () => resolveKanbanCardBadges(contributions, { assignee, id, status, tenant }),
+ [assignee, contributions, id, status, tenant]
+ )
+
+ if (badges.length === 0) {
+ return null
+ }
+
+ return (
+ <div className="flex min-w-0 flex-wrap items-center gap-1" data-slot="kanban-card-badges">
+ {badges.map(badge => (
+ <Tip
+ key={badge.key}
+ label={
+ <span className="flex flex-col gap-0.5">
+ {badge.tooltip && <span>{badge.tooltip}</span>}
+ <span className="text-[0.625rem] opacity-70">{pluginName(badge.source, records)}</span>
+ </span>
+ }
+ >
+ <span
+ className={cn(
+ 'inline-flex max-w-full items-center truncate rounded-[3px] px-1.5 py-0.5 text-[0.625rem] font-medium leading-none',
+ badge.tone === 'neutral' ? 'bg-muted text-muted-foreground' : HUE_STYLE
+ )}
+ data-slot="kanban-card-badge"
+ data-tone={badge.tone}
+ style={hueVar(badge.tone)}
+ >
+ {badge.label}
+ </span>
+ </Tip>
+ ))}
+ </div>
+ )
+}
diff --git a/apps/desktop/src/plugins/kanban/board.tsx b/apps/desktop/src/plugins/kanban/board.tsx
index 8b05b1fbb2c..c02153fdf24 100644
--- a/apps/desktop/src/plugins/kanban/board.tsx
+++ b/apps/desktop/src/plugins/kanban/board.tsx
@@ -34,6 +34,7 @@ import {
host,
Input,
isSubmitEnter,
+ KanbanCardBadges,
Loader,
SearchField,
Select,
@@ -304,6 +305,7 @@ function Card({
{(arc === 'running' || arc === 'stale') && !dragging && !selected && (
<span aria-hidden className={cn('kanban-arc', arc === 'stale' && 'kanban-arc--stale')} />
)}
+ <KanbanCardBadges card={task} />
<span className="line-clamp-2 text-[0.8125rem] font-medium leading-snug text-foreground">
{task.title || task.id}
</span>
diff --git a/apps/desktop/src/plugins/kanban/card-badges.test.tsx b/apps/desktop/src/plugins/kanban/card-badges.test.tsx
new file mode 100644
index 00000000000..43b9768e768
--- /dev/null
+++ b/apps/desktop/src/plugins/kanban/card-badges.test.tsx
@@ -0,0 +1,107 @@
+import { KANBAN_CARD_AREAS, type KanbanCardBadgeContribution } from '@hermes/plugin-sdk'
+/**
+ * The board paints plugin card badges (#140026): the REAL board page, the REAL
+ * plugin context and registry, with only the kanban REST layer mocked. A
+ * plugin never touches the card's DOM; it returns text and a palette tone and
+ * the board renders it in the card's own badge row.
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, cleanup, render, screen, within } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// eslint-disable-next-line no-restricted-imports
+import { createPluginContext } from '@/contrib/plugin'
+// Test harness supplies the host's locale registration, as plugin loading does.
+// eslint-disable-next-line no-restricted-imports
+import { registerPluginLocales } from '@/i18n/plugin-i18n'
+
+import type * as KanbanApi from './api'
+import { $boardSlug } from './api'
+import { KanbanBoardPage } from './board'
+import { KANBAN_LOCALES } from './i18n'
+
+vi.mock('./api', async importOriginal => ({
+ ...(await importOriginal<typeof KanbanApi>()),
+ fetchBoards: vi.fn(async () => ({
+ boards: [{ name: 'Main', project_id: null, slug: 'main', total: 2 }],
+ current: 'main'
+ })),
+ fetchBoard: vi.fn(async () => ({
+ assignees: [],
+ columns: [
+ {
+ name: 'ready',
+ tasks: [
+ { id: 't_1a2b3c', status: 'ready', tenant: 'acme', title: 'Ship the acme report' },
+ { id: 't_4d5e6f', status: 'ready', tenant: null, title: 'Untenanted chore' }
+ ]
+ }
+ ],
+ latest_event_id: 0,
+ now: 0,
+ tenants: ['acme']
+ })),
+ fetchOrchestration: vi.fn(async () => ({ default_assignee: '' })),
+ fetchProfiles: vi.fn(async () => ({ profiles: [] }))
+}))
+
+let disposeLocales: () => void = () => undefined
+let unloadPlugin: () => void = () => undefined
+
+beforeEach(() => {
+ disposeLocales = registerPluginLocales('kanban', KANBAN_LOCALES)
+
+ const disposers: Array<() => void> = []
+ const ctx = createPluginContext('tenant-labels', dispose => disposers.push(dispose))
+
+ ctx.register({
+ area: KANBAN_CARD_AREAS.badges,
+ data: {
+ decorate: ({ tenant }) =>
+ tenant ? [{ label: tenant, tone: 'blue', tooltip: `Tenant ${tenant}` }, { label: '<b>bold</b>' }] : null
+ } satisfies KanbanCardBadgeContribution,
+ id: 'tenant'
+ })
+ unloadPlugin = () => disposers.splice(0).forEach(dispose => dispose())
+})
+
+afterEach(() => {
+ cleanup()
+ unloadPlugin()
+ disposeLocales()
+ $boardSlug.set('')
+})
+
+const renderBoard = () =>
+ render(
+ <QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
+ <KanbanBoardPage />
+ </QueryClientProvider>
+ )
+
+const tileOf = (title: string) => screen.getByText(title).closest<HTMLElement>('[draggable="true"]')!
+
+describe('kanban board: plugin card badges', () => {
+ it('paints a plugin badge as plain text on the card it was decorated for, and nowhere else', async () => {
+ renderBoard()
+ await screen.findByText('Ship the acme report')
+
+ const acme = within(tileOf('Ship the acme report'))
+ const badge = acme.getByText('acme')
+
+ expect(badge.closest('[data-slot="kanban-card-badge"]')?.getAttribute('data-tone')).toBe('blue')
+ // Markup-looking text stays text: no element is created from a label.
+ expect(acme.getByText('<b>bold</b>').querySelector('b')).toBeNull()
+ expect(tileOf('Untenanted chore').querySelector('[data-slot="kanban-card-badges"]')).toBeNull()
+ })
+
+ it('unloading the plugin removes its badges from the live board', async () => {
+ const { container } = renderBoard()
+ await screen.findByText('acme')
+
+ act(() => unloadPlugin())
+
+ expect(screen.queryByText('acme')).toBeNull()
+ expect(container.querySelector('[data-slot="kanban-card-badges"]')).toBeNull()
+ })
+})
diff --git a/apps/desktop/src/sdk/areas.ts b/apps/desktop/src/sdk/areas.ts
index 4b7fc4b4da5..21a3307c8ec 100644
--- a/apps/desktop/src/sdk/areas.ts
+++ b/apps/desktop/src/sdk/areas.ts
@@ -1,5 +1,6 @@
-// Host-owned contribution areas with no feature module of their own; the SDK
-// barrel re-exports them.
+// Contribution-area constants the SDK barrel re-exports whole: host-owned
+// areas with no feature module of their own, plus area contracts whose module
+// lives in core but has no other public door.
export const PANES_AREA = 'panes'
export const STATUSBAR_AREAS = { left: 'statusBar.left', right: 'statusBar.right' } as const
@@ -8,3 +9,20 @@ export const STATUSBAR_AREAS = { left: 'statusBar.left', right: 'statusBar.right
* runs once per registration, not once per route. Page-owned controls that
* should exist only while a page is up go to `WORKSPACE_PAGE_HEADER_AREA`. */
export const TITLEBAR_AREAS = { center: 'titleBar.center', left: 'titleBar.left', right: 'titleBar.right' } as const
+/** Per-card labels on Kanban tiles: register a `KANBAN_CARD_AREAS.badges`
+ * data contribution whose `decorate({ id, status, tenant, assignee })`
+ * returns `{ label, tone?, tooltip? }` (or a few, or `null`). Core paints
+ * them as text chips in the card's badge row, ordered by plugin id, capped
+ * per plugin, removed with the plugin. Never touch the board's markup.
+ * `KanbanCardBadges` is the row the board itself renders. */
+export {
+ KANBAN_CARD_AREAS,
+ KANBAN_CARD_BADGE_HUES,
+ KANBAN_CARD_BADGE_LIMITS,
+ type KanbanCard,
+ type KanbanCardBadge,
+ type KanbanCardBadgeContribution,
+ type KanbanCardBadgeHue,
+ KanbanCardBadges,
+ type KanbanCardBadgeTone
+} from '@/contrib/kanban-card-badges'
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index 1771079ce63..730700da4b0 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -122,7 +122,7 @@ import { sessionsHost } from './sessions'
import { desktopSettings } from './settings'
/** Pane, status bar and titlebar slots; see `./areas` for the mount rules. */
-export { PANES_AREA, STATUSBAR_AREAS, TITLEBAR_AREAS } from './areas'
+export * from './areas'
/** The plugin authoring contract (`HermesPlugin`, `PluginContext`, `ctx.*` door types). */
export type * from './plugin-contract'
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index 2b2eb438b77..ef5db00471e 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -239,6 +239,7 @@ Import the area constants from the SDK; each area has its own `data` payload.
| Theme | `THEMES_AREA` | `data` as a `DesktopTheme` |
| Composer | `COMPOSER_AREAS.*` | render slots, or middleware / attachment providers |
| Model menu rows | `MODEL_MENU_ROW_AREA` | `data: ModelMenuRowContribution` — a leading icon / trailing badge per model |
+| Kanban card badges | `KANBAN_CARD_AREAS.badges` | `data: KanbanCardBadgeContribution` — short text labels per card, painted by the board |
| Appearance settings | `APPEARANCE_AREAS.extra` | `render` — controls appended to Settings → Appearance |
| Plugin settings page | `SETTINGS_PLUGINS_AREA` (`'settings.plugins'`) | Use `ctx.registerSettingsPage({ id, title, render, icon?, order?, children? })` — your own entry (with sub-pages) under Settings → Plugins |
@@ -759,6 +760,88 @@ images onto them. The same marks come from `decorate({ provider })` returning
`{ icon: <img alt="" src={providerSvgDataUrl(provider)} /> }` — no DOM reads,
and the row keeps working when the menu's markup changes.
+#### Kanban card badges {#kanban-card-badges}
+
+`KANBAN_CARD_AREAS.badges` puts small text labels on Kanban card tiles: a
+tenant, a CI state, an estimate. A contribution supplies `decorate(card)`; the
+board paints what it returns as chips in a fixed row above the card's title.
+The card's markup, layout, drag and drop, click and context menu stay the
+board's, and the row takes no space on cards no plugin has a badge for.
+
+```ts
+import {
+ KANBAN_CARD_AREAS,
+ KANBAN_CARD_BADGE_HUES,
+ type KanbanCardBadgeContribution
+} from '@hermes/plugin-sdk'
+
+interface KanbanCard { // frozen; identity and routing fields only
+ id: string // task id (t_…): key your own per-card data by it
+ status: string // the column: 'triage', 'ready', 'running', …
+ tenant: string | null
+ assignee: string | null
+}
+interface KanbanCardBadge {
+ label: string // plain text
+ tone?: KanbanCardBadgeTone // 'neutral' (default) or one of KANBAN_CARD_BADGE_HUES
+ tooltip?: string // plain text hover line
+}
+
+ctx.register({
+ area: KANBAN_CARD_AREAS.badges,
+ id: 'tenant',
+ data: {
+ decorate: ({ tenant }) =>
+ tenant ? { label: tenant, tone: KANBAN_CARD_BADGE_HUES[hash(tenant) % 12], tooltip: `Tenant: ${tenant}` } : null
+ } satisfies KanbanCardBadgeContribution
+})
+```
+
+`decorate` may return one badge, an array, or `null` for cards it has nothing
+to say about. The card view carries no prose (title, body, summaries,
+comments, run output); look up anything else you need by `id` in your own data
+(`ctx.rest` to your backend, `ctx.storage`).
+
+**What the board accepts** (`KANBAN_CARD_BADGE_LIMITS`):
+
+- **Text only.** `label` and `tooltip` must be strings and render as text, never
+ markup. Control characters, bidi overrides and zero-width characters are
+ removed, whitespace is collapsed, and text past 24 characters (`label`) or
+ 160 characters (`tooltip`) is shortened with an ellipsis. An empty or
+ non-string label is ignored. Any other field (`render`, `html`, a style) is
+ ignored.
+- **A fixed palette.** `tone` is `'neutral'` or one of the twelve
+ `KANBAN_CARD_BADGE_HUES` (`'red'`, `'orange'`, … `'pink'`, the app's identity
+ hues in hue order, the same set as `PROFILE_SWATCHES`). Anything else paints
+ neutral. The board picks the actual colors for the theme.
+- **Two badges per plugin per card**, counted across all of the plugin's
+ contributions to this area. Extra badges are dropped.
+- **Attribution.** Every badge's tooltip ends with the plugin's name, so a user
+ can always tell which plugin painted it.
+
+**Arbitration.** Every plugin's badges show side by side; no plugin can hide,
+reorder or restyle another's. The row is ordered by plugin id, then
+contribution id, then the order `decorate` returned them. A contribution's
+`order` field is ignored here, so load order and bidding cannot move a badge.
+A decorator that **throws** contributes nothing (logged once) and the rest of
+the row still paints.
+
+**Updates and teardown.** `decorate()` re-runs when the registry changes or
+when the card's id, status, tenant or assignee changes, so keep it a pure
+lookup. When your own data changes (a user pins a new color in your settings
+page), call `ctx.register` again with the same `id`: the new registration
+replaces the old one and the board repaints. Keep the latest disposer; the
+first one would remove the replacement. On disable, reload or unload, the
+host removes the contribution and the cards repaint without its badges;
+nothing to undo in `ctx.onDispose`.
+
+**Migrating a DOM-decorating plugin** (kanban-tenant-labels): delete the route
+poll, the `MutationObserver`, the tile matching, the inserted `<span>` and the
+reads of the Kanban plugin's query cache. The whole decoration becomes the
+`ctx.register` call above, with the plugin's color pins mapped to
+`KANBAN_CARD_BADGE_HUES` (its twelve hues are the same `hsl(n×30 68% 58%)`
+set, in the same order).
+
### Appearance settings
`APPEARANCE_AREAS.extra` renders contributions at the end of **Settings →
@@ -2033,8 +2116,8 @@ pipeline as a trust boundary.
|----------|---------|
| Host | `host` (`.state.*`, `.settings`, `.notify`, `.notifyError`, `.navigate`, `.onEvent`, `.logs`, `.status`, `.restartGateway`, `.request`, `.composer`, `.sessions`, `.skills`, `.toolsets`, `.profiles`, `.pluginDecisions`) |
| Plugin contract | `HermesPlugin`, `PluginContext`, `PluginContribution`, `PluginStorage`, `PluginOs`, `PluginPet`, `PetSayOptions`, `PetMessageTone`, `PluginAppActionId`, `PluginAppActionInfo`, `PluginRunActionResult`, `PLUGIN_APP_ACTIONS`, `PluginRestOptions`, `PluginNativeNotificationInput`, `PluginNotificationAction`, `HermesOpenTarget`, `Contribution` |
-| Area constants | `PANES_AREA`, `ROUTES_AREA`, `SIDEBAR_NAV_AREA`, `STATUSBAR_AREAS`, `TITLEBAR_AREAS`, `WORKSPACE_PAGE_HEADER_AREA`, `PALETTE_AREA`, `KEYBINDS_AREA`, `THEMES_AREA`, `COMPOSER_AREAS`, `MODEL_MENU_ROW_AREA`, `SESSION_ROW_AREAS`, `SIDEBAR_NAV_PREFS_AREA`, `APPEARANCE_AREAS`, `SETTINGS_PLUGINS_AREA` |
-| Area payloads | `PluginSettingsPage`, `PluginSettingsSubpage` (+ `pluginSettingsHref`), `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider`, `SessionRowSlotContribution`, `SidebarNavPrefsContribution` |
+| Area constants | `PANES_AREA`, `ROUTES_AREA`, `SIDEBAR_NAV_AREA`, `STATUSBAR_AREAS`, `TITLEBAR_AREAS`, `WORKSPACE_PAGE_HEADER_AREA`, `PALETTE_AREA`, `KEYBINDS_AREA`, `THEMES_AREA`, `COMPOSER_AREAS`, `MODEL_MENU_ROW_AREA`, `KANBAN_CARD_AREAS`, `SESSION_ROW_AREAS`, `SIDEBAR_NAV_PREFS_AREA`, `APPEARANCE_AREAS`, `SETTINGS_PLUGINS_AREA` |
+| Area payloads | `PluginSettingsPage`, `PluginSettingsSubpage` (+ `pluginSettingsHref`), `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider`, `SessionRowSlotContribution`, `KanbanCardBadgeContribution` (+ `KanbanCard`, `KanbanCardBadge`, `KanbanCardBadgeTone`, `KANBAN_CARD_BADGE_HUES`, `KANBAN_CARD_BADGE_LIMITS`), `SidebarNavPrefsContribution` |
| React / state | `useValue`, `atom`, `computed`, `useQuery`, `useMutation`, `useQueryClient`, `queryClient`, `Contribute`, `WorkspacePageHeaderControl` |
| Theming | `useTheme`, `requestTheme`, `setAccentOverride`, `$accentOverride`, `retintTheme`, `themeHue`, `DesktopTheme`, `DesktopThemeColors`, plus OKLCH math (`hexToOklch`, `oklchToHex`, `oklchToSrgb255`, `mixOklab`, `maxChroma`, `hueDelta`, `normalizeHex`) and sRGB measures (`contrastRatio` — `number | null`, null for unparseable input — `readableOn`) |
| UI kit | `Button`, `Input`, `Textarea`, `Select*`, `Switch`, `Checkbox`, `SegmentedControl`, `Tabs*`, `Dialog*`, `ConfirmDialog`, `DropdownMenu*`, `ContextMenu*`, `Popover*`, `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`, `SearchField`, `ScrollArea`, `Separator`, `Skeleton`, `GlyphSpinner`, `Loader`, `EmptyState`, `ErrorState`, `CopyButton`, `StatusDot`, `LogView`, `Codicon`, `DecodeText`, `SandboxedFrame` |
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index 7d8751f1747..dacb7c60466 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -926,7 +926,7 @@ Tasks in `~/.hermes/kanban.db` are profile-agnostic on purpose (that's the coord
### Extending it
-The plugin uses the standard Hermes dashboard plugin contract — see [Extending the Dashboard](./extending-the-dashboard) for the full manifest reference, shell slots, page-scoped slots, and the Plugin SDK. Extra columns, custom card chrome, tenant-filtered layouts, or full `tab.override` replacements are all expressible without forking this plugin.
+The plugin uses the standard Hermes dashboard plugin contract — see [Extending the Dashboard](./extending-the-dashboard) for the full manifest reference, shell slots, page-scoped slots, and the Plugin SDK. Extra columns, tenant-filtered layouts, or full `tab.override` replacements are all expressible without forking this plugin. The dashboard has no per-card slot; on the desktop board, plugins add per-card labels through the `KANBAN_CARD_AREAS.badges` contribution area (see [Desktop Plugin SDK](../../developer-guide/desktop-plugin-sdk.md#kanban-card-badges)).
To disable without removing: add `dashboard.plugins.kanban.enabled: false` to `config.yaml` (or delete `plugins/kanban/dashboard/manifest.json`).