The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsindex 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.tsindex 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.mdindex 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.mdindex 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`).