@softize/opus 16.0.0 → 16.1.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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.
 
+## 16.1.0 — 2026-09-11
+
+`PresentationDevtoolsProvider`, `usePresentationRegistration` e `PresentationDevtools` permitem
+que o shell reúna as Presentations ativas em um único launcher de desenvolvimento. Cada recurso
+registra sua definição e o estado vivo da invocação; a pessoa escolhe qual snapshot inspecionar no
+menu. O JSON continua mascarando dados sensíveis e só é materializado depois da escolha, evitando
+serialização desnecessária durante a renderização. O consumidor deve montar o provider, os registros
+e o launcher apenas em ambiente de desenvolvimento.
+
 ## 16.0.0 — 2026-09-11
 
 Opus 16 introduz `Presentation` como artefato público declarativo, disponível também pelo subpath

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "16.0.0",
+  "version": "16.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -1,4 +1,15 @@
-import { useState, type ReactElement, type ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
 import { Braces, X } from "lucide-react";
 import type {
   PresentationDiagnostic,
@@ -20,6 +31,13 @@ import {
   DialogHeader,
   DialogTitle,
 } from "../primitives/dialog.tsx";
+import {
+  Menu,
+  MenuContent,
+  MenuItem,
+  MenuLabel,
+  MenuTrigger,
+} from "../primitives/menu.tsx";
 import {
   Drawer,
   DrawerBody,
@@ -248,6 +266,211 @@ export interface PresentationInspectorProps {
   className?: string;
 }
 
+export interface PresentationRegistration
+  extends Pick<
+    PresentationInspectorProps,
+    "invocation" | "resolved" | "diagnostics"
+  > {
+  definition: PresentationDefinition;
+  /** Retira temporariamente a Presentation do inventário ativo sem desmontar o consumidor. */
+  enabled?: boolean;
+}
+
+interface ActivePresentationRegistration
+  extends Omit<PresentationRegistration, "enabled"> {
+  key: string;
+}
+
+interface PresentationRegistrationContextValue {
+  upsert: (key: string, registration: ActivePresentationRegistration) => void;
+  remove: (key: string) => void;
+}
+
+interface PresentationDevtoolsContextValue {
+  keys: readonly string[];
+  read: (key: string) => ActivePresentationRegistration | undefined;
+}
+
+const PresentationRegistrationContext =
+  createContext<PresentationRegistrationContextValue | null>(null);
+const PresentationDevtoolsContext =
+  createContext<PresentationDevtoolsContextValue | null>(null);
+
+export interface PresentationDevtoolsProviderProps {
+  children: ReactNode;
+}
+
+/** Mantém o inventário das Presentations montadas para uma única ferramenta do shell. */
+export function PresentationDevtoolsProvider({
+  children,
+}: PresentationDevtoolsProviderProps): ReactElement {
+  const registrations = useRef(
+    new Map<string, ActivePresentationRegistration>(),
+  );
+  const [keys, setKeys] = useState<readonly string[]>([]);
+  const upsert = useCallback(
+    (key: string, registration: ActivePresentationRegistration): void => {
+      const exists = registrations.current.has(key);
+      registrations.current.set(key, registration);
+      if (!exists) setKeys((current) => [...current, key]);
+    },
+    [],
+  );
+  const remove = useCallback((key: string): void => {
+    if (!registrations.current.delete(key)) return;
+    setKeys((current) => current.filter((candidate) => candidate !== key));
+  }, []);
+  const read = useCallback(
+    (key: string) => registrations.current.get(key),
+    [],
+  );
+  const registration = useMemo(() => ({ upsert, remove }), [upsert, remove]);
+  const devtools = useMemo(() => ({ keys, read }), [keys, read]);
+
+  return (
+    <PresentationRegistrationContext.Provider value={registration}>
+      <PresentationDevtoolsContext.Provider value={devtools}>
+        {children}
+      </PresentationDevtoolsContext.Provider>
+    </PresentationRegistrationContext.Provider>
+  );
+}
+
+/** Anuncia um snapshot ao provider mais próximo; fora dele, permanece inofensivo. */
+export function usePresentationRegistration({
+  definition,
+  invocation,
+  resolved,
+  diagnostics,
+  enabled = true,
+}: PresentationRegistration): void {
+  const context = useContext(PresentationRegistrationContext);
+  const upsert = context?.upsert;
+  const remove = context?.remove;
+  const key = useId();
+
+  // Sem dependências de propósito: os dados podem mudar mantendo a mesma Presentation.
+  // `upsert` substitui o snapshot em memória sem provocar um ciclo de render.
+  useEffect(() => {
+    if (upsert === undefined || !enabled) {
+      remove?.(key);
+      return;
+    }
+    upsert(key, { key, definition, invocation, resolved, diagnostics });
+  });
+
+  useEffect(
+    () => () => {
+      remove?.(key);
+    },
+    [key, remove],
+  );
+}
+
+interface SelectedPresentation {
+  key: string;
+  title: string;
+  json: string;
+}
+
+export interface PresentationDevtoolsProps {
+  /** Nome acessível e tooltip do launcher. */
+  triggerLabel?: string;
+  className?: string;
+}
+
+/** Launcher único do shell para escolher e inspecionar qualquer Presentation ativa. */
+export function PresentationDevtools({
+  triggerLabel = "Inspecionar Presentations ativas",
+  className,
+}: PresentationDevtoolsProps): ReactElement | null {
+  const registry = useContext(PresentationDevtoolsContext);
+  const [selected, setSelected] = useState<SelectedPresentation | null>(null);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const registrations =
+    registry?.keys.flatMap((key) => {
+      const registration = registry.read(key);
+      return registration === undefined ? [] : [registration];
+    }) ?? [];
+
+  useEffect(() => {
+    if (selected !== null && !registry?.keys.includes(selected.key)) {
+      setSelected(null);
+    }
+  }, [registry?.keys, selected]);
+
+  if (registrations.length === 0) return null;
+
+  function inspect(key: string): void {
+    const registration = registry?.read(key);
+    if (registration === undefined) return;
+    const json =
+      JSON.stringify(createPresentationInspectionSnapshot(registration), null, 2) ??
+      "null";
+    setSelected({ key, title: registration.definition.title, json });
+  }
+
+  return (
+    <>
+      <Menu open={menuOpen} onOpenChange={setMenuOpen}>
+        <MenuTrigger asChild>
+          <Button
+            size="icon"
+            variant="outline"
+            data-slot="presentation-devtools"
+            data-appearance="fab"
+            className={cn("rounded-full shadow-md", className)}
+            aria-label={triggerLabel}
+            title={triggerLabel}
+          >
+            <Braces aria-hidden />
+          </Button>
+        </MenuTrigger>
+        <MenuContent side="left" align="center" className="min-w-64">
+          <MenuLabel>Presentations ativas</MenuLabel>
+          {[...registrations].reverse().map((registration) => (
+            <MenuItem key={registration.key} onSelect={() => inspect(registration.key)}>
+              <span className="min-w-0 flex-1 truncate">
+                {registration.definition.title}
+              </span>
+              <span className="text-xs text-muted-foreground">
+                {registration.invocation === undefined ||
+                registration.invocation === null ||
+                typeof registration.invocation !== "object" ||
+                !("surface" in registration.invocation)
+                  ? "Presentation"
+                  : String(registration.invocation.surface)}
+              </span>
+            </MenuItem>
+          ))}
+        </MenuContent>
+      </Menu>
+      {selected === null ? null : (
+        <Dialog open onOpenChange={(open) => !open && setSelected(null)}>
+          <DialogContent className="sm:max-w-3xl" aria-describedby={undefined}>
+            <DialogHeader>
+              <DialogTitle>{selected.title}</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <pre className="max-h-[65vh] overflow-auto rounded-lg bg-muted p-4 text-xs leading-relaxed">
+                {selected.json}
+              </pre>
+            </DialogBody>
+            <DialogFooter>
+              <Copyable
+                value={selected.json}
+                className={buttonVariants({ variant: "outline" })}
+              >
+                Copiar JSON
+              </Copyable>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      )}
+    </>
+  );
+}
+
 /** Ferramenta de desenvolvimento para conferir e copiar o artefato consumido pelo renderer. */
 export function PresentationInspector({
   definition,

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

@@ -129,6 +129,13 @@ Use `floating` quando o inspetor precisar ficar disponível sem ocupar o cabeça
 aplica tamanho, forma, borda e elevação de FAB; `className` define a âncora na superfície consumidora.
 Reserve espaço para outros controles flutuantes do shell em vez de sobrepô-los.
 
+Quando várias Presentations puderem estar montadas ao mesmo tempo, envolva o shell com
+`PresentationDevtoolsProvider`, anuncie cada recurso com `usePresentationRegistration` e renderize
+um único `PresentationDevtools`. O launcher abre a lista ativa e só cria o snapshot mascarado depois
+que uma Presentation é escolhida. Monte os três exclusivamente em desenvolvimento: o inventário
+inclui definição, invocação, bindings resolvidos e diagnósticos que não pertencem à experiência de
+produção.
+
 ## Propriedades de Presentation
 
 | Propriedade     | Tipo                             | Padrão | Descrição                                                             |
@@ -156,3 +163,26 @@ Reserve espaço para outros controles flutuantes do shell em vez de sobrepô-los
 | `title`        | `string`                   | `JSON da Presentation`     | Título do dialog de inspeção.             |
 | `floating`     | `boolean`                  | `false`                    | Apresenta o gatilho com aparência de FAB. |
 | `className`    | `string`                   |                            | Classes adicionais do gatilho.            |
+
+## Propriedades de PresentationDevtoolsProvider
+
+| Propriedade | Tipo        | Descrição                                  |
+| ----------- | ----------- | ------------------------------------------ |
+| `children`  | `ReactNode` | Árvore que registra Presentations ativas.  |
+
+## Parâmetros de usePresentationRegistration
+
+| Propriedade   | Tipo                         | Padrão | Descrição                                              |
+| ------------- | ---------------------------- | ------ | ------------------------------------------------------ |
+| `definition`  | `PresentationDefinition`     |        | Definição estática da Presentation.                    |
+| `invocation`  | `unknown`                    |        | Estado vivo serializável, quando existir.              |
+| `resolved`    | `unknown`                    |        | Bindings resolvidos pelo renderer.                     |
+| `diagnostics` | `PresentationDiagnostic[]`   |        | Diagnósticos da definição ou execução.                 |
+| `enabled`     | `boolean`                    | `true` | Mantém ou retira o recurso do inventário ativo.        |
+
+## Propriedades de PresentationDevtools
+
+| Propriedade    | Tipo     | Padrão                           | Descrição                                      |
+| -------------- | -------- | -------------------------------- | ---------------------------------------------- |
+| `triggerLabel` | `string` | `Inspecionar Presentations ativas` | Nome acessível e tooltip do launcher.         |
+| `className`    | `string` |                                  | Classes adicionais; o shell define a posição. |

package/src/ui/meta.ts

@@ -406,7 +406,7 @@ export const componentMeta = {
     name: "presentation",
     ancestry: "opus",
     whenToUse:
-      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector reúne definição, invocação, bindings resolvidos e diagnósticos com dados sensíveis mascarados.",
+      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector inspeciona um recurso; PresentationDevtools reúne as Presentations ativas do shell em desenvolvimento. Ambos materializam snapshots mascarados somente sob demanda.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -420,11 +420,17 @@ export type { DataStateProps } from "./components/patterns/data-state.tsx";
 
 export {
   Presentation,
+  PresentationDevtools,
+  PresentationDevtoolsProvider,
   PresentationInspector,
+  usePresentationRegistration,
 } from "./components/patterns/presentation.tsx";
 export type {
   PresentationProps,
+  PresentationDevtoolsProps,
+  PresentationDevtoolsProviderProps,
   PresentationInspectorProps,
+  PresentationRegistration,
 } from "./components/patterns/presentation.tsx";
 
 // Esqueleto de página do back-office (main + container + header título/descrição/ação).