@softize/opus 12.3.0 → 12.5.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.5.0 — 2026-08-24
+
+Cache vira porta do protocolo. `CacheAdapter` chega aos handlers como `ctx.cache`, com a superfície
+mínima que um handler usa — `get`, `set`, `delete` — e cresce por reincidência, como a do storage.
+O **miss é o `null`**: quem observa a execução distingue acerto de ausência pelo retorno, sem o
+adapter reportar métrica por fora, e erro de infraestrutura continua sendo exceção — cache
+indisponível não deve virar "não estava em cache".
+
+`cache/memory` é o driver de processo, para desenvolvimento e para quem roda numa instância só.
+Expira preguiçosamente (a entrada vencida some quando alguém a procura, sem timer permanente),
+tem teto de entradas para não crescer sem limite dentro de um servidor de longa duração, e expõe
+`sweep()` e `size()` para quem quiser forçar a limpeza ou observar o tamanho.
+
+Nada é obrigatório: sem adapter montado, `ctx.cache` é `null` e o handler decide o que fazer.
+
+## 12.4.0 — 2026-08-24
+
+Superfícies de trabalho — canvas, editor, preview — ganham os dois lugares que faltavam. `Dock`
+ancora as ferramentas à própria superfície, com `DockGroup` separando intenções e `DockAction`
+distinguindo modo de execução; a barra é uma `toolbar` de verdade, com setas e Home/End entre as
+ações. `SurfaceStatus` recebe o que a superfície diz sobre si — salvamento, versão, execução
+percorrida — num canto estável, fora da barra: estado não é ação, e uma toolbar que carrega texto
+vivo deixa de ser navegável como toolbar.
+
+O truncamento passa a ter uma segunda forma. `Truncate` aceita `fade`, e a utilitária
+`truncate-fade` esmaece o fim da linha no lugar das reticências. O hook `useOverflowing`, extraído
+do próprio `Truncate`, fica exposto para quem precisa do sinal de corte sem o tooltip — é o que
+mantém a máscara fora do texto que cabe inteiro.
+
+`SidebarItem` vira a linha das árvores de navegação: `actions`, `onToggle`/`expanded` e
+`dropPosition` são irmãos do destino, nunca botões aninhados, e o rótulo cortado esmaece até a
+borda. Ele e o item do `ShellNav` também ganham foco visível com o anel do `Button` — antes a
+navegação por teclado caía no anel do navegador, que destoa do tema.
+
+Entram ainda `Dot`, para estado compacto onde o contexto já explica o significado, e
+`Table variant="framed"`, que traz para o componente a moldura de datagrid antes montada à mão em
+cada consumidor. `Select` passa a aplicar `className` na raiz do controle em todos os modos.
+
+O `opus copy` reconhece `Dock.label`, `DockAction.label` e `DockAction.hint`: componente com texto
+em prop precisa entrar no mapa de papéis, senão a copy sai do inventário em silêncio quando uma
+superfície migra de `aria-label` para prop.
+
+Tudo é aditivo e não exige migração. Consumidores que montavam a moldura da tabela à mão podem
+trocar o wrapper por `variant="framed"` quando quiserem.
+
 ## 12.3.0 — 2026-08-23
 
 O Opus deixa de definir `font-size` em `html`. A fonte raiz volta a pertencer ao navegador e à

package/bin/cli.mjs

@@ -509,8 +509,8 @@ Fundação de UI (só apps web — preset Tailwind + tema + flags do Opus):
   tema/tsconfig/dep — avisa o que falta plugar (não edita seus arquivos: sem clobber)
 
 Este comando materializa somente os artefatos Opus. O template encadeia
-\`opus setup && base setup\`: a Base 2.0 é obrigatória quando o gate universal de copy
-está habilitado; Maestro continua opcional.
+\`opus setup && base setup\`: a versão da Base registrada em base.json é obrigatória quando
+o gate universal de copy está habilitado; Maestro continua opcional.
 `)
       return
     }

package/bin/lib/copy.mjs

@@ -130,6 +130,10 @@ const JSX_PROP_ROLES = new Map([
   ['Alert', new Map([['title', 'title'], ['description', 'message']])],
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
   ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
+  // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
+  ['Dock', new Map([['label', 'label']])],
+  ['DockAction', new Map([['label', 'label'], ['hint', 'description']])],
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],

package/docs/releasing.md

@@ -53,7 +53,7 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.0.0` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.1.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
@@ -63,7 +63,7 @@ um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.0.0`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.1.0`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.3.0",
+  "version": "12.5.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -122,6 +122,14 @@
     "./storage": "./src/storage/index.ts",
     "./storage/fs": "./src/storage/drivers/fs.ts",
     "./storage/s3": "./src/storage/drivers/s3.ts",
+    "./cache": {
+      "types": "./src/cache/index.ts",
+      "default": "./src/cache/index.ts"
+    },
+    "./cache/memory": {
+      "types": "./src/cache/drivers/memory.ts",
+      "default": "./src/cache/drivers/memory.ts"
+    },
     "./ai": "./src/ai/index.ts",
     "./ai/anthropic": "./src/ai/drivers/anthropic.ts",
     "./mcp": "./src/mcp/index.ts",
@@ -201,7 +209,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@softize/base": "^2.0.0",
     "@radix-ui/react-checkbox": "^1.1.3",
     "@radix-ui/react-dialog": "^1.1.4",
     "@radix-ui/react-dropdown-menu": "^2.1.4",
@@ -211,6 +218,7 @@
     "@radix-ui/react-slot": "^1.1.1",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
+    "@softize/base": "^2.1.0",
     "@tailwindcss/typography": "^0.5.20",
     "@types/markdown-it": "^14.1.2",
     "class-variance-authority": "^0.7.1",
@@ -234,11 +242,11 @@
     "zod-to-json-schema": "^3.23.0"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.9.0",
     "@anthropic-ai/sdk": ">=0.35.0",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0",
     "@hookform/resolvers": "^3.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@tanstack/react-query": "^5.0.0",
     "bullmq": "^5.0.0",
     "fastify": "^5.0.0",

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.0.0",
+    "@softize/base": "^2.1.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

package/src/cache/drivers/memory.ts

@@ -0,0 +1,82 @@
+/**
+ * Driver de cache em memória do processo.
+ *
+ * Serve desenvolvimento e o caso de um único processo. Não compartilha nada entre
+ * instâncias — quem precisa disso usa um driver distribuído, e a troca é só a montagem.
+ *
+ * A expiração é preguiçosa: a entrada vencida some quando alguém a procura. Sem varredura
+ * de fundo, um cache de processo não justifica um timer permanente; `sweep()` existe para
+ * quem quiser forçar a limpeza.
+ */
+import type { CacheAdapter, CacheSetOptions } from '../../core/index.ts'
+
+interface Entry {
+  value: unknown
+  /** Epoch em milissegundos; `null` = não expira. */
+  expiresAt: number | null
+}
+
+export interface MemoryCacheOptions {
+  /** Expiração padrão quando a chamada não passa `ttlSeconds`. Ausente = não expira. */
+  defaultTtlSeconds?: number
+  /** Teto de entradas. Passando dele, a mais antiga sai — um cache de processo não deve
+   *  crescer sem limite dentro de um servidor de longa duração. */
+  maxEntries?: number
+}
+
+export interface MemoryCache extends CacheAdapter {
+  /** Remove as entradas vencidas agora. */
+  sweep(): number
+  /** Quantas entradas o cache guarda neste momento. */
+  size(): number
+}
+
+export function memoryCache(options: MemoryCacheOptions = {}): MemoryCache {
+  const entries = new Map<string, Entry>()
+  const maxEntries = options.maxEntries ?? 10_000
+
+  const expired = (entry: Entry, now: number): boolean => entry.expiresAt !== null && entry.expiresAt <= now
+
+  return {
+    name: 'memory',
+    kind: 'cache',
+    get<T>(key: string): Promise<T | null> {
+      const entry = entries.get(key)
+      if (entry === undefined) return Promise.resolve(null)
+      if (expired(entry, Date.now())) {
+        entries.delete(key)
+        return Promise.resolve(null)
+      }
+      return Promise.resolve(entry.value as T)
+    },
+    set<T>(key: string, value: T, opts: CacheSetOptions = {}): Promise<void> {
+      const ttl = opts.ttlSeconds ?? options.defaultTtlSeconds
+      // Reinserir move a chave para o fim da ordem do Map, que é o que faz o descarte
+      // abaixo tirar a MAIS ANTIGA, e não a que acabou de ser escrita.
+      entries.delete(key)
+      entries.set(key, { value, expiresAt: ttl === undefined ? null : Date.now() + ttl * 1000 })
+      if (entries.size > maxEntries) {
+        const oldest = entries.keys().next()
+        if (!oldest.done) entries.delete(oldest.value)
+      }
+      return Promise.resolve()
+    },
+    delete(key: string): Promise<void> {
+      entries.delete(key)
+      return Promise.resolve()
+    },
+    sweep(): number {
+      const now = Date.now()
+      let removed = 0
+      for (const [key, entry] of entries) {
+        if (expired(entry, now)) {
+          entries.delete(key)
+          removed += 1
+        }
+      }
+      return removed
+    },
+    size: () => entries.size,
+    healthCheck: () => Promise.resolve({ ok: true as const, details: { entries: entries.size } }),
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @softize/opus/cache — helpers compartilhados dos drivers de cache.
+ *
+ * EXPERIMENTAL. O contrato (`CacheAdapter`) vive no core; o driver de memória fica em
+ * `cache/memory`. A superfície é a mínima que um handler usa — guardar, ler, remover — e
+ * cresce por reincidência, não por especulação.
+ */
+
+export type { CacheAdapter, CacheSetOptions } from '../core/index.ts'
+
+/** Monta uma chave estável a partir de partes. Evita a concatenação à mão que produz
+ *  chaves parecidas e colidentes entre domínios. */
+export function cacheKey(...parts: (string | number)[]): string {
+  return parts.map((part) => String(part)).join(':')
+}

package/src/core/index.ts

@@ -99,6 +99,8 @@ export type {
   SchedulerAdapter,
   ClientAdapter,
   StorageAdapter,
+  CacheAdapter,
+  CacheSetOptions,
   StoragePutOptions,
   StorageObject,
   AiAdapter,

package/src/core/runtime.ts

@@ -61,6 +61,7 @@ import type {
   SchedulerAdapter,
   ServerAdapter,
   StorageAdapter,
+  CacheAdapter,
   AiAdapter,
   AiRunOptions,
   BoundAiRunOptions,
@@ -97,6 +98,8 @@ export interface RuntimeSetup {
   client?: ClientAdapter
   /** EXPERIMENTAL — storage de objetos (arquivos); chega nos handlers via `ctx.storage`. */
   storage?: StorageAdapter
+  /** EXPERIMENTAL — cache de leitura; chega nos handlers via `ctx.cache`. */
+  cache?: CacheAdapter
   /** EXPERIMENTAL — IA generativa (complete/extract); chega nos handlers via `ctx.ai`. */
   ai?: AiAdapter
 
@@ -243,6 +246,7 @@ export class Runtime {
   private readonly scheduler: SchedulerAdapter | undefined
   private readonly client: ClientAdapter | undefined
   private readonly storage: StorageAdapter | undefined
+  private readonly cache: CacheAdapter | undefined
   private readonly ai: AiAdapter | undefined
   /** Cache das tools derivadas das actions `ai:enabled` (registry é estático pós-start). */
   private aiToolsCache: AiTool[] | null = null
@@ -293,6 +297,7 @@ export class Runtime {
     this.scheduler = setup.scheduler
     this.client = setup.client
     this.storage = setup.storage
+    this.cache = setup.cache
     this.ai = setup.ai
   }
 
@@ -764,6 +769,7 @@ export class Runtime {
     if (this.scheduler !== undefined) yield this.scheduler
     if (this.client !== undefined) yield this.client
     if (this.storage !== undefined) yield this.storage
+    if (this.cache !== undefined) yield this.cache
     if (this.ai !== undefined) yield this.ai
   }
 
@@ -860,6 +866,7 @@ export class Runtime {
       log,
       emit: this.buildEmit(action, actionId, base, trace),
       storage: this.storage ?? null,
+      cache: this.cache ?? null,
       ai: this.bindAi({ ...base, ...(trace !== undefined ? { trace } : {}) }),
       provenance,
       ...(trace !== undefined ? { trace } : {}),
@@ -1192,6 +1199,7 @@ export class Runtime {
       log: reactionLog,
       emit: noopEmit,
       storage: this.storage ?? null,
+      cache: this.cache ?? null,
       // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
       // padrão — nada de LLM disparado por evento chamando action gated sem gate explícito).
       ai: this.bindAi({

package/src/core/types.ts

@@ -277,6 +277,7 @@ export interface ActionContext {
   log: Logger
   emit: EmitFn
   storage: StorageAdapter | null
+  cache: CacheAdapter | null
   ai: BoundAi | null
   provenance: Provenance
   trace?: TraceContext
@@ -294,6 +295,7 @@ export interface ReactionContext {
   log: Logger
   emit: EmitFn
   storage: StorageAdapter | null
+  cache: CacheAdapter | null
   ai: BoundAi | null
   provenance: Provenance
   trace?: TraceContext
@@ -941,6 +943,7 @@ export type AdapterKind =
   | 'scheduler'
   | 'client'
   | 'storage'
+  | 'cache'
   | 'ai'
   | 'ui'
   | 'schema'
@@ -1167,6 +1170,28 @@ export interface StorageAdapter extends Adapter {
   url(key: string, opts?: { expiresInSeconds?: number }): Promise<string>
 }
 
+/**
+ * EXPERIMENTAL — cache de leitura. A superfície é a mínima que um handler usa e cresce
+ * por reincidência, como a do storage.
+ *
+ * O MISS é o `null`: quem observa a execução distingue acerto de ausência pelo retorno,
+ * sem o adapter precisar reportar métrica por fora. Erro de infraestrutura é outra coisa
+ * e continua sendo exceção — cache indisponível não deve virar "não estava em cache".
+ */
+export interface CacheAdapter extends Adapter {
+  kind: 'cache'
+  /** Valor guardado, ou `null` quando a chave não está presente (ou expirou). */
+  get<T>(key: string): Promise<T | null>
+  /** Guarda o valor. Sem `ttlSeconds`, a expiração é a que o driver definir. */
+  set<T>(key: string, value: T, opts?: CacheSetOptions): Promise<void>
+  /** Remove. Idempotente: remover o que não existe não é erro. */
+  delete(key: string): Promise<void>
+}
+
+export interface CacheSetOptions {
+  ttlSeconds?: number
+}
+
 /** Opções por chamada do `AiAdapter` — tudo tem default do driver. */
 export interface AiCompleteOptions {
   /** System prompt da chamada. */

package/src/testing/index.ts

@@ -43,6 +43,7 @@ import type {
   Paginated,
   Schema,
   StorageAdapter,
+  CacheAdapter,
   StorageObject,
   StoragePutOptions,
   User,
@@ -72,6 +73,7 @@ export interface TestContextOptions {
   can?: ActionContext['can']
   db?: unknown
   storage?: StorageAdapter | null
+  cache?: CacheAdapter | null
   ai?: AiAdapter | null
   meta?: Record<string, unknown>
   trace?: TraceContext
@@ -133,6 +135,7 @@ export function testContext(options: TestContextOptions = {}): TestContext {
       return Promise.resolve()
     },
     storage: options.storage ?? null,
+    cache: options.cache ?? null,
     ai: options.ai ? toBoundAi(options.ai) : null,
     provenance: { kind: 'system', source: 'test' },
     ...(options.trace !== undefined ? { trace: options.trace } : {}),

package/src/ui/components/patterns/dock.tsx

@@ -0,0 +1,182 @@
+/**
+ * <Dock /> — a barra de ferramentas que flutua sobre uma superfície de trabalho.
+ *
+ * Canvas, editor e preview têm o mesmo problema: as ferramentas não cabem num cabeçalho
+ * sem empilhar mais uma faixa de chrome sobre a trilha que a aplicação já desenha. A Dock
+ * resolve isso ancorando as ações à própria superfície, agrupadas e sempre visíveis.
+ *
+ * O componente é dono da moldura, dos separadores entre grupos, da forma dos botões e da
+ * semântica de toolbar (`role="toolbar"` com navegação por setas). QUAIS ferramentas
+ * existem e o que cada uma faz continua sendo da aplicação.
+ *
+ * Requer `<TooltipProvider>` na raiz do app — cada ação nomeia-se por tooltip.
+ */
+
+import * as React from 'react'
+import { cn } from '../../lib/cn.ts'
+import { Button } from '../primitives/button.tsx'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip.tsx'
+
+const POSITION = {
+  bottom: 'bottom-3 left-1/2 -translate-x-1/2',
+  'bottom-left': 'bottom-3 left-3',
+  'bottom-right': 'bottom-3 right-3',
+} as const
+
+export interface DockProps {
+  /** Aresta da superfície onde a barra se ancora. */
+  position?: keyof typeof POSITION
+  /** Nome acessível da barra; é o que a tecnologia assistiva anuncia ao entrar nela. */
+  label: string
+  className?: string
+  children: React.ReactNode
+}
+
+/** Barra flutuante ancorada à superfície. O contêiner precisa ser `relative`. */
+export function Dock({ position = 'bottom', label, className, children }: DockProps): React.ReactElement {
+  const ref = React.useRef<HTMLDivElement>(null)
+
+  // Navegação de toolbar: as setas andam entre as ações, e Home/End vão às pontas. Sem isso
+  // uma barra com dez ícones cobra dez Tabs de quem navega por teclado.
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
+    const keys = ['ArrowRight', 'ArrowLeft', 'Home', 'End']
+    if (!keys.includes(event.key) || ref.current === null) return
+    const items = Array.from(ref.current.querySelectorAll<HTMLButtonElement>('button:not([disabled])'))
+    if (items.length === 0) return
+    const current = items.indexOf(document.activeElement as HTMLButtonElement)
+    if (current === -1) return
+    event.preventDefault()
+    const next =
+      event.key === 'Home'
+        ? 0
+        : event.key === 'End'
+          ? items.length - 1
+          : event.key === 'ArrowRight'
+            ? (current + 1) % items.length
+            : (current - 1 + items.length) % items.length
+    items[next]?.focus()
+  }
+
+  return (
+    <div
+      ref={ref}
+      data-slot="dock"
+      role="toolbar"
+      aria-label={label}
+      aria-orientation="horizontal"
+      onKeyDown={onKeyDown}
+      className={cn(
+        'absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-1.5 overflow-x-auto',
+        'rounded-2xl border border-border bg-background/95 p-1.5 shadow-lg backdrop-blur',
+        POSITION[position],
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/** Grupo de ações afins. A divisória entre grupos é do componente, não do consumidor. */
+export function DockGroup({ className, children }: { className?: string; children: React.ReactNode }): React.ReactElement {
+  return (
+    <div
+      data-slot="dock-group"
+      className={cn(
+        'flex shrink-0 flex-row items-center gap-1 border-l border-border pl-1.5',
+        'first:border-l-0 first:pl-0',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+export interface DockActionProps {
+  icon: React.ReactNode
+  /** Nome da ação: vai para o tooltip e para o nome acessível. */
+  label: string
+  /** Presente quando a ação liga um modo; ausente quando ela apenas executa. */
+  pressed?: boolean
+  disabled?: boolean
+  /** Conteúdo do tooltip quando ele precisa dizer mais que o rótulo. */
+  hint?: React.ReactNode
+  className?: string
+  onClick: () => void
+}
+
+/** Ação de ícone da Dock. Com `pressed`, comunica modo ligado em vez de execução. */
+export function DockAction({ icon, label, pressed, disabled = false, hint, className, onClick }: DockActionProps): React.ReactElement {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          data-slot="dock-action"
+          size="icon"
+          variant={pressed === true ? 'default' : 'ghost'}
+          aria-label={label}
+          aria-pressed={pressed}
+          disabled={disabled}
+          onClick={onClick}
+          className={cn('size-9 shrink-0 rounded-xl', className)}
+        >
+          {icon}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>{hint ?? label}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+const STATUS_POSITION = {
+  'top-right': 'top-3 right-3',
+  'top-left': 'top-3 left-3',
+} as const
+
+export interface SurfaceStatusProps {
+  /** Canto da superfície onde o estado se ancora. */
+  position?: keyof typeof STATUS_POSITION
+  /** Ações do recurso aberto — em geral o mesmo menu que a linha dele tem na navegação. */
+  actions?: React.ReactNode
+  className?: string
+  children?: React.ReactNode
+}
+
+/**
+ * O que a superfície diz sobre SI — salvamento, versão, execução percorrida — flutuando no canto,
+ * separado das ferramentas. Fica fora da Dock de propósito: estado não é ação, e uma toolbar que
+ * carrega texto vivo deixa de ser navegável como toolbar.
+ *
+ * A região é `role="status"` com `aria-live="polite"`: a mudança é anunciada sem roubar o foco.
+ * Mensagem de sucesso é transitória por natureza; falha permanece até o estado mudar. Quem decide
+ * isso é a aplicação, que conhece o ciclo — o componente só reserva o lugar.
+ */
+export function SurfaceStatus({ position = 'top-right', actions, className, children }: SurfaceStatusProps): React.ReactElement {
+  const hasActions = actions !== undefined && actions !== null
+  return (
+    <div
+      data-slot="surface-status"
+      className={cn(
+        'pointer-events-none absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-2',
+        'rounded-full border border-border bg-background/95 py-1.5 pl-3 text-xs text-muted-foreground shadow-sm backdrop-blur',
+        hasActions ? 'pr-1' : 'pr-3',
+        STATUS_POSITION[position],
+        className,
+      )}
+    >
+      {/* Só o texto é região viva: anunciar o menu a cada mudança de estado seria ruído. */}
+      <span role="status" aria-live="polite" className="flex min-w-0 flex-row items-center gap-2">
+        {children}
+      </span>
+      {hasActions && (
+        <span
+          data-slot="surface-status-actions"
+          className="pointer-events-auto flex shrink-0 items-center [&_button]:size-6 [&_button]:rounded-full [&_svg]:size-3.5"
+        >
+          {actions}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/ui/components/patterns/shell-nav.tsx

@@ -74,6 +74,7 @@ function renderItem(item: ShellNavItem, activeId: string | undefined, onSelect:
       className={cn(
         'flex w-full items-center gap-2.5 rounded-md py-1.5 text-left text-sm transition-colors',
         'disabled:pointer-events-none disabled:opacity-40',
+        'outline-none focus-visible:ring-2 focus-visible:ring-ring/50',
         railed ? 'justify-center px-0' : 'px-2.5',
         active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
       )}

package/src/ui/components/patterns/sidebar.tsx

@@ -1,4 +1,6 @@
-import { createContext, useContext, type ReactNode } from 'react'
+import { createContext, useContext, type HTMLAttributes, type ReactNode } from 'react'
+import { ChevronRight } from 'lucide-react'
+import { useOverflowing } from '../../lib/overflow.ts'
 import { cn } from '../../lib/cn.ts'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
 
@@ -50,22 +52,58 @@ export interface SidebarItemProps {
   badge?: ReactNode
   active?: boolean
   disabled?: boolean
+  /** Controles irmãos do alvo de navegação (ex.: menu de ações). */
+  actions?: ReactNode
+  /** Presente quando a linha desdobra filhos; o controle fica fora do botão principal. */
+  onToggle?: () => void
+  expanded?: boolean
+  /** Posição indicada durante drag-and-drop; bordas inserem, centro recebe dentro. */
+  dropPosition?: 'before' | 'inside' | 'after'
+  /** Props de drag-and-drop aplicadas à linha, sem acoplar a um driver. */
+  dragProps?: HTMLAttributes<HTMLDivElement>
+  /** Complemento do tooltip no rail recolhido. */
+  tooltipHint?: ReactNode
   className?: string
   onClick: () => void
 }
 
-/** Item de navegação que se adapta ao colapso da Sidebar em que está. */
-export function SidebarItem({ label, icon, badge, active = false, disabled = false, className, onClick }: SidebarItemProps): React.ReactElement {
+/** Linha única de navegação: o alvo principal e seus controles são irmãos, nunca botões aninhados. */
+export function SidebarItem({ label, icon, badge, active = false, disabled = false, actions, onToggle, expanded = false, dropPosition, dragProps, tooltipHint, className, onClick }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed()
-  const button = (
-    <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex items-center gap-2.5 rounded-md transition-colors', 'disabled:pointer-events-none disabled:opacity-40', collapsed ? 'mx-auto size-9 justify-center p-0' : 'w-full px-2.5 py-1.5 text-left text-sm', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60', className)}>
-      {icon !== undefined && <span className="flex shrink-0">{icon}</span>}
-      {!collapsed && <span className="min-w-0 flex-1 truncate">{label}</span>}
-      {!collapsed && badge !== undefined && <span className="shrink-0">{badge}</span>}
-    </button>
+  const hasActions = actions !== undefined && actions !== null
+  // O rótulo cortado esmaece em vez de terminar em reticências; a medição do transbordo
+  // mantém a máscara fora do rótulo que cabe inteiro na linha.
+  const { ref: labelRef, overflowing: labelCut } = useOverflowing<HTMLSpanElement>(label)
+  if (collapsed) {
+    const button = (
+      <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('mx-auto grid size-9 place-items-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-40', 'outline-none focus-visible:ring-2 focus-visible:ring-ring/50', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60', className)}>
+        {icon}
+      </button>
+    )
+    return <div {...dragProps}><Tooltip><TooltipTrigger asChild>{button}</TooltipTrigger><TooltipContent side="right">{label}{tooltipHint}</TooltipContent></Tooltip></div>
+  }
+
+  return (
+    <div data-slot="sidebar-item" className={cn('group/sidebar-item relative flex items-center rounded-md transition-colors', disabled ? 'text-muted-foreground/50 opacity-40' : 'hover:bg-muted/60', active && 'bg-muted', dropPosition === 'inside' && 'bg-primary/5 ring-2 ring-inset ring-primary/60', className)} {...dragProps}>
+      {(dropPosition === 'before' || dropPosition === 'after') && <span data-slot="sidebar-item-drop-indicator" className={cn('pointer-events-none absolute inset-x-1 z-20 h-0.5 rounded-full bg-primary before:absolute before:-left-1 before:top-1/2 before:size-2 before:-translate-y-1/2 before:rounded-full before:border-2 before:border-primary before:bg-background', dropPosition === 'before' ? '-top-px' : '-bottom-px')} />}
+      {icon !== undefined && (
+        <span data-slot="sidebar-item-leading" className="pointer-events-none absolute left-2.5 top-1/2 z-10 grid size-4 -translate-y-1/2 place-items-center">
+          <span className={cn('absolute inset-0 flex items-center justify-center transition-opacity', onToggle !== undefined && 'group-hover/sidebar-item:opacity-0 group-has-[[data-slot=sidebar-item-toggle]:focus-visible]/sidebar-item:opacity-0')}>{icon}</span>
+          {onToggle !== undefined && (
+            <button type="button" data-slot="sidebar-item-toggle" onClick={onToggle} aria-label={expanded ? `Fechar ${label}` : `Abrir ${label}`} aria-expanded={expanded} className="pointer-events-none absolute inset-0 grid place-items-center rounded-sm text-muted-foreground opacity-0 transition-[color,opacity] outline-none hover:text-foreground group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring/50">
+              <ChevronRight className={cn('size-3 transition-transform', expanded && 'rotate-90')} />
+            </button>
+          )}
+        </span>
+      )}
+      <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex min-w-0 flex-1 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm disabled:pointer-events-none', 'outline-none focus-visible:ring-2 focus-visible:ring-ring/50', disabled ? 'text-muted-foreground/50' : active ? 'font-medium text-foreground' : 'text-foreground/80')}>
+        {icon !== undefined && <span data-slot="sidebar-item-leading-space" aria-hidden className="size-4 shrink-0" />}
+        <span ref={labelRef} data-slot="sidebar-item-label" className={cn('min-w-0 flex-1 overflow-hidden whitespace-nowrap group-has-[[data-slot=dot]]/sidebar-item:mr-[1.1875rem]', labelCut && 'truncate-fade')}>{label}</span>
+        {badge !== undefined && <span data-slot="sidebar-item-badge" className={cn('shrink-0 transition-opacity has-[[data-slot=dot]]:absolute has-[[data-slot=dot]]:right-1 has-[[data-slot=dot]]:top-1/2 has-[[data-slot=dot]]:z-10 has-[[data-slot=dot]]:grid has-[[data-slot=dot]]:size-6 has-[[data-slot=dot]]:-translate-y-1/2 has-[[data-slot=dot]]:place-items-center', hasActions && 'group-hover/sidebar-item:has-[[data-slot=dot]]:opacity-0')}>{badge}</span>}
+      </button>
+      {hasActions && <div data-slot="sidebar-item-actions" className="pointer-events-none absolute right-1 top-1/2 z-10 flex -translate-y-1/2 items-center opacity-0 transition-opacity group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100 has-[:focus-visible]:pointer-events-auto has-[:focus-visible]:opacity-100 has-[[data-state=open]]:pointer-events-auto has-[[data-state=open]]:opacity-100 [&_button]:grid [&_button]:size-6 [&_button]:place-items-center [&_button]:p-0 [&_svg]:size-3.5">{actions}</div>}
+    </div>
   )
-  if (!collapsed) return button
-  return <Tooltip><TooltipTrigger asChild>{button}</TooltipTrigger><TooltipContent side="right">{label}</TooltipContent></Tooltip>
 }
 
 export interface SidebarNavGroup {
@@ -86,6 +124,11 @@ const subFilled = (subgroup: SidebarNavSubgroup): boolean => subgroup.items.leng
 const groupFilled = (group: SidebarNavGroup): boolean =>
   (group.items?.length ?? 0) > 0 || (group.subgroups?.some(subFilled) ?? false)
 
+/** Rótulo discreto de um grupo de navegação, compartilhado por listas e árvores. */
+export function SidebarGroupLabel({ className, children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div data-slot="sidebar-group-label" className={cn('px-2.5 pb-1 text-sm font-medium text-muted-foreground/70', className)}>{children}</div>
+}
+
 /** Navegação controlada para Sidebar. Header/footer continuam slots explícitos do pai. */
 export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação', className }: { groups: SidebarNavGroup[]; activeId?: string; onSelect: (id: string) => void; navLabel?: string; className?: string }): React.ReactElement {
   const collapsed = useSidebarCollapsed()
@@ -101,7 +144,7 @@ export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação
   const body = (
     <nav aria-label={navLabel} data-slot="sidebar-nav" className={cn('space-y-4 p-2', className)}>
       {groups.map((group, gi) => !groupFilled(group) ? null : <div key={gi} className="space-y-0.5">
-        {!collapsed && titled(group.label) && <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>}
+        {!collapsed && titled(group.label) && <SidebarGroupLabel>{group.label}</SidebarGroupLabel>}
         {group.items?.map((item) => renderItem(item))}
         {group.subgroups?.map((subgroup, si) => !subFilled(subgroup) ? null : <div key={si} className="space-y-0.5">
           {!collapsed && titled(subgroup.label) && <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[0.6875rem] font-medium text-muted-foreground/50">{subgroup.label}</div>}

package/src/ui/components/primitives/dot.tsx

@@ -0,0 +1,39 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../../lib/cn.ts'
+
+export const dotVariants = cva('inline-block size-1.5 shrink-0 rounded-full', {
+  variants: {
+    variant: {
+      default: 'bg-primary',
+      secondary: 'bg-muted-foreground/45',
+      destructive: 'bg-destructive',
+      outline: 'border border-border bg-transparent',
+      success: 'bg-emerald-500',
+      warning: 'bg-amber-500',
+      info: 'bg-blue-500',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+})
+
+export interface DotProps extends React.ComponentProps<'span'>, VariantProps<typeof dotVariants> {
+  /** Nome acessível quando a cor comunica estado; sem label, o ponto é decorativo. */
+  label?: string
+}
+
+/** Indicador compacto de estado; use Badge quando o texto precisar permanecer visível. */
+export function Dot({ className, variant, label, ...props }: DotProps): React.ReactElement {
+  return (
+    <span
+      data-slot="dot"
+      role={label === undefined ? undefined : 'img'}
+      aria-label={label}
+      aria-hidden={label === undefined ? true : undefined}
+      className={cn(dotVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}

package/src/ui/components/primitives/select.tsx

@@ -52,6 +52,7 @@ interface SelectBaseProps {
   /** Texto do campo vazio. */
   placeholder?: string
   disabled?: boolean
+  /** Classes da raiz do controle, incluindo campo, ícones e ações. */
   className?: string
   id?: string
   /** Ícone LEADING dentro do campo — identifica o filtro sem jogar o ícone ao lado. */
@@ -133,7 +134,10 @@ function NativeSelect({
 }: SelectNativeProps): React.ReactElement {
   const groups = byGroup(options)
   return (
-    <div className="group/select relative w-full min-w-0 has-[select:disabled]:opacity-50" data-slot="select-wrapper">
+    <div
+      className={cn('group/select relative w-full min-w-0 has-[select:disabled]:opacity-50', className)}
+      data-slot="select-wrapper"
+    >
       {icon ? (
         <span
           className="pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2 text-muted-foreground select-none [&_svg]:size-4"
@@ -157,7 +161,6 @@ function NativeSelect({
           'focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50',
           'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40',
           icon ? 'pl-9' : '',
-          className,
         )}
       >
         {placeholder !== undefined && (

package/src/ui/components/primitives/table.tsx

@@ -2,11 +2,21 @@ import * as React from "react"
 
 import { cn } from '../../lib/cn.ts'
 
-function Table({ className, ...props }: React.ComponentProps<"table">) {
+export interface TableProps extends React.ComponentProps<"table"> {
+  /** `framed` aplica a moldura canônica de datagrid no contêiner da tabela. */
+  variant?: 'plain' | 'framed'
+}
+
+function Table({ className, variant = 'plain', ...props }: TableProps) {
   return (
     <div
       data-slot="table-container"
-      className="relative w-full overflow-x-auto"
+      data-variant={variant}
+      className={cn(
+        "relative w-full overflow-x-auto",
+        variant === 'framed' &&
+          'rounded-lg border border-border [&_[data-slot=table-header]]:bg-muted/20',
+      )}
     >
       <table
         data-slot="table"

package/src/ui/components/primitives/truncate.tsx

@@ -1,10 +1,13 @@
 import * as React from 'react'
 import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip.tsx'
+import { useOverflowing } from '../../lib/overflow.ts'
 import { cn } from '../../lib/cn.ts'
 
 export interface TruncateProps extends React.ComponentProps<'span'> {
   /** Conteúdo do tooltip quando transborda. Default: os próprios children. */
   tooltip?: React.ReactNode
+  /** Sinaliza o corte esmaecendo o fim da linha, no lugar das reticências. */
+  fade?: boolean
 }
 
 /**
@@ -12,29 +15,15 @@ export interface TruncateProps extends React.ComponentProps<'span'> {
  * `scrollWidth > clientWidth`, re-medido em resize). Substitui a composição
  * `block truncate` + `title` sempre presente — title em texto que não corta é ruído.
  * Requer `<TooltipProvider>` na raiz do app (o esqueleto do `opus create` já monta).
+ * Com `fade`, a mesma medição decide quando esmaecer o fim da linha em vez de cortar
+ * em reticências — sem transbordo, nada é aplicado.
  */
-export function Truncate({ tooltip, children, className, ...props }: TruncateProps): React.ReactElement {
-  const ref = React.useRef<HTMLSpanElement>(null)
-  const [overflowing, setOverflowing] = React.useState(false)
-
-  const measure = React.useCallback(() => {
-    const el = ref.current
-    if (el === null) return
-    setOverflowing(el.scrollWidth > el.clientWidth)
-  }, [])
-
-  React.useLayoutEffect(() => {
-    measure()
-    const el = ref.current
-    if (el === null || typeof ResizeObserver === 'undefined') return
-    const ro = new ResizeObserver(measure)
-    ro.observe(el)
-    return () => ro.disconnect()
-    // children na dependência: texto novo re-mede (o RO só vê mudança de CAIXA).
-  }, [measure, children])
+export function Truncate({ tooltip, fade = false, children, className, ...props }: TruncateProps): React.ReactElement {
+  const { ref, overflowing } = useOverflowing<HTMLSpanElement>(children)
+  const cut = fade ? (overflowing ? 'truncate-fade' : 'overflow-hidden whitespace-nowrap') : 'truncate'
 
   const span = (
-    <span ref={ref} data-slot="truncate" className={cn('block truncate', className)} {...props}>
+    <span ref={ref} data-slot="truncate" className={cn('block', cut, className)} {...props}>
       {children}
     </span>
   )

package/src/ui/docs/content/dock.md

@@ -0,0 +1,69 @@
+# Dock
+
+Ferramentas ancoradas à superfície de trabalho. Um canvas ou um editor raramente comporta mais
+uma faixa de chrome no topo: a trilha da aplicação já ocupa esse papel, e um segundo cabeçalho
+empilha duas faixas com a mesma função. A Dock coloca as ações sobre a própria superfície,
+agrupadas e sempre alcançáveis.
+
+```tsx preview
+<div className="relative h-40 w-full rounded-lg border border-border bg-muted/20">
+  <Dock label="Ferramentas do fluxo">
+    <DockGroup>
+      <DockAction icon={<MousePointer2 />} label="Selecionar e mover" pressed onClick={() => {}} />
+    </DockGroup>
+    <DockGroup>
+      <DockAction icon={<Plus />} label="Adicionar etapa" onClick={() => {}} />
+      <DockAction icon={<GitBranch />} label="Adicionar condição" onClick={() => {}} />
+    </DockGroup>
+    <DockGroup>
+      <DockAction icon={<Sparkles />} label="Revisar com IA" onClick={() => {}} />
+    </DockGroup>
+  </Dock>
+  <SurfaceStatus>Salvo</SurfaceStatus>
+</div>
+```
+
+O contêiner precisa ser `relative` — a Dock se ancora nele, não na janela. `position` escolhe a
+aresta: `bottom` (centro), `bottom-left` e `bottom-right`. Uma superfície pode ter mais de uma
+barra quando os papéis são distintos, como ferramentas ao centro e controles de viewport à
+esquerda.
+
+## Grupos e divisórias
+
+A divisória entre grupos pertence ao componente: o consumidor declara `DockGroup` e a linha
+aparece entre grupos consecutivos, nunca antes do primeiro. Agrupe por intenção — modo, criação,
+IA, publicação — em vez de espalhar ícones numa fileira única.
+
+## Estado da superfície
+
+Estado não é ferramenta, e por isso não mora na barra: `SurfaceStatus` flutua num canto da mesma
+superfície — `top-right` por padrão — e recebe salvamento, versão publicada, execução percorrida.
+A região é `role="status"` com `aria-live="polite"`, então a mudança é anunciada sem roubar o foco.
+Separar os dois preserva a barra como toolbar navegável e dá ao estado um lugar estável, que não
+muda de posição conforme o número de ferramentas.
+
+Mensagem de sucesso é transitória por natureza — some depois de confirmar — enquanto falha
+permanece até o estado mudar. Essa decisão é da aplicação, que conhece o ciclo; o componente
+apenas reserva o lugar.
+
+`actions` recebe o que o recurso aberto permite fazer — em geral o mesmo menu que a linha dele
+tem na navegação. Assim a superfície deixa de ser o único lugar onde renomear ou excluir não
+alcançam o item que está na tela. Apenas o texto é região viva: anunciar o menu a cada mudança de
+estado seria ruído para quem usa leitor de tela.
+
+## Modo e execução
+
+`DockAction` sem `pressed` executa uma ação. Com `pressed`, comunica um modo ligado — o botão
+assume o preenchimento e expõe `aria-pressed`. Use `hint` quando o tooltip precisar dizer mais que
+o rótulo, que também é o nome acessível.
+
+## Teclado
+
+A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às pontas. Cada ação nomeia-se
+por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
+já monta.
+
+| Prop | Tipo | Default | O que faz |
+| --- | --- | --- | --- |
+| `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
+| `label` | `string` | | Nome acessível da barra. |

package/src/ui/docs/content/dot.md

@@ -0,0 +1,17 @@
+# Dot
+
+Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `variant`
+seleciona somente a intenção semântica. Quando a cor carrega significado, `label` fornece o nome
+acessível. Sem `label`, o ponto é decorativo.
+
+```tsx preview
+<div className="flex items-center gap-4">
+  <Dot variant="success" label="Ativo" />
+  <Dot variant="warning" label="Atenção" />
+  <Dot variant="destructive" label="Falhou" />
+  <Dot variant="info" label="Publicado" />
+  <Dot variant="secondary" aria-hidden />
+</div>
+```
+
+Use `Badge` quando o estado precisar permanecer legível sem depender do contexto ao redor.

package/src/ui/docs/content/select.md

@@ -340,3 +340,4 @@ render(
 | `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) pra toolbar densa. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
 | `id` | `string` | | Vai pro campo — pra parear com o `htmlFor` do Label. |
+| `className` | `string` | | Classes da raiz do controle, incluindo campo, ícones e ações, em todos os modos. |

package/src/ui/docs/content/sidebar.md

@@ -29,6 +29,27 @@ render(
 
 `collapsed` pertence à própria `Sidebar`; `SidebarItem`, `SidebarNav` e `ShellNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneContent` e `PaneFooter` são os slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar.
 
+`SidebarItem` também é a linha de árvores de navegação. `actions` e o controle formado por
+`onToggle`/`expanded` são irmãos do botão principal, portanto menus e chevrons não criam
+controles interativos aninhados. No modo recolhido, a linha conserva somente o destino com
+ícone e tooltip. No modo aberto, o chevron ocupa o lugar do ícone da pasta durante o hover da própria linha ou
+foco, e as ações ficam sobrepostas à extremidade direita: controles invisíveis não reduzem o
+espaço disponível para o rótulo. O foco comum no destino não mantém o chevron aberto;
+somente o foco visível no próprio controle o revela para navegação por teclado.
+As ações aparecem no hover da própria linha, no foco visível do próprio controle ou enquanto o menu está
+aberto; focar o destino da linha não revela as reticências.
+O rótulo que não cabe na linha desaparece num gradiente até a borda, em vez de terminar em
+reticências; a linha mede o próprio transbordo, então o rótulo que cabe inteiro fica intacto.
+O foco visível usa o mesmo anel do `Button` (`ring-2 ring-ring/50`), na linha aberta, no botão do
+rail recolhido e no chevron — sem ele a navegação por teclado cairia no anel padrão do navegador,
+que destoa do tema.
+Durante drag-and-drop, `dropPosition="before"` e `"after"` desenham uma linha sobreposta ao
+limite do item; `"inside"` realça a superfície da pasta. O indicador nunca reserva espaço.
+
+Árvores montadas por composição usam `SidebarGroupLabel` para os mesmos rótulos discretos
+que o `SidebarNav` desenha automaticamente. O heading permanece `text-sm`; hierarquia vem
+do peso médio e da cor atenuada, não de reduzir legibilidade.
+
 ```tsx
 <Sidebar collapsed={collapsed}>
   <PaneHeader><MySidebarHeader onToggle={() => setCollapsed(!collapsed)} /></PaneHeader>

package/src/ui/docs/content/table.md

@@ -38,32 +38,33 @@ A Table vem SEM borda externa — só as divisórias de linha (a última o Table
 
 ## Moldura (o datagrid da casa)
 
-A borda externa NÃO é do componente: é um wrapper `overflow-hidden rounded-lg border border-border` por fora — o estilo padrão de datagrid do back-office. O `overflow-hidden` recorta os cantos e contém o scroll horizontal; a última linha já vem sem divisória, então o quadro fecha limpo. O ActionList aplica a moldura sozinho na tabela derivada; em tabela montada à mão, é você quem embrulha.
+A variante `framed` aplica no próprio contêiner a borda externa, os cantos arredondados, o
+scroll horizontal contido e o fundo discreto do cabeçalho. A última linha já vem sem divisória,
+então o quadro fecha limpo. O ActionList continua sendo o pattern indicado para coleções
+pesquisáveis derivadas de actions `kind: 'list'`.
 
 ```tsx preview col
-<div className="w-full overflow-hidden rounded-lg border border-border">
-  <Table>
-    <TableHeader>
-      <TableRow>
-        <TableHead>Sessão</TableHead>
-        <TableHead>Agente</TableHead>
-        <TableHead className="text-right">Duração</TableHead>
-      </TableRow>
-    </TableHeader>
-    <TableBody>
-      <TableRow>
-        <TableCell className="font-medium">Importar pedidos da transportadora</TableCell>
-        <TableCell>developer</TableCell>
-        <TableCell className="text-right">42 min</TableCell>
-      </TableRow>
-      <TableRow>
-        <TableCell className="font-medium">Revisar contrato de rastreio</TableCell>
-        <TableCell>reviewer</TableCell>
-        <TableCell className="text-right">18 min</TableCell>
-      </TableRow>
-    </TableBody>
-  </Table>
-</div>
+<Table variant="framed">
+  <TableHeader>
+    <TableRow>
+      <TableHead>Sessão</TableHead>
+      <TableHead>Agente</TableHead>
+      <TableHead className="text-right">Duração</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">Importar pedidos da transportadora</TableCell>
+      <TableCell>developer</TableCell>
+      <TableCell className="text-right">42 min</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell className="font-medium">Revisar contrato de rastreio</TableCell>
+      <TableCell>reviewer</TableCell>
+      <TableCell className="text-right">18 min</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
 ```
 
 ## Com rodapé (TableFooter)

package/src/ui/docs/content/truncate.md

@@ -20,6 +20,32 @@ O mesmo componente, com espaço de sobra: sem tooltip, sem atributo, só o texto
 </div>
 ```
 
+## Corte por esmaecimento
+
+`fade` troca as reticências por um gradiente: o texto segue até a borda da caixa e desaparece
+ali. A medição é a mesma, então o esmaecimento e a dica aparecem juntos, só quando há texto
+escondido.
+
+```tsx preview
+<div className="w-48 rounded-md border p-2">
+  <Truncate fade>relatorio-consolidado-vendas-pos-vendas-2026-julho-final-v3.xlsx</Truncate>
+</div>
+```
+
+Uma composição que precisa do esmaecimento sem o tooltip aplica a utilitária `truncate-fade`,
+que cobre o último `1.5rem` da caixa, e decide quando ligá-la com o hook `useOverflowing` — a
+mesma medição que este componente usa. A máscara pressupõe corte real: em texto que cabe
+inteiro, ela esmaeceria o fim de uma palavra visível. É assim que o rótulo do `SidebarItem`
+funciona.
+
+```tsx
+const { ref, overflowing } = useOverflowing<HTMLSpanElement>(label)
+
+<span ref={ref} className={cn('overflow-hidden whitespace-nowrap', overflowing && 'truncate-fade')}>
+  {label}
+</span>
+```
+
 ## Conteúdo da dica
 
 `tooltip` sobrepõe o conteúdo mostrado no hover (default: os próprios children) — útil

package/src/ui/docs/registry.tsx

@@ -50,6 +50,8 @@ import confirmMd from './content/confirm.md?raw'
 import aspectRatioMd from './content/aspect-ratio.md?raw'
 import avatarMd from './content/avatar.md?raw'
 import badgeMd from './content/badge.md?raw'
+import dotMd from './content/dot.md?raw'
+import dockMd from './content/dock.md?raw'
 import breadcrumbMd from './content/breadcrumb.md?raw'
 import buttonMd from './content/button.md?raw'
 import buttonGroupMd from './content/button-group.md?raw'
@@ -357,6 +359,8 @@ export const UI_SECTIONS: DocSection[] = [
         pages: [
           { slug: 'avatar', title: 'Avatar', render: comp('Avatar', 'avatar', avatarMd) },
           { slug: 'badge', title: 'Badge', render: comp('Badge', 'badge', badgeMd) },
+          { slug: 'dot', title: 'Dot', render: comp('Dot', 'dot', dotMd) },
+          { slug: 'dock', title: 'Dock', render: comp('Dock', 'dock', dockMd) },
           { slug: 'carousel', title: 'Carousel', render: comp('Carousel', 'carousel', carouselMd) },
           { slug: 'copyable', title: 'Copyable', render: comp('Copyable', 'copyable', copyableMd) },
           { slug: 'item', title: 'Item', render: comp('Item', 'item', itemMd) },

package/src/ui/lib/overflow.ts

@@ -0,0 +1,34 @@
+import * as React from 'react'
+
+/**
+ * Diz se uma linha única de texto não cabe na própria caixa (`scrollWidth > clientWidth`).
+ * A medida é refeita quando a caixa muda de tamanho e quando o conteúdo passado em `content`
+ * muda — o ResizeObserver enxerga a CAIXA, não o texto que entra nela.
+ *
+ * É o que separa o corte real do corte suposto: quem consome liga o sinal de truncamento
+ * (reticências, esmaecimento, tooltip) só quando existe texto escondido.
+ */
+export function useOverflowing<T extends HTMLElement>(content?: React.ReactNode): {
+  ref: React.RefObject<T | null>
+  overflowing: boolean
+} {
+  const ref = React.useRef<T>(null)
+  const [overflowing, setOverflowing] = React.useState(false)
+
+  const measure = React.useCallback(() => {
+    const el = ref.current
+    if (el === null) return
+    setOverflowing(el.scrollWidth > el.clientWidth)
+  }, [])
+
+  React.useLayoutEffect(() => {
+    measure()
+    const el = ref.current
+    if (el === null || typeof ResizeObserver === 'undefined') return
+    const ro = new ResizeObserver(measure)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [measure, content])
+
+  return { ref, overflowing }
+}

package/src/ui/meta.ts

@@ -29,6 +29,18 @@ export const componentMeta = {
     whenToUse:
       'Rótulo curto de status/categoria. `variant` pra intenção (default/secondary/destructive/outline) ou tom de status (success/warning/info, fill tingido). Não-interativo — pra clique, use Button ou `asChild` num <a>.',
   },
+  'dot': {
+    name: 'dot',
+    ancestry: 'opus',
+    whenToUse:
+      'Sinal compacto de estado quando o contexto ou o nome acessível já explica o significado. `variant` segue a intenção semântica (default/secondary/destructive/outline/success/warning/info). Passe `label` quando a cor comunicar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.',
+  },
+  'dock': {
+    name: 'dock',
+    ancestry: 'opus',
+    whenToUse:
+      'Barra de ferramentas ancorada a uma superfície de trabalho — canvas, editor, preview —, quando um cabeçalho empilharia mais uma faixa de chrome sobre a trilha. Compõe Dock > DockGroup > DockAction; o estado da superfície (salvamento, versão) fica no SurfaceStatus, que flutua num canto e não pertence à barra. `position` escolhe a aresta; a divisória entre grupos é do componente. Requer TooltipProvider na raiz. Para ações de uma PÁGINA, use as `actions` do Page; para um conjunto de toggles exclusivos, ToggleGroup.',
+  },
   'button': {
     name: 'button',
     ancestry: 'shadcn',
@@ -137,7 +149,7 @@ export const componentMeta = {
     name: 'table',
     ancestry: 'shadcn',
     whenToUse:
-      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). Vem SEM borda externa — o datagrid da casa é a Table num wrapper "overflow-hidden rounded-lg border border-border". Pra listagem tabular — pro pattern de search use ActionList (que já monta a tabela emoldurada do spec).',
+      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Pra listagem tabular — pro pattern de search use ActionList.',
   },
   'tabs': {
     name: 'tabs',
@@ -167,7 +179,7 @@ export const componentMeta = {
     name: 'truncate',
     ancestry: 'opus',
     whenToUse:
-      'Texto truncado com tooltip SÓ quando transborda (medição do overflow, re-medida em resize) — substitui a composição `block truncate` + `title` sempre presente, que mostra dica até em texto que não corta. `tooltip` sobrepõe o conteúdo da dica (default: os children). Requer TooltipProvider na raiz. Pra célula de tabela, nome de arquivo, URL — qualquer linha única que pode estourar.',
+      'Texto truncado com tooltip SÓ quando transborda (medição do overflow, re-medida em resize) — substitui a composição `block truncate` + `title` sempre presente, que mostra dica até em texto que não corta. `tooltip` sobrepõe o conteúdo da dica (default: os children); `fade` troca as reticências por um esmaecimento até a borda, ligado pela mesma medição. Requer TooltipProvider na raiz. Pra célula de tabela, nome de arquivo, URL — qualquer linha única que pode estourar.',
   },
   'accordion': {
     name: 'accordion',

package/src/ui/react.tsx

@@ -135,6 +135,7 @@ export {
   TableCell,
   TableCaption,
 } from './components/primitives/table.tsx'
+export type { TableProps } from './components/primitives/table.tsx'
 
 // UM seletor: `native` (menu do SO), `searchable` (busca), `multiple` (chips) e
 // `variant="ghost"` (barra de composer) são PROPS, não componentes. Ver select.tsx.
@@ -172,6 +173,10 @@ export { ToggleGroup, ToggleGroupItem } from './components/primitives/toggle-gro
 export { Truncate } from './components/primitives/truncate.tsx'
 export type { TruncateProps } from './components/primitives/truncate.tsx'
 
+// A medição de transbordo por trás do Truncate, exposta para composições que precisam
+// do sinal de corte sem o tooltip — por exemplo, esmaecer um rótulo com `truncate-fade`.
+export { useOverflowing } from './lib/overflow.ts'
+
 // Patterns (renderizam actions a partir do spec)
 export { ActionForm, ActionFormField, useActionFormContext } from './components/patterns/form.tsx'
 export type { ActionFormProps, ActionFormFieldProps, ActionFormContextValue } from './components/patterns/form.tsx'
@@ -209,8 +214,12 @@ export type { PageProps } from './components/patterns/page.tsx'
 export { Split, Pane } from './components/patterns/split.tsx'
 export type { SplitProps, PaneProps, PaneSize, SplitLayout, SplitLayoutChange } from './components/patterns/split.tsx'
 
+// A barra de ferramentas que flutua sobre uma superfície de trabalho (canvas, editor, preview).
+export { Dock, DockGroup, DockAction, SurfaceStatus } from './components/patterns/dock.tsx'
+export type { DockProps, DockActionProps, SurfaceStatusProps } from './components/patterns/dock.tsx'
+
 // Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.
-export { PaneHeader, PaneContent, PaneFooter, Sidebar, SidebarItem, SidebarNav } from './components/patterns/sidebar.tsx'
+export { PaneHeader, PaneContent, PaneFooter, Sidebar, SidebarItem, SidebarGroupLabel, SidebarNav } from './components/patterns/sidebar.tsx'
 export type { SidebarProps, SidebarItemProps, SidebarNavGroup, SidebarNavSubgroup, SidebarNavItem } from './components/patterns/sidebar.tsx'
 
 // O menu como primitivo pivotável: recolhe quando composto dentro de Sidebar.
@@ -221,3 +230,5 @@ export type { ShellNavProps, ShellNavGroup, ShellNavItem, ShellNavHeadingProps }
 // reativa da URL + navigate — sem tabela de rotas. Ver src/ui/router.ts.
 export { navigate, usePathname, useSegments, useSearchParams } from './router.ts'
 export type { NavigateOptions } from './router.ts'
+export { Dot, dotVariants } from './components/primitives/dot.tsx'
+export type { DotProps } from './components/primitives/dot.tsx'

package/src/ui/theme.css

@@ -168,6 +168,18 @@
   }
 }
 
+/* Truncamento por esmaecimento: a linha continua em direção à borda e desaparece num
+ * gradiente, em vez de terminar em reticências. A máscara ocupa o último 1.5rem da caixa,
+ * então só deve ser aplicada quando o texto REALMENTE corta — em texto que cabe, ela
+ * esmaeceria o fim de uma palavra inteira. `Truncate fade` e o rótulo do `SidebarItem`
+ * medem o transbordo antes de ligá-la. */
+@utility truncate-fade {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: clip;
+  mask-image: linear-gradient(to right, #000 calc(100% - 1.5rem), transparent);
+}
+
 /* Scrollbar nativa da casa: todo scroller do documento compartilha o mesmo acabamento,
  * inclusive conteúdo renderizado por portal. Isso elimina a variação do macOS entre raiz,
  * elementos aninhados, mouse e trackpad sem trocar o mecanismo nativo nem adicionar trabalho