@softize/opus 8.6.6

package/src/testing/index.ts

@@ -0,0 +1,324 @@
+/**
+ * @softize/opus/testing — o harness de teste do protocolo (EXPERIMENTAL).
+ *
+ * A unidade natural de teste é a ACTION (o contrato): input → output/erro, bordas do
+ * schema, autorização fail-closed. Este módulo dá isso sem montar runtime nem mockar
+ * contexto à mão:
+ *
+ *   • `testContext()` — um ActionContext completo com fakes observáveis: `emit`
+ *     capturado em `emitted`, log capturado em `logged`, `can` configurável,
+ *     storage plugável (ex.: `memStorage()`).
+ *   • `runAction(action, input)` — o MESMO pipeline do `runtime.execute`, em unidade:
+ *     valida input → gate `public` → `authorize` (string DSL ou closure, semântica
+ *     idêntica, `loaded` incluso) → handler → valida output (pulado em `list`, como
+ *     no runtime). Falha estoura o MESMO `ActionError` tipado do runtime
+ *     (`validation.invalid_input`, `auth.unauthenticated`, `auth.forbidden`…).
+ *     Em `OPUS_MODE=design` roteia pro `mockHandler` como o runtime — contrato puro
+ *     (sem handler) é testável em design; fora dele, erro claro (`testing.no_handler`).
+ *   • `memStorage()` — StorageAdapter em memória pra testar handler que anexa
+ *     arquivo, com a mesma régua de key dos drivers reais.
+ *
+ * O que fica de fora (de propósito — é harness de UNIDADE): loaders reais (o teste
+ * passa `loaded` pronto), audit, reactions em cadeia e o servidor. `requires` é
+ * declarativo no protocolo (o runtime não o executa) — aqui idem; handler que chama
+ * `ctx.can` responde ao `can` das options. Pra fluxo completo, teste de integração
+ * com o runtime.
+ */
+
+import { evalExpression } from '../dsl/eval.ts'
+import { parseExpression } from '../dsl/parser.ts'
+import { normalizeKey } from '../storage/index.ts'
+import { error } from '../core/errors.ts'
+// Import direto do runtime (fora do index público): a régua handler×mockHandler
+// tem UMA fonte — o harness nunca pode divergir do execute().
+import { isOpusDesignMode } from '../core/runtime.ts'
+import type {
+  ActionContext,
+  ActionKind,
+  AiAdapter,
+  BoundAi,
+  AuthorizeSpec,
+  HandlerFn,
+  Logger,
+  Paginated,
+  Schema,
+  StorageAdapter,
+  StorageObject,
+  StoragePutOptions,
+  User,
+} from '../core/index.ts'
+
+// =============================================================================
+// testContext
+// =============================================================================
+
+export interface EmittedEvent {
+  event: string
+  data: unknown
+  meta?: Record<string, unknown>
+}
+
+export interface LoggedLine {
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  msg: string
+  meta?: object
+}
+
+export interface TestContextOptions {
+  user?: User | null
+  tenantId?: string | null
+  /** Resposta do `ctx.can` pra handlers que consultam permissão. Default: permite tudo. */
+  can?: ActionContext['can']
+  db?: unknown
+  storage?: StorageAdapter | null
+  ai?: AiAdapter | null
+  meta?: Record<string, unknown>
+}
+
+export interface TestContext {
+  ctx: ActionContext
+  /** Eventos emitidos pelo handler (`ctx.emit`), na ordem. */
+  emitted: EmittedEvent[]
+  /** Linhas logadas pelo handler (`ctx.log`), na ordem — o teste afirma o que importa. */
+  logged: LoggedLine[]
+}
+
+function captureLogger(sink: LoggedLine[]): Logger {
+  const log = (level: LoggedLine['level']) => (msg: string, meta?: object) => {
+    sink.push({ level, msg, ...(meta !== undefined ? { meta } : {}) })
+  }
+  const logger: Logger = {
+    trace: log('trace'),
+    debug: log('debug'),
+    info: log('info'),
+    warn: log('warn'),
+    error: log('error'),
+    fatal: log('fatal'),
+    child: () => logger,
+  }
+  return logger
+}
+
+/** Liga o adapter cru num `BoundAi` pro `ctx.ai` do teste. Sem runtime/registry, o `run`
+ *  sai com tools vazias — testar handler agêntico usa `createRuntime` (não este harness). */
+function toBoundAi(a: AiAdapter): BoundAi {
+  return {
+    complete: (p, o) => a.complete(p, o),
+    extract: (p, s, o) => a.extract(p, s, o),
+    run: (input, opts) =>
+      a.run
+        ? a.run(input, { ...opts, tools: [], execute: () => ({}) })
+        : Promise.reject(new Error('driver de IA sem run (loop agêntico).')),
+    runStream: (input, opts) => {
+      if (a.runStream === undefined) throw new Error('driver de IA sem runStream (loop em streaming).')
+      return a.runStream(input, { ...opts, tools: [], execute: () => ({}) })
+    },
+  }
+}
+
+/** ActionContext de teste: fakes observáveis, nada de rede/banco/runtime. */
+export function testContext(options: TestContextOptions = {}): TestContext {
+  const emitted: EmittedEvent[] = []
+  const logged: LoggedLine[] = []
+  const ctx: ActionContext = {
+    user: options.user ?? null,
+    tenantId: options.tenantId ?? null,
+    can: options.can ?? (() => true),
+    db: options.db,
+    log: captureLogger(logged),
+    emit: (event, data, meta) => {
+      emitted.push({ event, data, ...(meta !== undefined ? { meta } : {}) })
+      return Promise.resolve()
+    },
+    storage: options.storage ?? null,
+    ai: options.ai ? toBoundAi(options.ai) : null,
+    provenance: { kind: 'system', source: 'test' },
+    meta: options.meta ?? {},
+  }
+  return { ctx, emitted, logged }
+}
+
+// =============================================================================
+// memStorage
+// =============================================================================
+
+/**
+ * StorageAdapter em memória, com a régua de key dos drivers reais
+ * (`normalizeKey`). Métodos async como nos drivers: key inválida REJEITA,
+ * não estoura síncrono.
+ */
+export function memStorage(): StorageAdapter & { keys(): string[] } {
+  const objects = new Map<string, StorageObject>()
+  return {
+    name: 'mem',
+    kind: 'storage',
+    async put(key: string, data: Uint8Array, opts?: StoragePutOptions): Promise<void> {
+      objects.set(normalizeKey(key), {
+        data,
+        ...(opts?.contentType !== undefined ? { contentType: opts.contentType } : {}),
+      })
+    },
+    async get(key: string): Promise<StorageObject | null> {
+      return objects.get(normalizeKey(key)) ?? null
+    },
+    async delete(key: string): Promise<void> {
+      objects.delete(normalizeKey(key))
+    },
+    async url(key: string): Promise<string> {
+      return `mem://${normalizeKey(key)}`
+    },
+    keys(): string[] {
+      return [...objects.keys()].sort()
+    },
+  }
+}
+
+// =============================================================================
+// fake (fixtures do schema)
+// =============================================================================
+
+export { fake, fakeMany, type FakeOptions } from './fake.ts'
+
+// =============================================================================
+// runAction
+// =============================================================================
+
+/**
+ * O subset estrutural de action que o harness lê. Qualquer action real (defineAction
+ * ou objeto literal) satisfaz por dever campos a mais — `loads`, `requires` etc. são
+ * ignorados aqui (loaders não rodam em unidade; passe `loaded` nas options).
+ *
+ * Como no runtime, `authorize` e `handler` recebem o input PARSEADO (`ParsedIn`,
+ * o output do schema de input — defaults aplicados); `In` é o lado do fio.
+ */
+export interface TestableAction<In, Out, ParsedIn = In> {
+  name: string
+  kind?: ActionKind
+  public?: boolean
+  authorize?: AuthorizeSpec<ParsedIn>
+  input: Schema<In, ParsedIn>
+  output: Schema<Out> | Schema<unknown, Out>
+  /** Opcional: contrato puro (sem handler) executa via `mockHandler` em modo design. */
+  handler?: HandlerFn<ParsedIn, Out>
+  /** Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime. */
+  mockHandler?: HandlerFn<ParsedIn, Out>
+}
+
+/** Variante list: o schema descreve o ITEM, o handler devolve `Paginated<Item>`. */
+export interface TestableListAction<In, Item, ParsedIn = In> {
+  name: string
+  kind: 'list'
+  public?: boolean
+  authorize?: AuthorizeSpec<ParsedIn>
+  input: Schema<In, ParsedIn>
+  output: Schema<Item> | Schema<unknown, Item>
+  handler?: (
+    ctx: ActionContext,
+    input: ParsedIn,
+    loaded?: Record<string, unknown>,
+  ) => Paginated<Item> | Promise<Paginated<Item>>
+  mockHandler?: (
+    ctx: ActionContext,
+    input: ParsedIn,
+    loaded?: Record<string, unknown>,
+  ) => Paginated<Item> | Promise<Paginated<Item>>
+}
+
+export interface RunActionOptions extends TestContextOptions {
+  /** Substitui os loaders (não rodam em unidade): vai pro handler e pro evalCtx do authorize. */
+  loaded?: Record<string, unknown>
+}
+
+export interface RunActionResult<Out> extends TestContext {
+  output: Out
+}
+
+/** Espelho do `runtime.validate`: mesmo discriminador e mesmo `ActionError`. */
+async function validate<T>(
+  schema: Schema<T> | Schema<unknown, T>,
+  value: unknown,
+  kind: 'input' | 'output',
+): Promise<T> {
+  const result = await Promise.resolve(schema['~standard'].validate(value))
+  if ('value' in result) return result.value as T
+  throw error({
+    code: kind === 'input' ? 'validation.invalid_input' : 'validation.invalid_output',
+    category: kind === 'input' ? 'validation' : 'internal',
+    message: kind === 'input' ? 'Input validation failed' : 'Output validation failed (dev)',
+    issues: result.issues.map((iss) => ({
+      path: (iss.path ?? []).join('.'),
+      code: 'invalid',
+      message: iss.message,
+    })),
+  })
+}
+
+/**
+ * Roda uma action em UNIDADE com o pipeline do `runtime.execute`: valida input →
+ * gate `public` → authorize → handler → valida output. Sucesso devolve o output
+ * validado + o contexto observável (`emitted`, `logged`); falha estoura o mesmo
+ * `ActionError` do runtime — afirme com `expect(...).rejects`.
+ *
+ * A escolha do executável segue a régua do `execute()`: em `OPUS_MODE=design`,
+ * `mockHandler` presente vence; senão, `handler` real. Contrato puro (sem
+ * handler) só roda em design — fora dele, `testing.no_handler`.
+ */
+export async function runAction<In, Item, ParsedIn = In>(
+  action: TestableListAction<In, Item, ParsedIn>,
+  input: unknown,
+  options?: RunActionOptions,
+): Promise<RunActionResult<Paginated<Item>>>
+export async function runAction<In, Out, ParsedIn = In>(
+  action: TestableAction<In, Out, ParsedIn>,
+  input: unknown,
+  options?: RunActionOptions,
+): Promise<RunActionResult<Out>>
+export async function runAction<In, Out, ParsedIn = In>(
+  action: TestableAction<In, Out, ParsedIn>,
+  input: unknown,
+  options: RunActionOptions = {},
+): Promise<RunActionResult<Out>> {
+  const t = testContext(options)
+  const { ctx } = t
+  const loaded = options.loaded
+
+  const parsed = await validate<ParsedIn>(action.input, input, 'input')
+
+  if (action.public !== true && ctx.user === null) {
+    throw error({
+      code: 'auth.unauthenticated',
+      category: 'authentication',
+      message: 'Authentication required',
+    })
+  }
+
+  if (action.authorize !== undefined) {
+    const spec = action.authorize
+    const decision =
+      typeof spec === 'string'
+        ? Boolean(evalExpression(parseExpression(spec), { user: ctx.user, input: parsed, ctx, ...(loaded ?? {}) }))
+        : await spec(ctx, parsed, loaded)
+    if (decision === false) {
+      throw error({ code: 'auth.forbidden', category: 'authorization', message: 'Forbidden' })
+    }
+    if (decision !== true) throw decision
+  }
+
+  const handlerToRun =
+    isOpusDesignMode() && action.mockHandler !== undefined
+      ? action.mockHandler
+      : action.handler
+  if (handlerToRun === undefined) {
+    throw error({
+      code: 'testing.no_handler',
+      category: 'internal',
+      message: `Action "${action.name}" não tem handler executável — contrato puro roda em modo design (OPUS_MODE=design) com mockHandler; fora dele, teste o ActionDef do bindAction`,
+    })
+  }
+  const raw = await handlerToRun(ctx, parsed, loaded)
+
+  // Mesmo skip do runtime: list devolve Paginated<Item>, o schema descreve Item.
+  const output = action.kind === 'list' ? (raw as Out) : await validate<Out>(action.output, raw, 'output')
+
+  return { output, ...t }
+}

package/src/ui/components/patterns/action-form-card.tsx

@@ -0,0 +1,48 @@
+/**
+ * <ActionFormCard /> — o ActionForm dentro de um Card do Opus (header / conteúdo / rodapé),
+ * pra estruturar uma seção da página como painel. Segue o padrão do CARD (não a chrome de
+ * modal): sem divisor nem faixa, com o respiro do Card. Pra form em overlay, use o
+ * ActionFormDialog; pra form cru (sem chrome), o ActionForm direto.
+ */
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '../primitives/card.tsx'
+import { ActionForm, type ActionFormProps } from './form.tsx'
+
+export interface ActionFormCardProps<TInput extends Record<string, unknown>, TData>
+  extends Omit<ActionFormProps<TInput, TData>, 'body' | 'footer'> {
+  /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
+  title?: string
+  /** Subtítulo opcional, abaixo do título. */
+  description?: string
+  /** Classes do Card (a superfície). `className` vai pro <form>. */
+  cardClassName?: string
+}
+
+export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
+  title,
+  description,
+  cardClassName,
+  ...rest
+}: ActionFormCardProps<TInput, TData>) {
+  return (
+    <Card className={cardClassName}>
+      {(title !== undefined || description !== undefined) && (
+        <CardHeader>
+          {title !== undefined && <CardTitle>{title}</CardTitle>}
+          {description !== undefined && <CardDescription>{description}</CardDescription>}
+        </CardHeader>
+      )}
+      <ActionForm
+        {...rest}
+        body={(fields) => <CardContent>{fields}</CardContent>}
+        footer={(actions) => <CardFooter className="justify-end">{actions}</CardFooter>}
+      />
+    </Card>
+  )
+}

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -0,0 +1,93 @@
+/**
+ * <ActionListDialog action input /> — uma ListAction em modal (o modo modal da lista).
+ *
+ * CASCA sobre o <ActionList /> em modo composição: o dialog põe o chrome (título,
+ * descrição, a linha nota + ação de criar) e o ActionList faz o resto — fetch
+ * query-backed com refetch por `invalidates`, toolbar declarativa (busca/filtros/
+ * período, se o contrato declarar), estados de carga e o rodapé com total/pager.
+ *
+ * Escape hatches pro que o contrato não sabe (repassados ao ActionList):
+ * - `loading` AGREGA carga extra (a query irmã que os children precisam, ex.: papéis).
+ * - `empty` sobrepõe o vazio derivado (ex.: form inline de criar aberto ⇒ children).
+ */
+
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '../primitives/dialog.tsx'
+import { ActionList } from './list.tsx'
+import type { ListAction } from '../../../core/index.ts'
+
+export interface ActionListDialogProps<TItem, TInput extends Record<string, unknown> = Record<string, unknown>> {
+  /** A ListAction do Opus (estrutural: name + kind — o mesmo contrato da família). */
+  action: { name: string; kind: 'list' }
+  /** Input da action (o escopo base; ex.: { workspaceId }). Mudou, re-busca. */
+  input?: TInput
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: string
+  description?: string
+  /** Nota à esquerda da linha de ações (contexto curto). O total já mora no rodapé. */
+  note?: ReactNode
+  /** Ação à direita da linha — em geral o botão de criar. */
+  actions?: ReactNode
+  emptyText?: string
+  /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto. */
+  empty?: (items: TItem[]) => boolean
+  /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
+  loading?: boolean
+  /** Classes do DialogContent (largura). Default: sm:max-w-3xl (lista pede espaço). */
+  className?: string
+  /** O layout dos itens (cards/linhas) — os estados já saíram daqui. */
+  children: (items: TItem[], refetch: () => Promise<void>) => ReactNode
+}
+
+export function ActionListDialog<TItem, TInput extends Record<string, unknown> = Record<string, unknown>>({
+  action,
+  input,
+  open,
+  onOpenChange,
+  title,
+  description,
+  note,
+  actions,
+  emptyText,
+  empty,
+  loading,
+  className,
+  children,
+}: ActionListDialogProps<TItem, TInput>): React.ReactElement {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className={cn('sm:max-w-3xl', className)}>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {description !== undefined && <DialogDescription>{description}</DialogDescription>}
+        </DialogHeader>
+        <DialogBody>
+          {(note !== undefined || actions !== undefined) && (
+            <div data-slot="action-list-dialog-toolbar" className="mb-2 flex min-h-8 items-center justify-between gap-4">
+              <div className="min-w-0 text-xs text-muted-foreground/70">{note}</div>
+              {actions}
+            </div>
+          )}
+          <ActionList<TInput, TItem>
+            action={action as unknown as ListAction<TInput, TItem>}
+            input={(input ?? {}) as TInput}
+            {...(emptyText !== undefined ? { emptyMessage: emptyText } : {})}
+            {...(empty !== undefined ? { empty } : {})}
+            {...(loading !== undefined ? { loading } : {})}
+          >
+            {children}
+          </ActionList>
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  )
+}

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

@@ -0,0 +1,227 @@
+/**
+ * <AppShell /> — o chrome da aplicação: sidebar de navegação + conteúdo, com rail
+ * opcional à direita (chat de agente, inspetor).
+ *
+ * Padroniza o esqueleto que os apps copiavam à mão (mesmas classes, várias vezes):
+ * raiz `flex h-screen`, aside `w-64` com header/nav/rodapé (o nav rola; o rodapé
+ * ancora), e o conteúdo. Com `rail`, conteúdo e rail viram painéis redimensionáveis
+ * (Resizable). Presentacional de propósito: o QUE vai em cada slot (PaneHeader do
+ * app, ChatRail, preview…) é do consumidor — o shell é o quadro, não o conteúdo.
+ *
+ * RECOLHER (`collapsible`): o shell controla a LARGURA e publica o estado; quem decide
+ * o que some é o conteúdo, porque o `sidebarNav` é do consumidor. O aside expõe
+ * `data-collapsed` e o grupo `sidebar`, então rótulo some por CSS, sem estado no
+ * consumidor: `className="group-data-[collapsed=true]/sidebar:hidden"`. Quem precisa do
+ * estado em JS usa `useAppShell()`; o botão é o `<AppShellTrigger />`, posicionado pelo
+ * consumidor (numa `<AppShellBar>`, por exemplo) — o shell não escolhe por ele.
+ */
+
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from 'react'
+import { PanelLeft } from 'lucide-react'
+import { cn } from '../../lib/cn.ts'
+import { Button } from '../primitives/button.tsx'
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
+
+interface AppShellContextValue {
+  /** O shell permite recolher? Sem isso o trigger não se renderiza. */
+  collapsible: boolean
+  collapsed: boolean
+  setCollapsed: (collapsed: boolean) => void
+  toggle: () => void
+}
+
+const AppShellContext = createContext<AppShellContextValue | null>(null)
+
+/** Estado do shell (recolhido/expandido) pra quem precisa dele em JS. Em CSS, prefira o
+ *  seletor de grupo (`group-data-[collapsed=true]/sidebar:…`) — não precisa de hook. */
+export function useAppShell(): AppShellContextValue {
+  const ctx = useContext(AppShellContext)
+  if (ctx === null) throw new Error('useAppShell precisa de um <AppShell> acima na árvore.')
+  return ctx
+}
+
+interface SidebarSlotValue {
+  collapsed: boolean
+}
+/** Contexto presente SÓ dentro dos slots da sidebar (header/nav/rodapé), AUSENTE no
+ *  conteúdo. `useAppShell` não distingue os dois (o colapso vale a árvore toda); este sim.
+ *  É como um nav PIVOTÁVEL (o `<ShellNav>`) sabe se está NA sidebar — e se ela está
+ *  recolhida — sem o app passar isso em duas mãos (fecha a nota n=2 do gb-nav-rail). */
+const SidebarSlotContext = createContext<SidebarSlotValue | null>(null)
+/** Null quando FORA da sidebar (ex.: um `<ShellNav>` dentro do conteúdo, num SectionShell). */
+export function useSidebarSlot(): SidebarSlotValue | null {
+  return useContext(SidebarSlotContext)
+}
+
+export interface AppShellProps {
+  /** Topo da sidebar (marca, seletor de contexto/usuário). */
+  sidebarHeader?: ReactNode
+  /** Miolo da sidebar — a navegação; rola sozinho quando passa da altura. */
+  sidebarNav: ReactNode
+  /** Rodapé da sidebar, ancorado embaixo (status, ações globais). */
+  sidebarFooter?: ReactNode
+  /** Rail opcional à direita (chat de agente, inspetor). Sem ele, o conteúdo ocupa tudo. */
+  rail?: ReactNode
+  /** Tamanho inicial (%) do painel de conteúdo quando há rail. Default: 62. */
+  mainDefaultSize?: number
+  /** Tamanho mínimo (%) do painel de conteúdo. Default: 35. */
+  mainMinSize?: number
+  /** Tamanho mínimo (%) do rail. Default: 25. */
+  railMinSize?: number
+  /** Classes da raiz. Default: altura da tela (`h-screen`); em embeds, passe ex. `h-96`. */
+  className?: string
+  /** Classes do aside. Default: `w-64 shrink-0 flex-col p-2`. Largura passada aqui manda no
+   *  estado EXPANDIDO; no recolhido quem vence é `sidebarCollapsedClassName` (recolher é
+   *  estado, não estilo — senão o aside ficaria meio-recolhido). */
+  sidebarClassName?: string
+  /** Permite recolher a sidebar — OPT-IN: sem isso o shell é o de sempre. */
+  collapsible?: boolean
+  /** Recolhida? Passe junto com `onCollapsedChange` pra controlar de fora (ex.: persistir
+   *  a preferência); omita e o shell guarda o estado sozinho. */
+  collapsed?: boolean
+  /** Avisa que o estado mudou (obrigatório na forma controlada). */
+  onCollapsedChange?: (collapsed: boolean) => void
+  /** Largura do aside recolhido — só o suficiente pros ícones. Default: `w-14`. */
+  sidebarCollapsedClassName?: string
+  /** Chrome RENTE ao browser (sem inset): sidebar sem padding e conteúdo full-bleed
+   *  apartado pelo filete (`border-l`) — o shell NÃO pinta fundo (o canvas vem do
+   *  body); superfície branca é decisão do conteúdo (pinte `bg-background` no seu
+   *  contêiner). Combine com `<AppShellBar>` na sidebar e no topo do conteúdo pra
+   *  linha do header atravessar a tela inteira. Default: false (chrome clássico). */
+  flush?: boolean
+  children: ReactNode
+}
+
+export function AppShell({
+  sidebarHeader,
+  sidebarNav,
+  sidebarFooter,
+  rail,
+  mainDefaultSize = 62,
+  mainMinSize = 35,
+  railMinSize = 25,
+  className,
+  sidebarClassName,
+  collapsible = false,
+  collapsed: collapsedProp,
+  onCollapsedChange,
+  sidebarCollapsedClassName = 'w-14',
+  flush = false,
+  children,
+}: AppShellProps): React.ReactElement {
+  // Controlado quando `collapsed` vem de fora; senão o shell guarda sozinho.
+  const [internal, setInternal] = useState(false)
+  const isControlled = collapsedProp !== undefined
+  const collapsed = collapsible && (isControlled ? collapsedProp : internal)
+
+  const setCollapsed = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternal(next)
+      onCollapsedChange?.(next)
+    },
+    [isControlled, onCollapsedChange],
+  )
+  const ctx = useMemo<AppShellContextValue>(
+    () => ({ collapsible, collapsed, setCollapsed, toggle: () => setCollapsed(!collapsed) }),
+    [collapsible, collapsed, setCollapsed],
+  )
+  const sidebarSlot = useMemo<SidebarSlotValue>(() => ({ collapsed: collapsible && collapsed }), [collapsible, collapsed])
+
+  const main = (
+    <div
+      data-slot="app-shell-main"
+      className={cn('flex h-full min-w-0 flex-1 flex-col', flush && 'border-l border-border')}
+    >
+      {children}
+    </div>
+  )
+  return (
+    <AppShellContext.Provider value={ctx}>
+      <div data-slot="app-shell" className={cn('flex h-screen', className)}>
+        <aside
+          data-slot="app-shell-sidebar"
+          // `data-collapsed` + grupo nomeado: o conteúdo do consumidor reage por CSS.
+          data-collapsed={collapsible ? String(collapsed) : undefined}
+          className={cn(
+            'group/sidebar flex shrink-0 flex-col',
+            collapsible && 'transition-[width] duration-200 ease-out',
+            'w-64',
+            flush ? 'p-0' : 'p-2',
+            sidebarClassName,
+            // DEPOIS do `sidebarClassName` de propósito: recolhido é ESTADO, não estilo
+            // default. Quem passa a própria largura (`sidebarClassName="w-72"`) manda no
+            // expandido, mas não pode impedir o aside de estreitar — senão o shell ficaria
+            // meio-recolhido (rótulo some, largura fica) sem erro nenhum.
+            collapsed && sidebarCollapsedClassName,
+          )}
+        >
+          <SidebarSlotContext.Provider value={sidebarSlot}>
+            {sidebarHeader}
+            <div data-slot="app-shell-nav" className="min-h-0 flex-1 overflow-y-auto">
+              {sidebarNav}
+            </div>
+            {sidebarFooter}
+          </SidebarSlotContext.Provider>
+        </aside>
+        {rail === undefined ? (
+          main
+        ) : (
+          <ResizablePanelGroup orientation="horizontal" className="min-w-0 flex-1">
+            <ResizablePanel defaultSize={mainDefaultSize} minSize={mainMinSize}>
+              {main}
+            </ResizablePanel>
+            <ResizableHandle withHandle />
+            <ResizablePanel defaultSize={100 - mainDefaultSize} minSize={railMinSize}>
+              <div data-slot="app-shell-rail" className="h-full">
+                {rail}
+              </div>
+            </ResizablePanel>
+          </ResizablePanelGroup>
+        )}
+      </div>
+    </AppShellContext.Provider>
+  )
+}
+
+/**
+ * <AppShellTrigger /> — recolhe/expande a sidebar. Some sozinho quando o shell não é
+ * `collapsible`, então dá pra deixar fixo no layout sem condicional no consumidor.
+ */
+export function AppShellTrigger({ className }: { className?: string }): React.ReactElement | null {
+  const { collapsible, collapsed, toggle } = useAppShell()
+  if (!collapsible) return null
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={toggle}
+      aria-label={collapsed ? 'Expandir a barra lateral' : 'Recolher a barra lateral'}
+      aria-expanded={!collapsed}
+      className={className}
+    >
+      <PanelLeft className={cn('transition-transform duration-200', collapsed && 'rotate-180')} />
+    </Button>
+  )
+}
+
+/**
+ * <AppShellBar /> — a linha de header do chrome `flush`: faixa h-12 com `border-b`.
+ * Use UMA na sidebar (a marca) e OUTRA no topo do conteúdo (breadcrumb/ações): as
+ * alturas casam e as bordas emendam — uma régua contínua atravessando a tela.
+ */
+export function AppShellBar({
+  className,
+  children,
+}: {
+  className?: string
+  children?: ReactNode
+}): React.ReactElement {
+  return (
+    <div
+      data-slot="app-shell-bar"
+      className={cn('flex h-12 shrink-0 items-center gap-2.5 border-b border-border px-4', className)}
+    >
+      {children}
+    </div>
+  )
+}