total-recall-brain 3.40.7 → 3.41.1

package/frontend/dist/index.html

@@ -17,8 +17,8 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,800&family=Cabinet+Grotesk:wght@700;800&family=Chivo+Mono:wght@500;700&family=Cinzel:wght@600;700;900&family=Cormorant+Garamond:ital,wght@0,600;0,700;1,600;1,700&family=DM+Mono:wght@500&family=DM+Sans:wght@500;700&family=Fraunces:opsz,wght@9..144,600;9..144,800&family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&family=Lexend:wght@600;800&family=Newsreader:ital,opsz,wght@0,6..72,600;1,6..72,600&family=Orbitron:wght@700;900&family=Outfit:wght@500;700;800&family=Plus+Jakarta+Sans:wght@600;700;800&family=Space+Grotesk:wght@600;700&family=Syne:wght@700;800&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-Bt5iVPZj.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-AGUes-VG.css">
+    <script type="module" crossorigin src="/assets/index-BtuiZqwP.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BG9NkVUy.css">
   </head>
   <body>
     <div id="root"></div>

package/frontend/src/components/plugins/PluginPanel.tsx

@@ -2,7 +2,8 @@ import { useEffect, useRef, useState } from 'react'
 import type { PluginInfo } from '../../api/plugins'
 import { runPluginCommand } from '../../api/plugins'
 import { apiFetch, API_BASE } from '../../api/_base'
-import { pluginFrameDocument, allowedFrameCommand, pluginCommandTimeouts } from './plugin-frame'
+import { pluginFrameDocument, allowedFrameCommand, pluginCommandTimeouts, sanitizePluginScreens } from './plugin-frame'
+import type { PluginScreen } from './plugin-frame'
 
 export interface PluginElement {
   id: string
@@ -37,10 +38,29 @@ export function PluginPanel({ plugin, elementId, readOnly = false }: { plugin: P
       const secrets = command.args?.filter(arg => arg.secret === true) || []
       return secrets.length === 1 && secrets[0].type === 'string' && secrets[0].flag === undefined
     }).map(command => command.name))
+    const element = elements.find(item => item.id === selected) || elements[0]
+    let ownerScreens: PluginScreen[] = []
+    const showScreen = (event: Event) => {
+      const detail = (event as CustomEvent).detail
+      if (disposed || element?.kind !== 'card' || detail?.pluginId !== plugin.id || !ownerScreens.some(screen => screen.id === detail.screen)) return
+      frame.current?.contentWindow?.postMessage({ channel, type: 'show-screen', screen: detail.screen }, '*')
+    }
     let active = 0
     const message = async (event: MessageEvent) => {
       if (disposed || event.source !== frame.current?.contentWindow || event.origin !== 'null' || event.data?.channel !== channel) return
       const data = event.data
+      if (data.type === 'screens') {
+        if (element?.kind === 'card') {
+          ownerScreens = sanitizePluginScreens(data.screens)
+          window.dispatchEvent(new CustomEvent('plugin-screens', { detail: { pluginId: plugin.id, screens: ownerScreens } }))
+        }
+        return
+      }
+      if (data.type === 'screen-changed') {
+        if (element?.kind === 'card' && ownerScreens.some(screen => screen.id === data.screen))
+          window.dispatchEvent(new CustomEvent('plugin-screen-changed', { detail: { pluginId: plugin.id, screen: data.screen } }))
+        return
+      }
       if (data.type === 'contextmenu') window.dispatchEvent(new CustomEvent('plugin-context-menu', { detail: { pluginId: plugin.id } }))
       if (data.type === 'height' && Number.isFinite(data.height)) setHeight(Math.max(128, Math.min(1000, data.height)))
       if (data.type === 'error') setError('Could not open the plugin interface')
@@ -63,8 +83,14 @@ export function PluginPanel({ plugin, elementId, readOnly = false }: { plugin: P
       }
     }
     window.addEventListener('message', message)
-    const element = elements.find(item => item.id === selected) || elements[0]
-    if (!element) return () => { disposed = true; window.removeEventListener('message', message) }
+    window.addEventListener('plugin-show-screen', showScreen)
+    const dispose = () => {
+      disposed = true
+      window.removeEventListener('message', message)
+      window.removeEventListener('plugin-show-screen', showScreen)
+      if (element?.kind === 'card') window.dispatchEvent(new CustomEvent('plugin-screens', { detail: { pluginId: plugin.id, screens: [] } }))
+    }
+    if (!element) return dispose
     const load = async () => {
       const response = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(plugin.id)}/ui/${encodeURIComponent(element.id)}`)
       if (!response.ok) throw new Error(`Could not open ${plugin.name} (${response.status})`)
@@ -74,10 +100,10 @@ export function PluginPanel({ plugin, elementId, readOnly = false }: { plugin: P
       const styles = getComputedStyle(window.document.documentElement)
       const theme: Record<string, string> = {}
       for (const name of ['--text-primary', '--text-secondary', '--text-tertiary', '--bg-primary', '--bg-secondary', '--border', '--accent', '--font-sans', '--color-text', '--color-surface', '--color-border', '--spacing-md', '--radius-md']) theme[name] = styles.getPropertyValue(name)
-      setDocument(pluginFrameDocument(source, element.tag, channel, theme, plugin.id, pluginCommandTimeouts(plugin.manifest)))
+      setDocument(pluginFrameDocument(source, element.tag, channel, theme, plugin.id, pluginCommandTimeouts(plugin.manifest), [...allowed]))
     }
     load().catch(err => { if (!disposed) setError(err.message) })
-    return () => { disposed = true; window.removeEventListener('message', message) }
+    return dispose
   }, [plugin.id, selected, plugin.sha256, elementId, readOnly])
 
   return <section>

package/frontend/src/components/plugins/card/CardEngine.tsx

@@ -1,12 +1,12 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
 import type { PluginInfo } from '../../../api/plugins'
 import { apiFetch, API_BASE } from '../../../api/_base'
-import { normalizeCard, type Card, type CardRegion } from './contract'
+import { normalizeCard, type Card } from './contract'
 import { CardRunner } from './runner'
-import { ActivityWidget, CommandsWidget, DataWidget, SettingsWidget, StatusWidget } from './widgets'
+import { ActivityWidget, CommandsWidget, SettingsWidget } from './widgets'
 import { brandStyle } from './theme'
 import { WorkspaceHost } from '../workspace/WorkspaceHost'
-import { PluginPanel, pluginElements } from '../PluginPanel'
+import { PluginPanel } from '../PluginPanel'
 import './card.css'
 import { CardScenes } from './CardScenes'
 
@@ -45,17 +45,6 @@ function Header({ card, onOpenDrawer }: { card: Card; onOpenDrawer: () => void }
   </header>
 }
 
-function Region({ region, plugin }: { region: CardRegion; plugin: PluginInfo }) {
-  switch (region.widget) {
-    case 'status': return <StatusWidget />
-    case 'live': return <PluginPanel plugin={plugin} elementId={pluginElements(plugin).find(element => element.kind === 'card')?.id} readOnly />
-    case 'actions': case 'form': case 'keypad': return <CommandsWidget region={region.command ? { ...region, commands: [region.command] } : region} />
-    case 'table': case 'detail': case 'list': case 'gauge': case 'log': return <DataWidget region={region} />
-    case 'settings': case 'credentials': return <SettingsWidget plugin={plugin} />
-    case 'activity': return <ActivityWidget />
-  }
-}
-
 function Drawer({ plugin, card, onClose }: { plugin: PluginInfo; card: Card; onClose: () => void }) {
   const hasWorkspace = Boolean(card.workspace)
   const [tab, setTab] = useState<'workspace' | 'settings' | 'commands' | 'usage'>(hasWorkspace ? 'workspace' : 'settings')
@@ -89,26 +78,29 @@ function Drawer({ plugin, card, onClose }: { plugin: PluginInfo; card: Card; onC
     <div className="card-drawer-body">
       {tab === 'workspace' && <WorkspaceHost plugin={plugin} card={card} />}
       {tab === 'settings' && <SettingsWidget plugin={plugin} />}
-      {tab === 'commands' && <CommandsWidget region={{ widget: 'actions' }} />}
+      {tab === 'commands' && <CommandsWidget />}
       {tab === 'usage' && <ActivityWidget />}
     </div>
   </aside>
 }
 
-/** One engine for every plugin; the manifest supplies layout, brand and commands. */
+/**
+ * The host gives a plugin its frame, its brand tokens and its command
+ * plumbing. The layout is the plugin's own face: CardEngine never arranges
+ * a plugin's interface and there is no shared template to fall back to.
+ */
 export function CardEngine({ plugin }: { plugin: PluginInfo }) {
   const card = useMemo(() => normalizeCard(plugin), [plugin])
-  const owned = pluginElements(plugin).some(element => element.kind === 'card' || element.kind === 'panel')
   const [drawer, setDrawer] = useState(false)
   return <CardRunner card={card}>
-    <section className={`card card-${card.template}${owned ? ' card-owned' : ''}`} style={brandStyle(card.branding)} data-density={card.branding.density} aria-label={`${card.title} card`}>
+    <section className={`card card-bespoke${card.face ? ' card-owned' : ''}`} style={brandStyle(card.branding)} data-density={card.branding.density} aria-label={`${card.title} card`}>
       <Header card={card} onOpenDrawer={() => setDrawer(true)} />
       {card.description && <p className="card-muted card-description">{card.description}</p>}
-      <CardScenes plugin={plugin}><div className="card-regions">
-        {card.regions.filter(region => !['actions', 'form', 'keypad'].includes(region.widget)).map((region, i) => <section key={i} className={`card-region card-region-${region.widget}`} style={{ gridColumn: `span ${Math.min(12, Math.max(1, region.span || 12))}` }}>
-          {region.title && <h3>{region.title}</h3>}<Region region={region} plugin={plugin} />
-        </section>)}
-      </div></CardScenes>
+      <CardScenes plugin={plugin}>
+        {card.face
+          ? <PluginPanel plugin={plugin} elementId={card.face.id} readOnly />
+          : <p className="card-error" role="alert">{plugin.name} has not supplied its card face.</p>}
+      </CardScenes>
       {card.branding.provider && <footer className="card-footer">{card.branding.provider.url ? <a href={card.branding.provider.url} target="_blank" rel="noreferrer noopener">{card.branding.provider.name}</a> : card.branding.provider.name} is a trademark of its owner. This plugin connects to the service with your own account.</footer>}
       {drawer && <Drawer plugin={plugin} card={card} onClose={() => setDrawer(false)} />}
     </section>

package/frontend/src/components/plugins/card/CardScenes.tsx

@@ -3,10 +3,18 @@ import type { ReactNode } from 'react'
 import type { PluginInfo } from '../../../api/plugins'
 import { API_BASE, apiFetch } from '../../../api/_base'
 import { useRunner } from './runner-context'
-import { CommandsWidget } from './widgets'
 import { ExecutionPicker } from './ExecutionPicker'
+import { sanitizePluginScreens } from '../plugin-frame'
+import type { PluginScreen } from '../plugin-frame'
+
+/**
+ * The host gives a plugin a place to put its screens and a way to move between
+ * them. Which screens exist, what they are called and what is on them is the
+ * plugin's design: the face declares them and reports the active one. The host
+ * never derives a screen from the command list.
+ */
+export type { PluginScreen } from '../plugin-frame'
 
-/** Generic navigation and activation; the overview stays the owner's bespoke interface. */
 export function CardScenes({ plugin, children }: { plugin: PluginInfo; children: ReactNode }) {
   const { card, busy } = useRunner()
   const [enabled, setEnabled] = useState(plugin.activation?.enabled !== false)
@@ -15,31 +23,53 @@ export function CardScenes({ plugin, children }: { plugin: PluginInfo; children:
   const [error, setError] = useState('')
   const [ownerBusy, setOwnerBusy] = useState<Record<string, string>>({})
   const [menu, setMenu] = useState(false)
+  const [screens, setScreens] = useState<PluginScreen[]>([])
+  const [activeScreen, setActiveScreen] = useState('')
+  const screensRef = useRef<PluginScreen[]>([])
   useEffect(() => {
+    screensRef.current = []
+    setScreens([]); setActiveScreen(''); setMenu(false)
     const activity = (event: Event) => {
       const detail = (event as CustomEvent).detail
       if (detail?.pluginId !== plugin.id) return
       setOwnerBusy(previous => { const next = { ...previous }; if (detail.running) next[detail.requestId] = detail.command; else delete next[detail.requestId]; return next })
     }
     const contextMenu = (event: Event) => { if ((event as CustomEvent).detail?.pluginId === plugin.id) setMenu(true) }
+    const declared = (event: Event) => {
+      const detail = (event as CustomEvent).detail
+      if (detail?.pluginId !== plugin.id) return
+      const next = sanitizePluginScreens(detail.screens)
+      screensRef.current = next
+      setScreens(next)
+      setActiveScreen(previous => next.some(screen => screen.id === previous) ? previous : next[0]?.id || '')
+    }
+    const changed = (event: Event) => {
+      const detail = (event as CustomEvent).detail
+      if (detail?.pluginId === plugin.id && screensRef.current.some(screen => screen.id === detail.screen)) setActiveScreen(detail.screen)
+    }
     window.addEventListener('plugin-command-activity', activity)
     window.addEventListener('plugin-context-menu', contextMenu)
-    return () => { window.removeEventListener('plugin-command-activity', activity); window.removeEventListener('plugin-context-menu', contextMenu) }
+    window.addEventListener('plugin-screens', declared)
+    window.addEventListener('plugin-screen-changed', changed)
+    return () => {
+      window.removeEventListener('plugin-command-activity', activity); window.removeEventListener('plugin-context-menu', contextMenu)
+      window.removeEventListener('plugin-screens', declared); window.removeEventListener('plugin-screen-changed', changed)
+    }
   }, [plugin.id])
   const running = [...busy, ...Object.values(ownerBusy)]
-  const track = useRef<HTMLDivElement>(null)
-  const names = [...card.commands.keys()]
-  const face = plugin.manifest?.card_face as { quick_actions?: Array<{ subcommand: string; label?: string }> } | undefined
-  const declared = plugin.card_face?.quick_actions || face?.quick_actions || []
-  const validActions = declared.filter(action => names.includes(action.subcommand))
-  const common = validActions.length ? validActions.slice(0, 6) : names.filter(name => !['on', 'off'].includes(name)).slice(0, 6).map(subcommand => ({ subcommand, label: subcommand }))
-  const behavior = () => window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ? 'auto' as const : 'smooth' as const
-  const openCommand = (name: string) => {
+  // The face's own screens collapse into a single mount point: the plugin keeps
+  // every screen inside its own component and reports which one is active.
+  /** Ask the face to show a screen it declared; it may ignore a name it does not own. */
+  const openScreen = (name: string) => {
+    if (!screens.some(screen => screen.id === name)) return
     setMenu(false)
-    const scene = track.current?.children[names.indexOf(name) + 1] as HTMLElement | undefined
-    if (scene && track.current) track.current.scrollTo({ left: scene.offsetLeft, behavior: behavior() })
+    window.dispatchEvent(new CustomEvent('plugin-show-screen', { detail: { pluginId: plugin.id, screen: name } }))
+  }
+  const move = (delta: number) => {
+    if (screens.length < 2) return
+    const current = Math.max(0, screens.findIndex(screen => screen.id === activeScreen))
+    openScreen(screens[(current + delta + screens.length) % screens.length].id)
   }
-  const move = (delta: number) => track.current?.scrollBy({ left: delta * track.current.clientWidth, behavior: behavior() })
   const toggle = async () => {
     setChanging(true); setError('')
     try {
@@ -56,19 +86,18 @@ export function CardScenes({ plugin, children }: { plugin: PluginInfo; children:
     <div className="card-row card-scene-controls">
       <span role="status" className="card-pill">{running.length ? `Running ${running.join(', ')}` : enabled ? 'Active' : 'Inactive'}</span>
       <button type="button" className="card-button" role="switch" aria-checked={enabled} aria-label={`${card.title} on or off`} onClick={() => void toggle()} disabled={changing || running.length > 0}>{changing ? 'Updating…' : enabled ? 'Turn off' : 'Turn on'}</button>
-      <button type="button" className="card-link" aria-label="Previous scene" onClick={() => move(-1)}>←</button>
-      <button type="button" className="card-link" aria-label="Next scene" onClick={() => move(1)}>→</button>
-      <button type="button" className="card-link" aria-haspopup="menu" aria-expanded={menu} onClick={() => setMenu(!menu)}>Quick commands</button>
+      <button type="button" className="card-link" aria-label="Previous screen" disabled={screens.length < 2} onClick={() => move(-1)}>←</button>
+      <button type="button" className="card-link" aria-label="Next screen" disabled={screens.length < 2} onClick={() => move(1)}>→</button>
+      {screens.length > 0 && <span className="card-pill" aria-label="Current screen">{screens.find(screen => screen.id === activeScreen)?.label}</span>}
+      {screens.length > 0 && <button type="button" className="card-link" aria-haspopup="menu" aria-expanded={menu} onClick={() => setMenu(!menu)}>Screens</button>}
     </div>
-    {menu && <div role="menu" aria-label={`${card.title} common commands`} className="card-context-menu">
-      {common.map(action => <button role="menuitem" type="button" className="card-link" key={action.subcommand} onClick={() => openCommand(action.subcommand)}>{action.label || action.subcommand}</button>)}
-      {!common.length && <span>No commands declared.</span>}
+    {menu && screens.length > 0 && <div role="menu" aria-label={`${card.title} declared screens`} className="card-context-menu">
+      {screens.map(screen => <button role="menuitem" type="button" className="card-link" key={screen.id} aria-current={screen.id === activeScreen ? 'page' : undefined} onClick={() => openScreen(screen.id)}>{screen.label}</button>)}
     </div>}
     {error && <p role="alert" className="card-error">{error}</p>}
     <ExecutionPicker />
-    <div className="card-scene-track" ref={track} tabIndex={0} aria-label={`${card.title} scenes`}>
-      <section className="card-scene" aria-label="Overview">{children}</section>
-      {names.map(name => <section className="card-scene" key={name} aria-label={`${name} command scene`}><CommandsWidget region={{ widget: 'actions', commands: [name] }} /></section>)}
+    <div className="card-scene-track" tabIndex={0} aria-label={`${card.title} interface`}>
+      <section className="card-scene" aria-label="Interface">{children}</section>
     </div>
   </div>
 }

package/frontend/src/components/plugins/card/card.css

@@ -9,11 +9,8 @@
 .card-badge{display:inline-block;margin:4px 6px 0 0;padding:1px 8px;border-radius:var(--card-radius);background:var(--card-accent);color:var(--card-on-accent);font-size:.7rem;font-weight:600}
 .card-badge-quiet{background:transparent;color:var(--card-muted);border:1px solid var(--card-line)}
 .card-description{margin:0}.card-muted{color:var(--card-muted);font-size:.85rem;margin:2px 0}
-.card-regions{display:grid;grid-template-columns:repeat(12,1fr);gap:var(--card-gap)}.card-region{grid-column:span 12;min-width:0}
-.card-console .card-region-status{grid-column:span 12}.card-dashboard .card-region,.card-monitor .card-region{grid-column:span 6}
-.card-workbench .card-regions,.card-inbox .card-regions{grid-template-columns:minmax(0,1fr) minmax(0,2fr)}.card-workbench .card-region,.card-inbox .card-region{grid-column:auto}
-.card-ledger .card-region-table{grid-column:span 12}.card-vault .card-region{grid-column:span 12;border-left:3px solid var(--card-accent);padding-left:var(--card-gap)}
-@media (max-width:720px){.card-regions{grid-template-columns:1fr}.card-regions>.card-region{grid-column:auto!important}}
+/* The face supplies its own layout; the host only gives it a surface. */
+.card-bespoke .card-face{display:block;min-width:0}
 .card-row{display:flex;align-items:center;gap:8px;flex-wrap:wrap}.card-kv{display:grid;grid-template-columns:repeat(auto-fit,minmax(130px,1fr));gap:8px;margin:8px 0 0}.card-kv dt{font-size:.7rem;color:var(--card-muted);text-transform:uppercase}.card-kv dd{margin:0;font-weight:600;overflow-wrap:anywhere}
 .card-pill{padding:1px 8px;border-radius:999px;font-size:.75rem;font-weight:600;border:1px solid currentColor}.card-pill-ok{color:#047857}.card-pill-warn{color:#b45309}.card-pill-error{color:#b91c1c}.card-pill-neutral{color:var(--card-muted)}
 .card-button{background:var(--card-color);color:var(--card-on-color);border:0;border-radius:var(--card-radius);padding:6px 12px;font:inherit;cursor:pointer}.card-button:disabled{opacity:.5;cursor:not-allowed}.card-button-quiet{background:transparent;color:var(--card-text);border:1px solid var(--card-line)}

package/frontend/src/components/plugins/card/contract.ts

@@ -2,14 +2,9 @@ import type { PluginInfo } from '../../../api/plugins'
 
 export type ArgType = 'string' | 'number' | 'boolean' | 'choice'
 export type Effect = 'read' | 'write' | 'destructive' | 'send'
-export type Template = 'console' | 'ledger' | 'monitor' | 'inbox' | 'dashboard' | 'workbench' | 'vault'
-export type WidgetKind = 'status' | 'actions' | 'table' | 'detail' | 'log' | 'form' | 'keypad' | 'gauge' | 'list' | 'settings' | 'credentials' | 'activity' | 'live'
-export type CellFormat = 'text' | 'number' | 'money' | 'date' | 'datetime' | 'bytes' | 'percent' | 'status'
 
 export interface CardArg { name: string; flag?: string; positional?: boolean; label: string; type: ArgType; options?: Array<string | number>; required?: boolean; secret?: boolean }
 export interface CardCommand { name: string; description?: string; args: CardArg[]; effect: Effect; output: 'json' | 'text'; timeoutMs?: number }
-export interface CardColumn { key: string; label: string; format?: CellFormat }
-export interface CardRegion { widget: WidgetKind; title?: string; source?: { command: string; args?: string[] }; columns?: CardColumn[]; command?: string; commands?: string[]; span?: number }
 export interface CardBranding {
   name: string; color: string; accent: string; font: string; density: 'compact' | 'comfortable' | 'spacious'
   radius: 'none' | 'sm' | 'md' | 'lg' | 'pill'; header: 'plain' | 'ledger-rule' | 'band' | 'tab-strip' | 'badge-left'
@@ -20,14 +15,15 @@ export interface CardWorkspace {
   tabs?: string[];
   permissions?: string[];
 }
+/** The plugin's own card face. Layout belongs to the plugin, never to a shared template. */
+export interface CardFace { id: string; tag: string; module: string; description?: string }
 export interface Card {
-  id: string; title: string; description: string; template: Template; regions: CardRegion[]
+  id: string; title: string; description: string; face?: CardFace
   commands: Map<string, CardCommand>; branding: CardBranding; status?: { command: string; refreshSeconds: number }
   distribution?: { tier: string; license: string }
   workspace?: CardWorkspace
 }
 
-const TEMPLATES: Template[] = ['console', 'ledger', 'monitor', 'inbox', 'dashboard', 'workbench', 'vault']
 const FONTS = ['system', 'inter', 'ibm-plex', 'space-grotesk', 'jetbrains-mono', 'dm-sans', 'outfit', 'fraunces', 'newsreader', 'chivo-mono']
 const HEX = /^#[0-9a-fA-F]{6}$/
 /** Manifest JSON is untyped input; every field is checked before it is used. */
@@ -71,17 +67,15 @@ export function normalizeCard(plugin: PluginInfo): Card {
   }
   const status = obj(manifest.status)
   const statusCommand = typeof status.command === 'string' && commands.has(status.command) ? status.command : undefined
-  const layout = obj(manifest.card_layout)
-  const known = (r: Loose) => r && typeof r === 'object'
-  const regions: CardRegion[] = Array.isArray(layout.regions) ? layout.regions.filter(known).slice(0, 12) : []
-  const template: Template = TEMPLATES.includes(layout.template) ? layout.template : 'console'
-  if (regions.length === 0) {
-    // No declared layout: show real state, every command with its arguments, then configuration.
-    const elements = plugin.ui?.elements || manifest.ui?.elements || []
-    if (elements.some((element: Loose) => element.kind === 'card' || element.kind === 'panel')) regions.push({ widget: 'live' })
-    if (statusCommand) regions.push({ widget: 'status', title: 'Status' })
-    regions.push({ widget: 'actions', title: 'Commands' }, { widget: 'activity', title: 'Recent activity' })
-  }
+  // The face is the plugin's own component; there is no shared layout to fall back to.
+  // Only `kind: 'card'` is the face. A plugin may declare any number of
+  // `kind: 'panel'` screens, and one declared before the card is still a
+  // secondary screen, never the face.
+  const elements: Loose[] = Array.isArray(manifest.ui?.elements) ? manifest.ui.elements : (Array.isArray(plugin.ui?.elements) ? plugin.ui.elements : [])
+  const declared = elements.find((element: Loose) => element && typeof element === 'object' && element.kind === 'card')
+  const face: CardFace | undefined = declared && typeof declared.id === 'string' && typeof declared.tag === 'string' && typeof declared.module === 'string'
+    ? { id: declared.id, tag: declared.tag, module: declared.module, description: typeof declared.description === 'string' ? declared.description : undefined }
+    : undefined
   const ws = obj(manifest.workspace)
   const workspace: CardWorkspace | undefined = ws && (ws.component || Array.isArray(ws.tabs)) ? {
     component: typeof ws.component === 'string' ? ws.component : undefined,
@@ -89,7 +83,7 @@ export function normalizeCard(plugin: PluginInfo): Card {
     permissions: Array.isArray(ws.permissions) ? ws.permissions.filter((p: unknown) => typeof p === 'string') : undefined,
   } : undefined
   return {
-    id: plugin.id, title: branding.name, description: plugin.description, template, regions, commands, branding,
+    id: plugin.id, title: branding.name, description: plugin.description, face, commands, branding,
     status: statusCommand ? { command: statusCommand, refreshSeconds: Number.isInteger(status.refresh_seconds) ? Math.min(86400, Math.max(5, status.refresh_seconds)) : 30 } : undefined,
     distribution: obj(manifest.distribution).tier ? { tier: manifest.distribution.tier, license: manifest.distribution.license } : undefined,
     workspace,

package/frontend/src/components/plugins/card/format.ts

@@ -1,4 +1,11 @@
-import type { CellFormat, Loose } from './contract'
+import type { Loose } from './contract'
+
+/**
+ * How a scalar is rendered. This is presentation owned by the card face that
+ * asks for it — not a template primitive. The layout vocabulary (`CardRegion`,
+ * `CardColumn`, `CellFormat`) that once shared these names is deleted.
+ */
+export type CellFormat = 'text' | 'number' | 'money' | 'percent' | 'bytes' | 'date' | 'datetime'
 
 export type Tone = 'ok' | 'warn' | 'error' | 'neutral'
 const GOOD = /^(ok|healthy|active|connected|ready|running|verified|delivered|sent|passed|pass|up|online|true|complete|completed)$/i

package/frontend/src/components/plugins/card/widgets.tsx

@@ -3,8 +3,8 @@ import type { PluginInfo } from '../../../api/plugins'
 import { PluginSettings } from '../PluginSettings'
 import { defaultValue, missingRequired, visibleArgs, type ArgValues } from './args'
 import { cliLine } from './cli-line'
-import type { CardColumn, CardCommand, CardRegion } from './contract'
-import { formatCell, rowsOf, scalarsOf, toneOf } from './format'
+import type { CardCommand } from './contract'
+import { scalarsOf, toneOf } from './format'
 import { useRunner, type RunResult } from './runner-context'
 import { useSource } from './use-source'
 
@@ -58,10 +58,10 @@ function ReadForm({ command }: { command: CardCommand }) {
 }
 
 /** Every declared operation, with arguments, explicit mutation confirmation and secure stdin. */
-export function CommandsWidget({ region }: { region: CardRegion }) {
+export function CommandsWidget() {
   const { card } = useRunner()
   const cliName = card.id
-  const names = region.commands || [...card.commands.keys()]
+  const names = [...card.commands.keys()]
   const [open, setOpen] = useState('')
   const [copied, setCopied] = useState('')
   return <ul className="card-commands">
@@ -83,37 +83,6 @@ export function CommandsWidget({ region }: { region: CardRegion }) {
   </ul>
 }
 
-function Cell({ value, column }: { value: unknown; column: CardColumn }) {
-  return column.format === 'status' ? <Pill tone={toneOf(value)}>{formatCell(value)}</Pill> : <>{formatCell(value, column.format)}</>
-}
-
-/** table, list, detail, gauge and log all read one declared command and show it. */
-export function DataWidget({ region }: { region: CardRegion }) {
-  const { result, loading } = useSource(region.source?.command, region.source?.args)
-  if (!result) return <p className="card-muted">{loading ? 'Loading…' : ''}</p>
-  if (!result.ok) return <Failure result={result} />
-  const { widget } = region
-  if (widget === 'log') return <pre className="card-pre">{result.text || JSON.stringify(result.data, null, 2)}</pre>
-  if (widget === 'gauge') {
-    const d = result.data || {}
-    const observedValue = d.value ?? d.used ?? d.percent
-    const observedMax = d.max ?? d.total ?? (d.percent !== undefined ? 100 : undefined)
-    const value = Number(observedValue), max = Number(observedMax)
-    if (observedValue == null || observedMax == null || !Number.isFinite(value) || !Number.isFinite(max) || max <= 0 || value < 0 || value > max) {
-      return <p role="status" className="card-muted">No valid usage measurement is available.</p>
-    }
-    const pct = max > 0 ? Math.max(0, Math.min(100, (value / max) * 100)) : 0
-    return <div><div className="card-gauge" role="meter" aria-valuenow={value} aria-valuemin={0} aria-valuemax={max}><span style={{ width: `${pct}%` }} /></div><p className="card-muted">{formatCell(value, 'number')} of {formatCell(max, 'number')}</p></div>
-  }
-  if (widget === 'detail') return <dl className="card-kv">{scalarsOf(result.data).map(([k, v]) => <div key={k}><dt>{k.replace(/_/g, ' ')}</dt><dd>{v}</dd></div>)}</dl>
-  const rows = rowsOf(result.data)
-  if (rows.length === 0) return <p className="card-muted">Nothing to show yet.</p>
-  if (widget === 'list') return <ul className="card-list">{rows.map((row, i) => <li key={i}>{typeof row === 'object' && row ? String(row.title ?? row.name ?? row.id ?? JSON.stringify(row)) : String(row)}</li>)}</ul>
-  const columns = region.columns || Object.keys(rows[0] || {}).slice(0, 5).map(key => ({ key, label: key }))
-  return <div className="card-scroll"><table className="card-table"><thead><tr>{columns.map(c => <th key={c.key} scope="col">{c.label}</th>)}</tr></thead>
-    <tbody>{rows.map((row, i) => <tr key={i}>{columns.map(c => <td key={c.key}><Cell value={row?.[c.key]} column={c} /></td>)}</tr>)}</tbody></table></div>
-}
-
 export function SettingsWidget({ plugin }: { plugin: PluginInfo }) {
   return <PluginSettings plugin={plugin} />
 }

package/frontend/src/components/plugins/plugin-frame.ts

@@ -1,7 +1,21 @@
 const inlineJson = (value: unknown) => JSON.stringify(value).replace(/</g, '\\u003c')
 
+export interface PluginScreen { id: string; label: string }
+
+/** Bound untrusted screen metadata without deriving any screen from commands. */
+export function sanitizePluginScreens(value: unknown): PluginScreen[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  return value.slice(0, 128).flatMap(item => {
+    if (!item || typeof item !== 'object' || typeof item.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(item.id)
+      || typeof item.label !== 'string' || !item.label.trim() || item.label.length > 160 || /[\u0000-\u001f\u007f]/.test(item.label) || seen.has(item.id)) return []
+    seen.add(item.id)
+    return [{ id: item.id, label: item.label.trim() }]
+  })
+}
+
 /** Owner code runs in an opaque origin, with no dashboard DOM/storage or direct network. */
-export function pluginFrameDocument(source: string, tag: string, channel: string, theme: Record<string, string> = {}, pluginId = '', commandTimeouts: Record<string, number> = {}) {
+export function pluginFrameDocument(source: string, tag: string, channel: string, theme: Record<string, string> = {}, pluginId = '', commandTimeouts: Record<string, number> = {}, operations: readonly string[] = []) {
   return `<!doctype html><html><head>
 <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'nonce-${channel}' blob:; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com data:; img-src data: https:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'">
 <meta name="referrer" content="no-referrer">
@@ -13,15 +27,27 @@ export function pluginFrameDocument(source: string, tag: string, channel: string
 const channel=${inlineJson(channel)};
 const pending=new Map();let sequence=0;
 const send=(type,extra={})=>parent.postMessage({channel,type,...extra},'*');
+let ownerScreens=[];
+const sanitizeScreens=${sanitizePluginScreens.toString()};
+function publishScreens(element){
+ ownerScreens=sanitizeScreens(element.screens);
+ send('screens',{screens:ownerScreens});
+ if(ownerScreens.some(screen=>screen.id===element.screen))host.screenChanged(element.screen);
+}
 window.addEventListener('contextmenu',event=>{event.preventDefault();send('contextmenu');});
 for(const [name,value] of Object.entries(${inlineJson(theme)}))document.documentElement.style.setProperty(name,value);
 window.addEventListener('message',event=>{
- if(event.source!==parent||event.data?.channel!==channel||event.data?.type!=='result')return;
+ if(event.source!==parent||event.data?.channel!==channel)return;
+ if(event.data.type==='show-screen'){
+  if(ownerScreens.some(screen=>screen.id===event.data.screen))window.dispatchEvent(new CustomEvent('plugin-show-screen',{detail:{pluginId:${inlineJson(pluginId)},screen:event.data.screen}}));
+  return;
+ }
+ if(event.data.type!=='result')return;
  const request=pending.get(event.data.requestId);if(!request)return;
  pending.delete(event.data.requestId);clearTimeout(request.timer);
  if(event.data.error)request.reject(new Error(event.data.error));else request.resolve(event.data.result);
 });
-const host=Object.freeze({pluginId:${inlineJson(pluginId)},run(subcommand,args=[],options={}){return new Promise((resolve,reject)=>{
+const host=Object.freeze({pluginId:${inlineJson(pluginId)},operations:Object.freeze(${inlineJson(operations)}),screenChanged(screen){if(ownerScreens.some(item=>item.id===screen))send('screen-changed',{screen});},run(subcommand,args=[],options={}){return new Promise((resolve,reject)=>{
  const requestId=String(++sequence);
  const declared=${inlineJson(commandTimeouts)}[subcommand];
  const timeout=Number.isInteger(declared)&&declared>=1&&declared<=600000?declared:30000;
@@ -34,6 +60,7 @@ try{
  const tag=${inlineJson(tag)};
  if(!customElements.get(tag))throw new Error('The plugin did not register its declared interface');
  const element=document.createElement(tag);element.host=host;document.body.append(element);
+ publishScreens(element);
  if(typeof element.load==='function'&&!element.hasAttribute('data-loaded')){try{element.load();}catch(_){}}
  if('view' in element||tag==='domains-console'||tag==='stripe-panel'){
   host.run('view').then(v=>{element.view=v;}).catch(()=>{

package/frontend/src/pages/PluginsPage.tsx

@@ -828,7 +828,8 @@ export default function PluginsPage({ activeBrainId }: PluginsPageProps) {
                 )}
               </Empty>
             ) : (
-              <div className="card-grid" style={{ gridTemplateColumns: "repeat(auto-fill, minmax(min(100%, 360px), 1fr))", gap: "22px" }}>
+              // Plugin faces are wide surfaces with screens to flip through, never narrow columns.
+              <div className="card-grid" style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 720px), 1fr))", gap: "22px" }}>
                 {shownInstalled.map((p) => {
                   return (
                     <div
@@ -836,7 +837,7 @@ export default function PluginsPage({ activeBrainId }: PluginsPageProps) {
                       onContextMenu={(e) => handleContextMenu(p, e)}
                       onTouchStart={(e) => handleTouchStart(p, e)}
                       onTouchEnd={cancelLongPress}
-                      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
+                      style={{ display: "flex", flexDirection: "column", gap: "8px", minWidth: 0 }}
                     >
                       <CardEngine plugin={p} />
                       <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "0 4px", fontSize: "11px", color: "var(--text-tertiary)", flexWrap: "wrap", gap: "6px" }}>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.40.7",
+  "version": "3.41.1",
   "description": "The Vibe Coding Brain & Autonomous Software Factory: memory, rules, secrets, and 33 visual plugins automatically managed across all your devices.",
   "type": "module",
   "bin": {

package/scaffold/.agent/skills/meta-harness/references/optimized/original.md

@@ -23,7 +23,7 @@ Total Recall connects to every major IDE, CLI harness, and local neural runtime:
   - **Lovable**: Repository root `AGENTS.md` and `CLAUDE.md`.
   - **DeepSeek Harness (`dsh`)**: `.dsh/memory/MEMORY.md` and `AGENTS.md`.
   - **OpenClaw**: `SOUL.md`, `AGENTS.md`, `USER.md`, and `MEMORY.md`.
-  - **Hermes Agent**: `.hermes/memories/MEMORY.md`, `USER.md`, and `AGENTS.md`.
+  - **Hermes Agent**: `AGENTS.md` (loaded as a context file from the git root to cwd) and `.hermes/skills/`. `~/.hermes/memories/` is Hermes' own notes store and is never written.
   - **Cline**: `.clinerules/total-recall.md` and `.cline/skills/`.
   - **VS Code**: `.github/copilot-instructions.md` and `.vscode/copilot-instructions.md`.