ghostykit 0.6.4 → 0.7.0

package/dist/core/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./types";
 export { argsDetail, beginSend, beginSteer, createPilotState, dropLastExchange, expiryMs, lastUserTurn, markSubagent, messagesToTurns, prependHistory, queueMessage, reduceAgUiEvent, resolvePermission, sendFailed, stopTurn, subagentsOf, takeQueued, toPermission, } from "./reducer";
 export { applyJsonPatch, type PatchOp } from "./jsonPatch";
-export { isNarration, narrationToMarkdown, splitNarration } from "./narration";
+export { extractBlocks, isNarration, narrationToMarkdown, splitNarration, type TextBlock } from "./narration";
 export { cleanReplyOption, extractReplyOptions, type ReplyOptions } from "./options";
 export { TOOL_VERBS_EN, TOOL_VERBS_ES, groupSteps, isRunning, stepLabel, summarizeTools, toolName, toolNames, type ToolVerb, type ToolVerbs, } from "./steps";
 export { applyReferences, cleanUserText, formatDuration, systemNoteOf } from "./text";

package/dist/core/index.js

@@ -1,6 +1,4 @@
 import {
-  TOOL_VERBS_EN,
-  TOOL_VERBS_ES,
   applyJsonPatch,
   argsDetail,
   beginSend,
@@ -9,10 +7,9 @@ import {
   createPilotState,
   dropLastExchange,
   expiryMs,
+  extractBlocks,
   extractReplyOptions,
-  groupSteps,
   isNarration,
-  isRunning,
   lastUserTurn,
   markSubagent,
   messagesToTurns,
@@ -23,15 +20,21 @@ import {
   resolvePermission,
   sendFailed,
   splitNarration,
-  stepLabel,
   stopTurn,
   subagentsOf,
-  summarizeTools,
   takeQueued,
-  toPermission,
+  toPermission
+} from "../chunks/chunk-FWBUIGTC.js";
+import {
+  TOOL_VERBS_EN,
+  TOOL_VERBS_ES,
+  groupSteps,
+  isRunning,
+  stepLabel,
+  summarizeTools,
   toolName,
   toolNames
-} from "../chunks/chunk-LPPND5ME.js";
+} from "../chunks/chunk-UUH37KXA.js";
 import {
   applyReferences,
   cleanUserText,
@@ -51,6 +54,7 @@ export {
   createPilotState,
   dropLastExchange,
   expiryMs,
+  extractBlocks,
   extractReplyOptions,
   formatDuration,
   groupSteps,

package/dist/core/narration.d.ts

@@ -9,9 +9,26 @@
  */
 /** Un tramo es «narración» si es corto y de un solo párrafo; si no, es texto normal. */
 export declare function isNarration(chunk: string): boolean;
-export declare function splitNarration(text: string, cuts?: number[]): {
+export declare function splitNarration(text: string, cuts?: number[], closed?: boolean): {
     steps: string[];
     rest: string;
 };
 /** La copia que se guarda: narración como `- ✓ …` y luego la respuesta. */
 export declare function narrationToMarkdown(chunks: string[], answer: string): string;
+/** Un bloque con nombre del texto (```eb-file …```) que una app pinta como tarjeta. */
+export interface TextBlock {
+    lang: string;
+    body: string;
+    /** El bloque ya cerró (en vivo, uno a medio escribir llega sin cerrar). */
+    complete: boolean;
+}
+/**
+ * Saca del texto los bloques ```<lang>``` cuyos nombres se piden (sólo los que abren al inicio de un
+ * renglón) y recorre los cortes de la narración para que sigan cayendo donde caían. Uno sin cerrar
+ * (todavía se escribe) se saca hasta el final.
+ */
+export declare function extractBlocks(text: string, langs: readonly string[], cuts?: number[]): {
+    text: string;
+    cuts?: number[];
+    blocks: TextBlock[];
+};

package/dist/plugins/index.d.ts

@@ -0,0 +1,39 @@
+import { type PilotoPlugin, type PluginCtx } from "../react/plugins";
+export interface ModelPickerOptions {
+    /** La llave de `agentState` con `{current, options: [{value, name}]}`. Default: `model`. */
+    stateKey?: string;
+    /** Cambiar de modelo es API de la app (no un run): aquí la llamas. */
+    onChange: (value: string, ctx: PluginCtx) => void | Promise<void>;
+}
+/**
+ * El selector de modelo en la barra del composer, con lo que el agente anuncia en
+ * `agentState.model = {current, options}`.
+ */
+export declare function modelPicker({ stateKey, onChange }: ModelPickerOptions): PilotoPlugin;
+/** Una página que el agente arma en vivo (`CUSTOM ghosty.page`). */
+export interface LivePage {
+    pageId: string;
+    title: string;
+    sections: {
+        id: string;
+        title?: string;
+        status: "pending" | "building" | "done" | "failed";
+    }[];
+    url: string | null;
+    error?: string;
+}
+export interface LivePageOptions {
+    /** Ancho del panel. Default: 320 px. */
+    width?: number;
+}
+/**
+ * El panel de la página en vivo: escucha `ghosty.page` (plan, secciones, lista, error) y pinta el
+ * avance a un lado del chat, con el enlace al terminar.
+ */
+export declare function livePage({ width }?: LivePageOptions): PilotoPlugin;
+export interface DevtoolsOptions {
+    /** Además de la lista de plugins, cada evento con quién lo atiende. Default: no. */
+    events?: boolean;
+}
+/** Imprime en consola los plugins montados, sus puntos y lo que atienden (y, si quieres, cada evento). */
+export declare function pilotDevtools({ events }?: DevtoolsOptions): PilotoPlugin;

package/dist/plugins/index.js

@@ -0,0 +1,129 @@
+import {
+  ModelPicker,
+  definePlugin,
+  pluginPoints,
+  pluginRequires
+} from "../chunks/chunk-ZIUOXG7B.js";
+import "../chunks/chunk-UUH37KXA.js";
+import "../chunks/chunk-6U545WJG.js";
+
+// src/plugins/index.tsx
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+function modelPicker({ stateKey = "model", onChange }) {
+  function Picker({ ctx }) {
+    const model = ctx.agentState[stateKey];
+    const [chosen, setChosen] = useState(null);
+    useEffect(() => setChosen(null), [model?.current]);
+    if (!model?.options?.length) return null;
+    return /* @__PURE__ */ jsx(
+      ModelPicker,
+      {
+        models: model.options,
+        current: chosen ?? model.current ?? null,
+        onChange: (value) => {
+          setChosen(value);
+          void onChange(value, ctx);
+        }
+      }
+    );
+  }
+  return definePlugin({ name: "modelPicker", styles: "ghostykit", requires: { state: [stateKey] }, composer: { actionsEnd: Picker } });
+}
+function livePage({ width = 320 } = {}) {
+  let page = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const set = (next) => {
+    page = next;
+    for (const l of listeners) l();
+  };
+  const store = {
+    subscribe: (l) => {
+      listeners.add(l);
+      return () => void listeners.delete(l);
+    },
+    get: () => page
+  };
+  const status = (id, s) => page && set({ ...page, sections: page.sections.map((x) => x.id === id ? { ...x, status: s } : x) });
+  function onPage(e) {
+    const v = e.value ?? {};
+    switch (v.event) {
+      case "page-plan":
+        return set({ pageId: v.pageId, title: v.title, url: null, sections: (v.sections ?? []).map((x) => ({ id: x.id, title: x.title, status: "pending" })) });
+      case "section-building":
+        return status(v.id, "building");
+      case "section":
+        return status(v.id, v.ok === false ? "failed" : "done");
+      case "page-ready":
+        return page && set({ ...page, title: v.title ?? page.title, url: v.url ?? null });
+      case "page-error":
+        return page && set({ ...page, error: v.message });
+      case "page-drop":
+        return page?.pageId === v.pageId && set(null);
+    }
+  }
+  function Panel({ ctx }) {
+    const p = useSyncExternalStore(store.subscribe, store.get, store.get);
+    if (!p) return null;
+    const done = p.sections.filter((x) => x.status === "done").length;
+    return /* @__PURE__ */ jsxs("aside", { style: { width }, className: "hidden shrink-0 flex-col gap-3 overflow-y-auto border-l border-border-primary bg-background-secondary p-4 text-sm md:flex", children: [
+      /* @__PURE__ */ jsxs("div", { children: [
+        /* @__PURE__ */ jsx("p", { className: "font-medium text-text-primary", children: p.title }),
+        /* @__PURE__ */ jsxs("p", { className: "text-xs text-text-tertiary", children: [
+          done,
+          "/",
+          p.sections.length,
+          " ",
+          ctx.strings.numberLocale.startsWith("en") ? "sections" : "secciones"
+        ] })
+      ] }),
+      /* @__PURE__ */ jsx("ul", { className: "flex flex-col gap-1.5", children: p.sections.map((x) => /* @__PURE__ */ jsxs("li", { "data-status": x.status, className: "flex items-center gap-2", children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: `h-2 w-2 shrink-0 rounded-full ${x.status === "done" ? "bg-text-success" : x.status === "failed" ? "bg-text-danger" : x.status === "building" ? "animate-pulse bg-brand-500" : "bg-border-primary"}`
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { className: "truncate text-text-secondary", children: x.title ?? x.id })
+      ] }, x.id)) }),
+      p.error && /* @__PURE__ */ jsx("p", { className: "text-xs text-text-danger", children: p.error }),
+      p.url && /* @__PURE__ */ jsx("a", { href: p.url, target: "_blank", rel: "noopener noreferrer", className: "self-start rounded-full bg-brand-500 px-3 py-1 text-white hover:bg-brand-600", children: ctx.strings.linkOpen })
+    ] });
+  }
+  return definePlugin({ name: "livePage", styles: "ghostykit", requires: { events: ["ghosty.page"] }, events: { "ghosty.page": onPage }, sidePanel: Panel });
+}
+function pilotDevtools({ events = false } = {}) {
+  function Devtools({ ctx }) {
+    const names = ctx.plugins.map((p) => p.name).join(",");
+    useEffect(() => {
+      console.groupCollapsed(`[ghostykit] ${ctx.plugins.length} plugins`);
+      console.table(
+        ctx.plugins.map((p) => {
+          const req = pluginRequires(p);
+          return { plugin: p.name, points: pluginPoints(p).join(" "), events: req.events.join(" "), state: req.state.join(" ") };
+        })
+      );
+      console.groupEnd();
+    }, [names]);
+    return null;
+  }
+  return definePlugin({
+    name: "pilotDevtools",
+    styles: "ghostykit",
+    aboveThread: Devtools,
+    ...events ? {
+      events: {
+        "*": (e, ctx) => {
+          const key = e.type === "CUSTOM" ? e.name : e.type;
+          const who = ctx.plugins.filter((p) => p.name !== "pilotDevtools" && (p.events?.[e.type] || key && (p.events?.[key] || p.message?.custom?.[key]))).map((p) => p.name);
+          console.debug(`[ghostykit] ${e.type}${e.type === "CUSTOM" ? ` ${e.name}` : ""}`, who.length ? `\u2192 ${who.join(", ")}` : "", e);
+        }
+      }
+    } : {}
+  });
+}
+export {
+  livePage,
+  modelPicker,
+  pilotDevtools
+};

package/dist/react/Bubble.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import { type TextBlock } from "../core/narration";
 import { type ReplyOptions } from "../core/options";
 import type { Turn, Usage } from "../core/types";
 export declare function UserBubble({ turn }: {
@@ -35,5 +36,14 @@ export interface AgentBubbleProps {
     showDuration?: boolean;
     /** Lo que la app quiera pintar bajo la respuesta (archivos, tarjetas propias). */
     renderDeliveries?: (turn: Turn, live: boolean) => ReactNode;
+    /** Vistas propias de las herramientas, justo bajo los pasos. */
+    renderTools?: (turn: Turn, live: boolean) => ReactNode;
+    /** Antes del texto de la respuesta, bajo sus pasos. */
+    renderBefore?: (turn: Turn, live: boolean) => ReactNode;
+    /** Bloques con nombre (```eb-file```) que salen del texto y se pintan como tarjetas bajo la respuesta. */
+    blocks?: {
+        langs: string[];
+        render: (blocks: TextBlock[], turn: Turn, live: boolean) => ReactNode;
+    };
 }
-export declare function AgentBubble({ turn, live, onRetry, onOption, showUsage, showCopy, showDuration, renderDeliveries }: AgentBubbleProps): import("react").JSX.Element;
+export declare function AgentBubble({ turn, live, onRetry, onOption, showUsage, showCopy, showDuration, renderDeliveries, renderTools, renderBefore, blocks }: AgentBubbleProps): import("react").JSX.Element;

package/dist/react/Composer.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import type { Attachment, Reference } from "../core/types";
 /** Un modelo que la app ofrece elegir (AG-UI no lo define: la app lo manda en `forwardedProps`). */
 export interface ModelOption {
@@ -10,6 +10,10 @@ export interface UploadResult {
     url: string;
     id?: string;
 }
+/** Lo que se puede hacer con la caja desde afuera (`ctx.addAttachments`). */
+export interface ComposerHandle {
+    addAttachments: (items: (File | Attachment)[]) => void;
+}
 /** El tipo del archivo, deducido del nombre cuando el navegador no lo dice (pasa más de lo que parece). */
 export declare function mimeOf(file: File): string;
 export interface ComposerProps {
@@ -36,12 +40,16 @@ export interface ComposerProps {
     references?: Reference[];
     onRemoveReference?: (id: string) => void;
     onActivateReference?: (ref: Reference) => void;
-    /** Botones propios junto a adjuntar (slot `composerExtras`). */
+    /** Botones propios entre la imagen y el clip. */
     extras?: ReactNode;
+    /** Botones propios después del clip. */
+    extrasEnd?: ReactNode;
+    /** Para agregar adjuntos desde afuera. */
+    handleRef?: Ref<ComposerHandle>;
     maxFiles?: number;
     maxFileMb?: number;
 }
-export declare function Composer({ onSubmit, onStop, busy, canSteer, placeholder, initialValue, autoFocus, canSeeImages, attachments: withFiles, upload, transcribe, voiceNoteText, models, currentModel, onModelChange, references, onRemoveReference, onActivateReference, extras, maxFiles, maxFileMb, }: ComposerProps): import("react").JSX.Element;
+export declare function Composer({ onSubmit, onStop, busy, canSteer, placeholder, initialValue, autoFocus, canSeeImages, attachments: withFiles, upload, transcribe, voiceNoteText, models, currentModel, onModelChange, references, onRemoveReference, onActivateReference, extras, extrasEnd, handleRef, maxFiles, maxFileMb, }: ComposerProps): import("react").JSX.Element;
 /**
  * El selector de modelo. PORTADO de Ghosty (`ModelPicker.tsx`): dropdown discreto hacia arriba, sin
  * Radix; cierra con clic fuera y con Escape.

package/dist/react/Piloto.d.ts

@@ -1,10 +1,8 @@
 import { type CSSProperties, type ReactNode } from "react";
-import { type ToolVerbs } from "../core/steps";
-import type { Attachment, Reference, Turn } from "../core/types";
+import type { Reference } from "../core/types";
 import type { PilotTransport } from "../transport";
-import { type UploadResult } from "./Composer";
-import { type MarkdownOptions, type PilotIcon, type PilotTheme } from "./context";
-import { type PilotStrings } from "./strings";
+import { type PilotTheme } from "./context";
+import { type PilotoPlugin, type PluginCtx } from "./plugins";
 import { type Pilot, type UsePilotOptions } from "./usePilot";
 export interface PilotoFeatures {
     /** Botones de adjuntar. Default: sí si hay `upload`. */
@@ -22,45 +20,22 @@ export interface PilotoFeatures {
     /** Mandar con el run vivo (steer). Default: lo que diga el agente en `state.caps.steer`. */
     steer?: boolean;
 }
-export interface PilotoSlots {
-    /** Lo que la app pinte bajo cada respuesta (archivos, tarjetas propias). */
-    renderDeliveries?: (turn: Turn, live: boolean) => ReactNode;
-    /** Botones propios en la barra del composer. */
-    composerExtras?: ReactNode;
-    /** Lo que se ve con el hilo vacío (en lugar del saludo de casa). */
-    emptyState?: ReactNode;
-    /** Arriba a la derecha, sobre el hilo (compartir, abrir en grande…). */
-    headerActions?: ReactNode;
-    /** Pegado arriba del composer (un aviso, un banner, `<Subagents pilot={pilot} />`). */
-    aboveComposer?: ReactNode | ((pilot: Pilot) => ReactNode);
-    /** Un panel junto al chat (subagentes, vista previa), con el estado del agente y el piloto. */
-    sidePanel?: (agentState: Record<string, unknown>, pilot: Pilot) => ReactNode;
-}
 export interface PilotoProps extends UsePilotOptions {
     transport: PilotTransport | null;
     /** Si la app ya usa `usePilot` (para leer el estado afuera), pásalo aquí. */
     pilot?: Pilot;
     agentName?: string;
     locale?: "es" | "en";
-    strings?: Partial<PilotStrings>;
     theme?: PilotTheme;
     /** La piel: `ghosty` (default), `easybits`, `neutral`, o el nombre de una propia (`[data-skin]`). */
     skin?: string;
     className?: string;
     style?: CSSProperties;
-    toolVerbs?: ToolVerbs;
-    toolIcons?: Record<string, PilotIcon>;
-    /** El texto del usuario como se pinta (quita la fontanería que la app pega al prompt). */
-    formatUserText?: (text: string) => string;
-    markdown?: MarkdownOptions;
     /** Saludo del hilo vacío. */
     welcome?: ReactNode;
     avatar?: ReactNode;
     placeholder?: string;
     suggestions?: string[];
-    upload?: (file: File) => Promise<UploadResult>;
-    transcribe?: (audio: Blob) => Promise<string>;
-    voiceNoteText?: (transcript: string) => string;
     features?: PilotoFeatures;
     /**
      * Una pregunta lista en la caja (sin mandarla) y el foco en ella: al abrir el piloto desde una
@@ -75,15 +50,16 @@ export interface PilotoProps extends UsePilotOptions {
     onReferencesChange?: (refs: Reference[]) => void;
     /** Clic en un chip de referencia (resaltar la tarjeta en la app). */
     onReferenceClick?: (ref: Reference) => void;
-    slots?: PilotoSlots;
-}
-/** Lo que la app puede hacer desde afuera (`<Piloto ref={…} />`). */
-export interface PilotoHandle {
-    send: (text: string, attachments?: Attachment[]) => void;
-    addReference: (ref: Reference) => void;
-    /** Escribe en la caja sin mandar. */
-    setDraft: (text: string) => void;
-    focus: () => void;
+    /**
+     * La ÚNICA forma de personalizar: textos, pasos, eventos, entregas, composer y paneles (ver
+     * `PilotoPlugin`). Créalos una vez (fuera del render o con `useMemo`).
+     */
+    plugins?: readonly PilotoPlugin[];
 }
+/**
+ * Lo que la app puede hacer desde afuera (`<Piloto ref={…} />`): lo MISMO que recibe un plugin en
+ * `ctx`. Con `pilot` (estado, `reconnect`, `stop`, `continueRun`…) nadie necesita `usePilot` aparte.
+ */
+export type PilotoHandle = Omit<PluginCtx, "plugins" | "strings" | "agentState">;
 export declare const Piloto: import("react").ForwardRefExoticComponent<PilotoProps & import("react").RefAttributes<PilotoHandle>>;
 export default Piloto;

package/dist/react/context.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentType } from "react";
 import { type ToolVerbs } from "../core/steps";
+import type { Turn } from "../core/types";
 import { type PilotStrings } from "./strings";
 /** Un ícono: cualquier componente que acepte `className` (los de lucide-react sirven tal cual). */
 export type PilotIcon = ComponentType<{
@@ -9,7 +10,7 @@ export type PilotTheme = "light" | "dark" | "auto";
 /** Ajustes del markdown de las respuestas. */
 export interface MarkdownOptions {
     /** Reescribe el markdown antes de pintarlo (p. ej. `#12` → `[#12](#folio-12)`). */
-    transform?: (md: string) => string;
+    transform?: (md: string, turn?: Turn) => string;
     /** Un clic en un enlace. Devuelve `true` si la app lo manejó (no se abre el aviso de salida). */
     onLinkClick?: (href: string, event: MouseEvent) => boolean;
 }
@@ -26,6 +27,8 @@ export interface PilotoConfig {
 }
 export declare const PilotoContext: import("react").Context<PilotoConfig>;
 export declare const usePiloto: () => PilotoConfig;
+/** La respuesta que se está pintando (para `markdown.transform(md, turn)`). */
+export declare const TurnContext: import("react").Context<Turn | undefined>;
 /** Las clases de la raíz: el alcance de los estilos y el tema. Lo usan también los portales. */
 export declare function rootProps(theme: PilotTheme, skin?: string): {
     className: string;

package/dist/react/index.d.ts

@@ -1,11 +1,12 @@
-export { Piloto, Piloto as default, type PilotoFeatures, type PilotoHandle, type PilotoProps, type PilotoSlots } from "./Piloto";
-export { toAgUiContext, usePilot, type Pilot, type SendOptions, type TurnDoneInfo, type UsePilotOptions } from "./usePilot";
+export { Piloto, Piloto as default, type PilotoFeatures, type PilotoHandle, type PilotoProps } from "./Piloto";
+export { definePlugin, pluginPoints, pluginRequires, resolvePlugins, type PilotoPlugin, type PluginCtx, type PluginEvent, type PluginView, type ResolvedPlugins, } from "./plugins";
+export { toAgUiContext, usePilot, type Pilot, type SendOptions, type TurnDoneInfo, type TurnEvent, type UsePilotOptions } from "./usePilot";
 export { AgentBubble, CopyUserMessage, ReplyOptionButtons, TurnFooter, UsageStats, UserBubble, type AgentBubbleProps } from "./Bubble";
 export { AgentSteps, ArcadeIcon, ClawIcon, DEFAULT_TOOL_ICONS, Narration, RobotArmIcon, ToolRow } from "./Steps";
 export { LinkSafetyModal, Markdown } from "./Markdown";
 export { InlineMarkdown, renderInline } from "./InlineMarkdown";
 export { useTextAtPace } from "./TextAtPace";
-export { Composer, ModelPicker, mimeOf, type ComposerProps, type ModelOption, type UploadResult } from "./Composer";
+export { Composer, ModelPicker, mimeOf, type ComposerHandle, type ComposerProps, type ModelOption, type UploadResult } from "./Composer";
 export { ConfirmCard, DecisionLines } from "./ConfirmCard";
 export { ReferenceChips, Suggestions } from "./Chips";
 export { TypingDots, WaitLabel } from "./Status";