@softize/opus 18.1.1 → 18.2.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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.
 
+## 18.2.0 — 2026-09-16
+
+`Presentation` passa a aceitar um body serializável baseado em componente. O contrato continua
+definindo rota, superfície, navegação e ações, enquanto a aplicação fornece o conteúdo React em
+tempo de execução. Assim, uma página pode adotar a casca dirigida por spec sem precisar migrar de
+uma vez toda a implementação interna para actions declarativas.
+
+Recursos podem declarar um gatilho de assistência contextual em `assistant`. A aplicação fornece o
+painel e os dados vivos do recurso por `assistant.render`; identidade, autorização e demais dados
+não entram no manifest. O novo `SurfaceAssistant`, também disponível pela API pública, divide
+somente o body de Page, Dialog ou Drawer. Cabeçalho e rodapé permanecem em toda a largura, e o
+gatilho sai do cabeçalho enquanto o painel aberto assume a identidade visual da assistência.
+
+O split contextual usa um único separador redimensionável, sem sobrepor uma segunda borda entre o
+conteúdo e o painel. O conteúdo principal permanece montado durante a conversa e volta a ocupar
+toda a largura quando ela é fechada.
+
 ## 18.1.1 — 2026-09-16
 
 **Correção de segurança.** Quem executa tools de IA só roda o que `aiTools()` anunciou. Até aqui, o

package/package.json

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

package/src/core/presentation.ts

@@ -90,7 +90,7 @@ const presentationFieldSchema = z
   })
   .strict();
 
-const presentationBodySchema = z
+const presentationActionBodySchema = z
   .object({
     action: z.string().min(1),
     input: z.record(presentationBindingSchema).default({}),
@@ -108,6 +108,27 @@ const presentationBodySchema = z
   })
   .strict();
 
+const presentationComponentBodySchema = z
+  .object({
+    /** Boundary estático do conteúdo React fornecido pelo consumidor. */
+    component: identifierSchema,
+    /** Define se o heading principal nasce na casca ou no conteúdo React. */
+    heading: z.enum(["shell", "content"]).default("shell"),
+  })
+  .strict();
+
+const presentationBodySchema = z.union([
+  presentationActionBodySchema,
+  presentationComponentBodySchema,
+]);
+
+const presentationAssistantSchema = z
+  .object({
+    /** Nome acessível do botão que abre a assistência contextual. */
+    triggerLabel: z.string().min(1),
+  })
+  .strict();
+
 const presentationRouteRecordSchema = z
   .object({
     presentation: identifierSchema,
@@ -136,6 +157,7 @@ export const presentationSchema = z
     title: z.string().min(1),
     route: presentationRouteSchema.optional(),
     body: presentationBodySchema,
+    assistant: presentationAssistantSchema.optional(),
     actions: z.array(presentationCommandSchema).default([]),
   })
   .strict();
@@ -143,6 +165,12 @@ export const presentationSchema = z
 export type PresentationDefinition = z.infer<typeof presentationSchema>;
 export type PresentationDefinitionInput = z.input<typeof presentationSchema>;
 export type PresentationCommand = PresentationDefinition["actions"][number];
+export type PresentationActionBody = z.infer<
+  typeof presentationActionBodySchema
+>;
+export type PresentationComponentBody = z.infer<
+  typeof presentationComponentBodySchema
+>;
 type DefaultedProperty<
   Input,
   Key extends PropertyKey,
@@ -174,27 +202,48 @@ type DefinedPresentationEffects<
         }
       : PresentationCommand["onSuccess"]
   : PresentationCommand["onSuccess"];
-type PresentationOpen = NonNullable<PresentationDefinition["body"]["open"]>;
+type PresentationOpen = NonNullable<PresentationActionBody["open"]>;
 type DefinedPresentationOpen<Open> = Open extends object
   ? Omit<Open, "input"> &
       Omit<PresentationOpen, "input"> & {
         input: DefaultedProperty<Open, "input", PresentationOpen["input"]>;
       }
   : never;
+type DefinedPresentationActionBody<Body> =
+  Body extends z.input<typeof presentationActionBodySchema>
+    ? Omit<Body, "input" | "open" | "onSuccess"> &
+        Omit<PresentationActionBody, "input" | "open" | "onSuccess"> & {
+          input: DefaultedProperty<
+            Body,
+            "input",
+            PresentationActionBody["input"]
+          >;
+          onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
+        } & ("open" extends keyof Body
+          ? undefined extends Body["open"]
+            ? {
+                open?: DefinedPresentationOpen<
+                  Exclude<Body["open"], undefined>
+                >;
+              }
+            : { open: DefinedPresentationOpen<Body["open"]> }
+          : { open?: PresentationActionBody["open"] })
+    : never;
+type DefinedPresentationComponentBody<Body> =
+  Body extends z.input<typeof presentationComponentBodySchema>
+    ? Omit<Body, "heading"> &
+        Omit<PresentationComponentBody, "heading"> & {
+          heading: DefaultedProperty<
+            Body,
+            "heading",
+            PresentationComponentBody["heading"]
+          >;
+        }
+    : never;
 type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
-  Omit<Body, "input" | "open" | "onSuccess"> &
-    Omit<PresentationDefinition["body"], "input" | "open" | "onSuccess"> & {
-      input: DefaultedProperty<
-        Body,
-        "input",
-        PresentationDefinition["body"]["input"]
-      >;
-      onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
-    } & ("open" extends keyof Body
-      ? undefined extends Body["open"]
-        ? { open?: DefinedPresentationOpen<Exclude<Body["open"], undefined>> }
-        : { open: DefinedPresentationOpen<Body["open"]> }
-      : { open?: PresentationDefinition["body"]["open"] });
+  Body extends { component: string }
+    ? DefinedPresentationComponentBody<Body>
+    : DefinedPresentationActionBody<Body>;
 type DefinedPresentationCommand<Command> = Command extends object
   ? Omit<Command, "input" | "blocking" | "onSuccess"> &
       Omit<PresentationCommand, "input" | "blocking" | "onSuccess"> & {
@@ -272,6 +321,18 @@ export interface PresentationActionRegistry {
   readonly [name: string]: ActionContract;
 }
 
+export function isPresentationActionBody(
+  body: PresentationDefinition["body"],
+): body is PresentationActionBody {
+  return "action" in body;
+}
+
+export function isPresentationComponentBody(
+  body: PresentationDefinition["body"],
+): body is PresentationComponentBody {
+  return "component" in body;
+}
+
 export interface PresentationRouteMatch {
   definition: PresentationDefinition;
   input: Record<string, string>;
@@ -312,8 +373,7 @@ export function matchPresentationRoute(
         const decoded = decodeRouteSegment(received);
         if (decoded === null) return [];
         input[expected.slice(1)] = decoded;
-      }
-      else if (expected !== received) return [];
+      } else if (expected !== received) return [];
     }
     return [{ definition, input }];
   });
@@ -527,46 +587,53 @@ export function validatePresentations(
       problems.push(`Presentation “${presentation.id}” duplicada.`);
     byId.set(presentation.id, presentation);
 
-    const bodyAction = actions[presentation.body.action];
-    if (bodyAction === undefined) {
-      problems.push(
-        `A action “${presentation.body.action}” não está disponível.`,
-      );
-    } else if (bodyAction.kind === "simple") {
-      problems.push(
-        `A action simple “${bodyAction.name}” não pode ocupar o body.`,
-      );
+    if (isPresentationComponentBody(presentation.body)) {
+      // O conteúdo interno permanece uma fronteira React opaca para a spec da casca.
     } else {
-      validateActionBindings(
-        presentation.body.input,
-        bodyAction,
-        `${presentation.id}.body.input`,
-        problems,
-      );
-      if (
-        bodyAction.kind === "view" &&
-        presentation.body.fields === undefined
-      ) {
+      const bodyAction = actions[presentation.body.action];
+      if (bodyAction === undefined) {
         problems.push(
-          `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          `A action “${presentation.body.action}” não está disponível.`,
         );
-      }
-      if (
-        bodyAction.kind !== "view" &&
-        presentation.body.fields !== undefined
-      ) {
-        problems.push(`Fields só podem ser declarados para uma action view.`);
-      }
-      if (bodyAction.kind !== "list" && presentation.body.open !== undefined) {
-        problems.push(`Open só pode ser declarado para uma action list.`);
-      }
-      if (
-        bodyAction.kind !== "form" &&
-        presentation.body.submitLabel !== undefined
-      ) {
+      } else if (bodyAction.kind === "simple") {
         problems.push(
-          `SubmitLabel só pode ser declarado para uma action form.`,
+          `A action simple “${bodyAction.name}” não pode ocupar o body.`,
+        );
+      } else {
+        validateActionBindings(
+          presentation.body.input,
+          bodyAction,
+          `${presentation.id}.body.input`,
+          problems,
         );
+        if (
+          bodyAction.kind === "view" &&
+          presentation.body.fields === undefined
+        ) {
+          problems.push(
+            `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          );
+        }
+        if (
+          bodyAction.kind !== "view" &&
+          presentation.body.fields !== undefined
+        ) {
+          problems.push(`Fields só podem ser declarados para uma action view.`);
+        }
+        if (
+          bodyAction.kind !== "list" &&
+          presentation.body.open !== undefined
+        ) {
+          problems.push(`Open só pode ser declarado para uma action list.`);
+        }
+        if (
+          bodyAction.kind !== "form" &&
+          presentation.body.submitLabel !== undefined
+        ) {
+          problems.push(
+            `SubmitLabel só pode ser declarado para uma action form.`,
+          );
+        }
       }
     }
 
@@ -615,7 +682,10 @@ export function validatePresentations(
           problems.push(
             `A route de “${presentation.id}” consulta a Presentation inexistente “${record.presentation}”.`,
           );
-        } else if (actions[source.body.action]?.kind !== "list") {
+        } else if (
+          !isPresentationActionBody(source.body) ||
+          actions[source.body.action]?.kind !== "list"
+        ) {
           problems.push(
             `A route de “${presentation.id}” exige que “${record.presentation}” tenha uma list action no body.`,
           );
@@ -633,7 +703,9 @@ export function validatePresentations(
         }
       }
     }
-    const open = presentation.body.open;
+    const open = isPresentationActionBody(presentation.body)
+      ? presentation.body.open
+      : undefined;
     if (open !== undefined && !byId.has(open.presentation)) {
       problems.push(
         `A lista “${presentation.id}” abre a Presentation inexistente “${open.presentation}”.`,
@@ -650,7 +722,9 @@ export function validatePresentations(
         );
       }
       const action =
-        target === undefined ? undefined : actions[target.body.action];
+        target !== undefined && isPresentationActionBody(target.body)
+          ? actions[target.body.action]
+          : undefined;
       if (action !== undefined) {
         validateActionBindings(
           open.input,
@@ -660,7 +734,10 @@ export function validatePresentations(
         );
       }
     }
-    for (const effect of presentation.body.onSuccess) {
+    const bodyEffects = isPresentationActionBody(presentation.body)
+      ? presentation.body.onSuccess
+      : [];
+    for (const effect of bodyEffects) {
       if (effect.effect !== "navigate") continue;
       const target = byId.get(effect.presentation);
       if (target === undefined) {
@@ -678,7 +755,9 @@ export function validatePresentations(
           `O body de “${presentation.id}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
         );
       }
-      const action = actions[target.body.action];
+      const action = isPresentationActionBody(target.body)
+        ? actions[target.body.action]
+        : undefined;
       if (action !== undefined) {
         validateActionBindings(
           effect.input,
@@ -706,7 +785,9 @@ export function validatePresentations(
                 `A action “${command.action}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
               );
             }
-            const action = actions[target.body.action];
+            const action = isPresentationActionBody(target.body)
+              ? actions[target.body.action]
+              : undefined;
             if (action !== undefined) {
               validateActionBindings(
                 effect.input,
@@ -724,6 +805,10 @@ export function validatePresentations(
         problems.push(
           `A action “${command.action}” abre a Presentation inexistente “${command.target.presentation}”.`,
         );
+      } else if (!isPresentationActionBody(target.body)) {
+        problems.push(
+          `A Presentation “${target.id}” usa conteúdo de componente e não pode ser aberta pela action “${command.action}”.`,
+        );
       } else if (target.body.action !== command.action) {
         problems.push(
           `A Presentation “${target.id}” usa “${target.body.action}”, mas foi aberta por “${command.action}”.`,

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

@@ -1,13 +1,15 @@
 import {
   useCallback,
+  useEffect,
   useState,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
-import { ArrowLeft, Braces } from "lucide-react";
+import { ArrowLeft, Braces, MessageCircle } from "lucide-react";
 import type {
   PresentationActionRegistry,
+  PresentationActionBody,
   PresentationBindingContext,
   PresentationCommand,
   PresentationDiagnostic,
@@ -19,6 +21,7 @@ import type {
 import {
   applyPresentationEffects,
   createPresentationInspectionSnapshot,
+  isPresentationActionBody,
   openPresentation,
   resolvePresentationBindings,
 } from "../../../core/presentation.ts";
@@ -75,6 +78,7 @@ import {
   ContentHeader,
   ContentTitle,
 } from "./content-header.tsx";
+import { SurfaceAssistant } from "./surface-assistant.tsx";
 
 interface PresentationFrameProps {
   surface: PresentationSurface;
@@ -90,6 +94,11 @@ interface PresentationFrameProps {
   className?: string;
   bodyClassName?: string;
   listBody?: boolean;
+  contentOwnsHeading?: boolean;
+  assistantOpen?: boolean;
+  assistantLabel?: string;
+  assistantAction?: ReactNode;
+  assistantPanel?: ReactNode;
 }
 
 const bodyClassName =
@@ -124,6 +133,11 @@ function PresentationFrame({
   className,
   bodyClassName: bodyClassNameProp,
   listBody = false,
+  contentOwnsHeading = false,
+  assistantOpen = false,
+  assistantLabel,
+  assistantAction,
+  assistantPanel,
 }: PresentationFrameProps): ReactElement {
   const insidePageShell = useInsidePageShell();
   const [footerTarget, setFooterTarget] = useState<HTMLElement | null>(null);
@@ -153,6 +167,20 @@ function PresentationFrame({
       {typeof children === "function" ? children(footerTarget) : children}
     </div>
   );
+  const withAssistant = (content: ReactElement): ReactElement =>
+    assistantLabel === undefined || assistantPanel === undefined ? (
+      content
+    ) : (
+      <SurfaceAssistant
+        open={assistantOpen}
+        assistantLabel={assistantLabel}
+        assistant={assistantPanel}
+        className="min-h-0 flex-1"
+        contentClassName="flex min-h-0 flex-col"
+      >
+        {content}
+      </SurfaceAssistant>
+    );
 
   if (surface === "page") {
     if (listBody) {
@@ -171,13 +199,20 @@ function PresentationFrame({
       );
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          {navigation === undefined ? null : (
+          {navigation === undefined && assistantAction === undefined ? null : (
             <PageHeader>
-              <PageNavigation>{navigation}</PageNavigation>
+              {navigation === undefined ? null : (
+                <PageNavigation>{navigation}</PageNavigation>
+              )}
+              {assistantAction === undefined ? null : (
+                <PageActions>{assistantAction}</PageActions>
+              )}
             </PageHeader>
           )}
-          <PageBody className="min-h-0 flex-1 overflow-y-auto">
-            {content}
+          <PageBody className="min-h-0 flex-1 overflow-hidden">
+            {withAssistant(
+              <div className="h-full overflow-y-auto">{content}</div>,
+            )}
           </PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
@@ -186,22 +221,36 @@ function PresentationFrame({
     if (insidePageShell) {
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          {navigation === undefined && headerActions === undefined ? null : (
+          {navigation === undefined &&
+          headerActions === undefined &&
+          assistantAction === undefined ? null : (
             <PageHeader>
               {navigation === undefined ? null : (
                 <PageNavigation>{navigation}</PageNavigation>
               )}
-              {headerActions === undefined ? null : (
+              {headerActions === undefined &&
+              assistantAction === undefined ? null : (
                 <PageActions>
-                  <PresentationActions>{headerActions}</PresentationActions>
+                  <PresentationActions>
+                    {headerActions}
+                    {assistantAction}
+                  </PresentationActions>
                 </PageActions>
               )}
             </PageHeader>
           )}
-          <PageIntro>
-            <PageTitle>{title}</PageTitle>
-          </PageIntro>
-          <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
+          <PageBody className="min-h-0 flex-1 overflow-hidden">
+            {withAssistant(
+              <div className="flex h-full min-h-0 flex-col overflow-y-auto">
+                {contentOwnsHeading ? null : (
+                  <PageIntro>
+                    <PageTitle>{title}</PageTitle>
+                  </PageIntro>
+                )}
+                {body}
+              </div>,
+            )}
+          </PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
       );
@@ -218,14 +267,20 @@ function PresentationFrame({
             <PageNavigation>{navigation}</PageNavigation>
           )}
           <PageTitle className="text-lg leading-none">{title}</PageTitle>
-          {headerActions === undefined ? null : (
+          {headerActions === undefined &&
+          assistantAction === undefined ? null : (
             <PageActions>
-              <PresentationActions>{headerActions}</PresentationActions>
+              <PresentationActions>
+                {headerActions}
+                {assistantAction}
+              </PresentationActions>
             </PageActions>
           )}
         </PageHeader>
-        <PageBody className="min-h-0 flex-1 overflow-y-auto px-8 py-8">
-          {body}
+        <PageBody className="min-h-0 flex-1 overflow-hidden">
+          {withAssistant(
+            <div className="h-full overflow-y-auto px-8 py-8">{body}</div>,
+          )}
         </PageBody>
         {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
       </Page>
@@ -242,7 +297,10 @@ function PresentationFrame({
         }}
       >
         <DialogContent
-          className={className}
+          className={cn(
+            assistantOpen ? "h-[min(48rem,85vh)] max-w-5xl" : undefined,
+            className,
+          )}
           aria-describedby={undefined}
           closeDisabled={blocked}
           onEscapeKeyDown={(event) => {
@@ -252,17 +310,23 @@ function PresentationFrame({
             if (blocked) event.preventDefault();
           }}
         >
-          <DialogHeader>
-            {navigation}
-            <DialogTitle className="truncate">{title}</DialogTitle>
-            {headerActions === undefined ? null : (
-              <PresentationActions>{headerActions}</PresentationActions>
-            )}
-          </DialogHeader>
-          <DialogBody>{body}</DialogBody>
-          {hasFooter ? (
-            <DialogFooter>{renderFooterActions()}</DialogFooter>
-          ) : null}
+          <div className="flex h-full min-h-0 flex-col">
+            <DialogHeader>
+              {navigation}
+              <DialogTitle className="truncate">{title}</DialogTitle>
+              {headerActions === undefined &&
+              assistantAction === undefined ? null : (
+                <PresentationActions>
+                  {headerActions}
+                  {assistantAction}
+                </PresentationActions>
+              )}
+            </DialogHeader>
+            {withAssistant(<DialogBody>{body}</DialogBody>)}
+            {hasFooter ? (
+              <DialogFooter>{renderFooterActions()}</DialogFooter>
+            ) : null}
+          </div>
         </DialogContent>
       </Dialog>
     );
@@ -277,7 +341,12 @@ function PresentationFrame({
       }}
     >
       <DrawerContent
-        className={className}
+        className={cn(
+          assistantOpen
+            ? "w-[min(80rem,calc(100%-2rem))] max-w-none"
+            : undefined,
+          className,
+        )}
         aria-describedby={undefined}
         closeDisabled={blocked}
         onEscapeKeyDown={(event) => {
@@ -287,22 +356,33 @@ function PresentationFrame({
           if (blocked) event.preventDefault();
         }}
       >
-        <DrawerHeader>
-          {navigation}
-          <DrawerTitle className="truncate">{title}</DrawerTitle>
-          {headerActions === undefined ? null : (
-            <PresentationActions>{headerActions}</PresentationActions>
-          )}
-        </DrawerHeader>
-        <DrawerBody>{body}</DrawerBody>
-        {hasFooter ? (
-          <DrawerFooter>{renderFooterActions()}</DrawerFooter>
-        ) : null}
+        <div className="flex h-full min-h-0 flex-col">
+          <DrawerHeader>
+            {navigation}
+            <DrawerTitle className="truncate">{title}</DrawerTitle>
+            {headerActions === undefined &&
+            assistantAction === undefined ? null : (
+              <PresentationActions>
+                {headerActions}
+                {assistantAction}
+              </PresentationActions>
+            )}
+          </DrawerHeader>
+          {withAssistant(<DrawerBody>{body}</DrawerBody>)}
+          {hasFooter ? (
+            <DrawerFooter>{renderFooterActions()}</DrawerFooter>
+          ) : null}
+        </div>
       </DrawerContent>
     </Drawer>
   );
 }
 
+export interface PresentationAssistantRuntime {
+  icon?: ReactNode;
+  render: (controls: { close: () => void }) => ReactNode;
+}
+
 export interface PresentationProps {
   /** Definição estática registrada e publicada no manifest. */
   definition: PresentationDefinition;
@@ -325,6 +405,10 @@ export interface PresentationProps {
   onOpenChange?: (open: boolean) => void;
   className?: string;
   bodyClassName?: string;
+  /** Conteúdo React da boundary declarada por `body.component`. */
+  children?: ReactNode;
+  /** Painel runtime; a página fecha sobre os dados do recurso que ela carregou. */
+  assistant?: PresentationAssistantRuntime;
 }
 
 function actionLabel(action: { name: string; label?: unknown }): string {
@@ -394,6 +478,8 @@ export function Presentation({
   onOpenChange,
   className,
   bodyClassName: bodyClassNameProp,
+  children,
+  assistant,
 }: PresentationProps): ReactElement {
   if (definition.id !== invocation.presentationId) {
     throw new Error(
@@ -404,16 +490,17 @@ export function Presentation({
     ReadonlySet<PresentationCommand>
   >(() => new Set());
   const [bodyLoading, setBodyLoading] = useState(false);
+  const [assistantOpen, setAssistantOpen] = useState(false);
+  useEffect(() => {
+    setAssistantOpen(false);
+  }, [definition.id, invocation.surface]);
   const context: PresentationBindingContext = {
     ...bindingContext,
     route: bindingContext?.route ?? invocation.input,
   };
 
   const applyEffects = useCallback(
-    (
-      effects: PresentationDefinition["body"]["onSuccess"],
-      result?: unknown,
-    ): void => {
+    (effects: PresentationActionBody["onSuccess"], result?: unknown): void => {
       const next = applyPresentationEffects(
         invocation,
         effects,
@@ -541,23 +628,51 @@ export function Presentation({
     );
   };
 
-  const bodyAction = actions[definition.body.action];
-  if (bodyAction === undefined) {
-    throw new Error(`Action “${definition.body.action}” não registrada.`);
+  const actionBody = isPresentationActionBody(definition.body)
+    ? definition.body
+    : null;
+  const bodyAction = actionBody === null ? null : actions[actionBody.action];
+  if (actionBody !== null && bodyAction === undefined) {
+    throw new Error(`Action “${actionBody.action}” não registrada.`);
   }
-  const bodyInput = resolvePresentationBindings(
-    definition.body.input,
-    context,
-  ) as Record<string, unknown>;
+  if (actionBody === null && children === undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” declara body.component e exige children.`,
+    );
+  }
+  if (actionBody !== null && children !== undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” usa body.action e não aceita children.`,
+    );
+  }
+  if (definition.assistant !== undefined && assistant === undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” declara assistência e exige a prop assistant.`,
+    );
+  }
+  if (definition.assistant === undefined && assistant !== undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” não declara assistência e não aceita a prop assistant.`,
+    );
+  }
+  const bodyInput =
+    actionBody === null
+      ? {}
+      : (resolvePresentationBindings(actionBody.input, context) as Record<
+          string,
+          unknown
+        >);
   const renderBody = (footerTarget: HTMLElement | null): ReactNode => {
+    if (actionBody === null) return children;
+    if (bodyAction === null) return null;
     if (bodyAction.kind === "form") {
       return (
         <ActionForm
           action={bodyAction as FormContract<Record<string, unknown>, unknown>}
           defaultValues={bodyInput}
-          submitLabel={definition.body.submitLabel}
+          submitLabel={actionBody.submitLabel}
           onCancel={invocation.surface === "page" ? undefined : closeSurface}
-          onSuccess={(data) => applyEffects(definition.body.onSuccess, data)}
+          onSuccess={(data) => applyEffects(actionBody.onSuccess, data)}
           disabled={hasSurfaceBlock}
           onLoadingChange={setBodyLoading}
           footer={(actions) =>
@@ -578,14 +693,14 @@ export function Presentation({
           input={bodyInput}
           state={listState}
           onStateChange={onListStateChange}
-          {...(definition.body.open === undefined
+          {...(actionBody.open === undefined
             ? {}
             : {
                 onRowClick: (item: Record<string, unknown>) =>
                   openTarget(
-                    definition.body.open!.presentation,
-                    definition.body.open!.surface,
-                    definition.body.open!.input,
+                    actionBody.open!.presentation,
+                    actionBody.open!.surface,
+                    actionBody.open!.input,
                     { ...context, item },
                   ),
               })}
@@ -593,7 +708,7 @@ export function Presentation({
       );
     }
     if (bodyAction.kind === "view") {
-      const fields = definition.body.fields ?? [];
+      const fields = actionBody.fields ?? [];
       return (
         <ActionView
           action={bodyAction as ViewContract<Record<string, unknown>, unknown>}
@@ -641,6 +756,22 @@ export function Presentation({
       <ArrowLeft aria-hidden />
     </Button>
   );
+  const assistantAction =
+    definition.assistant === undefined || assistantOpen ? undefined : (
+      <Button
+        size="icon"
+        variant="ghost"
+        aria-label={definition.assistant.triggerLabel}
+        title={definition.assistant.triggerLabel}
+        onClick={() => setAssistantOpen(true)}
+      >
+        {assistant?.icon ?? <MessageCircle aria-hidden />}
+      </Button>
+    );
+  const assistantPanel =
+    definition.assistant === undefined || assistant === undefined
+      ? undefined
+      : assistant.render({ close: () => setAssistantOpen(false) });
 
   return (
     <PresentationFrame
@@ -659,9 +790,17 @@ export function Presentation({
       }}
       className={className}
       bodyClassName={bodyClassNameProp}
-      hasBodyFooter={bodyAction.kind === "form"}
+      hasBodyFooter={bodyAction?.kind === "form"}
       blocked={surfaceBlocked}
-      listBody={bodyAction.kind === "list"}
+      listBody={bodyAction?.kind === "list"}
+      contentOwnsHeading={
+        !isPresentationActionBody(definition.body) &&
+        definition.body.heading === "content"
+      }
+      assistantOpen={assistantOpen}
+      assistantLabel={definition.assistant?.triggerLabel}
+      assistantAction={assistantAction}
+      assistantPanel={assistantPanel}
     >
       {renderBody}
     </PresentationFrame>

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

@@ -48,6 +48,8 @@ export interface SplitProps {
   /** Chamado ao concluir uma mudança de layout; pode persistir o resultado em localStorage. */
   onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void
   className?: string
+  /** Identificador semântico opcional para testes e composição de patterns. */
+  'data-slot'?: string
   children: ReactNode
 }
 
@@ -86,6 +88,7 @@ export function Split({
   defaultLayout,
   onLayoutChanged,
   className,
+  'data-slot': dataSlot = 'split',
   children,
 }: SplitProps): React.ReactElement {
   const panes = panesOf(children)
@@ -93,7 +96,7 @@ export function Split({
 
   if (!resizable) {
     return (
-      <div id={id === undefined ? undefined : String(id)} data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+      <div id={id === undefined ? undefined : String(id)} data-slot={dataSlot} data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
         {panes}
       </div>
     )
@@ -111,7 +114,7 @@ export function Split({
       orientation={direction}
       defaultLayout={defaultLayout}
       onLayoutChanged={onLayoutChanged}
-      data-slot="split"
+      data-slot={dataSlot}
       className={cn('min-h-0 min-w-0 flex-1', className)}
     >
       {panes.flatMap((pane, index) => {

package/src/ui/components/patterns/surface-assistant.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+import { cn } from "../../lib/cn.ts";
+import { Pane, type PaneSize, Split } from "./split.tsx";
+
+export interface SurfaceAssistantProps {
+  /** Controla somente a presença visual do painel; o conteúdo pertence ao consumidor. */
+  open: boolean;
+  /** Nome acessível da região complementar. */
+  assistantLabel: string;
+  /** Conteúdo principal que permanece visível à esquerda. */
+  children: ReactNode;
+  /** Painel fornecido pela superfície que conhece o contexto do recurso. */
+  assistant: ReactNode;
+  initialSize?: PaneSize;
+  minSize?: PaneSize;
+  maxSize?: PaneSize;
+  className?: string;
+  contentClassName?: string;
+  assistantClassName?: string;
+}
+
+/**
+ * Mantém conteúdo e assistência contextual na mesma superfície. O host decide abertura,
+ * trigger e dados; o pattern preserva a relação espacial e o redimensionamento.
+ */
+export function SurfaceAssistant({
+  open,
+  assistantLabel,
+  children,
+  assistant,
+  initialSize = "28rem",
+  minSize = "20rem",
+  maxSize = "40rem",
+  className,
+  contentClassName,
+  assistantClassName,
+}: SurfaceAssistantProps): React.ReactElement {
+  return (
+    <Split
+      resizable
+      data-slot="surface-assistant"
+      className={cn("h-full", className)}
+    >
+      <Pane
+        key="surface-content"
+        id="surface-content"
+        grow
+        inset="none"
+        className={cn("h-full", contentClassName)}
+      >
+        {children}
+      </Pane>
+      {open ? (
+        <Pane
+          key="surface-assistant"
+          id="surface-assistant"
+          initialSize={initialSize}
+          minSize={minSize}
+          maxSize={maxSize}
+          inset="none"
+          className={cn("h-full bg-background", assistantClassName)}
+        >
+          <aside
+            data-slot="surface-assistant-panel"
+            aria-label={assistantLabel}
+            className="h-full min-w-0 overflow-hidden"
+          >
+            {assistant}
+          </aside>
+        </Pane>
+      ) : null}
+    </Split>
+  );
+}

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

@@ -32,11 +32,20 @@ shell que efetivamente hospeda a rota.
 O exemplo declara a Presentation sobre um contrato de formulário e alterna a superfície. O
 `DocBrowserActionProvider` simula o cliente de actions; na aplicação, esse papel é do provider real.
 
+Quando o recurso aceita assistência contextual, declare somente o gatilho serializável em
+`assistant`. O renderer coloca esse gatilho no cabeçalho e abre o painel à direita do body da
+própria Page, Dialog ou Drawer. Cabeçalho e rodapé continuam ocupando toda a largura da superfície;
+enquanto o painel está aberto, o gatilho sai do cabeçalho e o próprio painel assume sua identidade
+visual. O dado vivo do recurso não entra na definição: a página que o carregou fornece
+`assistant.render`, captura identidade, nome e demais dados autorizados e monta o chat. Assim,
+contexto de conversa não vira autorização nem dado persistido no manifest.
+
 ```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
   id: "workspace.create",
   title: "Criar workspace",
+  assistant: { triggerLabel: "Conversar sobre este workspace" },
   body: { action: docWorkspaceCreate.name },
 });
 
@@ -81,6 +90,22 @@ function Example() {
             if (next) setInvocation(next);
             else setOpen(false);
           }}
+          assistant={{
+            render: ({ close }) => (
+              <div className="flex h-full flex-col p-3">
+                <p className="text-sm">
+                  Conversa vinculada ao workspace carregado pela página.
+                </p>
+                <Button
+                  className="mt-3 self-start"
+                  variant="ghost"
+                  onClick={close}
+                >
+                  Fechar
+                </Button>
+              </div>
+            ),
+          }}
         />
       </div>
     </DocBrowserActionProvider>
@@ -164,21 +189,22 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 
 ## Propriedades de Presentation
 
-| Propriedade          | Tipo                                             | Padrão | Descrição                                              |
-| -------------------- | ------------------------------------------------ | ------ | ------------------------------------------------------ |
-| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.              |
-| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno. |
-| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato. |
-| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.              |
-| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.   |
-| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                |
-| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.           |
-| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL. |
+| Propriedade          | Tipo                                             | Padrão | Descrição                                                                                           |
+| -------------------- | ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
+| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.                                                           |
+| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno.                                              |
+| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato.                                              |
+| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.                                                           |
+| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.                                                |
+| `assistant`          | `PresentationAssistantRuntime`                   |        | Painel contextual fornecido pela superfície hospedeira.                                             |
+| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                                                             |
+| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.                                                        |
+| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL.             |
 | `onListStateChange`  | `(state: ActionListState) => void`               |        | Recebe cada mudança de recorte ou exibição da lista do body, como busca, filtros, período e página. |
-| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                 |
-| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.    |
-| `className`          | `string`                                         |        | Classes adicionais da superfície.                      |
-| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.   |
+| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                                                              |
+| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.                                                 |
+| `className`          | `string`                                         |        | Classes adicionais da superfície.                                                                   |
+| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.                                                |
 
 ## Propriedades de PresentationInspector
 

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

@@ -12,11 +12,13 @@ render(
         <div className="p-4 text-sm">Navegação</div>
       </Pane>
       <Pane grow inset="lg">
-        <p className="text-sm text-muted-foreground">Conteúdo. Arraste a divisória.</p>
+        <p className="text-sm text-muted-foreground">
+          Conteúdo. Arraste a divisória.
+        </p>
       </Pane>
     </Split>
   </div>,
-)
+);
 ```
 
 ## Espaçamento interno
@@ -30,8 +32,12 @@ Quando uma área precisa continuar legível em telas largas, use uma unidade abs
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none"><Main /></Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none"><Inspector /></Pane>
+  <Pane grow inset="none">
+    <Main />
+  </Pane>
+  <Pane initialSize="28rem" minSize="20rem" inset="none">
+    <Inspector />
+  </Pane>
 </Split>
 ```
 
@@ -75,23 +81,78 @@ const defaultLayout = readLayout('workspace-layout')
 
 Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.
 
+## Assistência dentro da superfície
+
+`SurfaceAssistant` especializa o split usado por uma Page, Dialog ou Drawer que abre assistência
+contextual. O conteúdo principal permanece montado e o painel aparece à direita com largura
+redimensionável. A superfície hospedeira controla o gatilho, o estado aberto e os dados passados ao
+painel; o pattern cuida apenas da relação espacial. Envolva somente o body da superfície com
+`SurfaceAssistant`: cabeçalho e rodapé devem permanecer fora do split e ocupar toda a largura.
+
+```tsx preview
+function Example() {
+  const [open, setOpen] = React.useState(true);
+
+  return (
+    <div className="h-72 overflow-hidden rounded-lg border border-border">
+      <SurfaceAssistant
+        open={open}
+        assistantLabel="Assistente do pedido"
+        assistant={
+          <div className="h-full p-3">
+            <p className="text-sm">Conversa vinculada ao pedido carregado.</p>
+            <Button
+              className="mt-3"
+              variant="ghost"
+              onClick={() => setOpen(false)}
+            >
+              Fechar
+            </Button>
+          </div>
+        }
+      >
+        <div className="h-full p-3">
+          <Button variant="outline" onClick={() => setOpen(true)}>
+            Abrir assistente
+          </Button>
+        </div>
+      </SurfaceAssistant>
+    </div>
+  );
+}
+
+render(<Example />);
+```
+
 ## Propriedades de Split
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Sentido em que os panes se alinham. |
-| `resizable` | `boolean` | `false` | Cada fronteira ganha um separador acessível e arrastável. |
-| `handle` | `boolean` | `false` | Mostra a alça visual no separador. |
-| `id` | `string` | | Identidade estável do grupo redimensionável. |
-| `defaultLayout` | `Record<string, number>` | | Layout percentual restaurado, indexado pelos ids dos panes. |
-| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` | | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
+| Propriedade       | Tipo                                      | Padrão         | Descrição                                                               |
+| ----------------- | ----------------------------------------- | -------------- | ----------------------------------------------------------------------- |
+| `direction`       | `'horizontal' \| 'vertical'`              | `'horizontal'` | Sentido em que os panes se alinham.                                     |
+| `resizable`       | `boolean`                                 | `false`        | Cada fronteira ganha um separador acessível e arrastável.               |
+| `handle`          | `boolean`                                 | `false`        | Mostra a alça visual no separador.                                      |
+| `id`              | `string`                                  |                | Identidade estável do grupo redimensionável.                            |
+| `defaultLayout`   | `Record<string, number>`                  |                | Layout percentual restaurado, indexado pelos ids dos panes.             |
+| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` |                | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
 
 ## Propriedades de Pane
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
-| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
-| `minSize` / `maxSize` | `number \| string` | | Limites quando o split é redimensionável. |
-| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
-| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio. |
+| Propriedade           | Tipo                             | Padrão  | Descrição                                                                                 |
+| --------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `id`                  | `string`                         |         | Identidade estável usada pelo layout redimensionável e persistido.                        |
+| `initialSize`         | `number \| string`               |         | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string`               |         | Limites quando o split é redimensionável.                                                 |
+| `grow`                | `boolean`                        | `false` | Ocupa o espaço remanescente no layout simples.                                            |
+| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`  | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio.             |
+
+## Propriedades de SurfaceAssistant
+
+| Propriedade      | Tipo        | Padrão  | Descrição                                               |
+| ---------------- | ----------- | ------- | ------------------------------------------------------- |
+| `open`           | `boolean`   |         | Exibe o painel complementar à direita.                  |
+| `assistantLabel` | `string`    |         | Nome acessível da região complementar.                  |
+| `children`       | `ReactNode` |         | Conteúdo principal que permanece montado.               |
+| `assistant`      | `ReactNode` |         | Painel fornecido pela superfície que conhece o recurso. |
+| `initialSize`    | `PaneSize`  | `28rem` | Largura inicial do painel.                              |
+| `minSize`        | `PaneSize`  | `20rem` | Largura mínima durante o redimensionamento.             |
+| `maxSize`        | `PaneSize`  | `40rem` | Largura máxima durante o redimensionamento.             |

package/src/ui/meta.ts

@@ -321,7 +321,7 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",

package/src/ui/react.tsx

@@ -424,6 +424,7 @@ export {
   PresentationInspector,
 } from "./components/patterns/presentation.tsx";
 export type {
+  PresentationAssistantRuntime,
   PresentationProps,
   PresentationInspectorProps,
 } from "./components/patterns/presentation.tsx";
@@ -483,6 +484,10 @@ export type {
   SplitLayoutChange,
 } from "./components/patterns/split.tsx";
 
+// Assistência contextual: mantém o recurso visível e abre um painel redimensionável na superfície.
+export { SurfaceAssistant } from "./components/patterns/surface-assistant.tsx";
+export type { SurfaceAssistantProps } from "./components/patterns/surface-assistant.tsx";
+
 // A barra de ferramentas que flutua sobre uma superfície de trabalho (canvas, editor, preview).
 export {
   Dock,