@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/chat/words.js

@@ -0,0 +1,460 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The chat's own words in the person's language (LOOP P-26): the composer's
+ * placeholder and buttons, its error sentences, the tool lines and the tool
+ * cards, the approvals, and the assistant's balloon — said in the six
+ * languages the application's composer is said in (`interfaceWords`).
+ *
+ * The chat reads them in the language its host says (`ChatLanguage`, which
+ * `AppRenderer` and the embed set from their `language`), else in the first
+ * the browser prefers that is here, else in English: as an application's own
+ * words are picked (`loop/apps/language`).
+ *
+ * Pure: no React ({@link useChatWords} is in `ChatLanguage`).
+ *
+ * @module chat/words
+ */
+import { pickLanguage } from '../loop/apps/language';
+/** The chat's words, by language. Another language reads English. */
+export const CHAT_WORDS = {
+    en: {
+        placeholder: 'Ask anything, type / for commands or @ for mention',
+        typeMessage: 'Type a message...',
+        messageInput: 'Message input',
+        send: 'Send',
+        stop: 'Stop',
+        pauseKernelBusy: 'Pause (kernel busy)',
+        suggestedPrompts: 'Suggested prompts',
+        demoKeyExpired: 'This demo runs on a shared key, and its time is up. Sign in to keep going.',
+        keyExpired: 'Your key has expired. Sign in to keep going.',
+        startConversation: 'Start a conversation',
+        sendToBegin: 'Send a message to begin chatting',
+        copyTurn: 'Copy this turn',
+        removeTurn: 'Remove this turn',
+        error: message => `Error: ${message}`,
+        thinking: 'Thinking…',
+        toolPreparing: 'Preparing...',
+        toolExecuting: 'Executing...',
+        toolComplete: 'Complete',
+        toolExecutionFailed: 'Execution Failed',
+        toolCodeError: 'Code Error',
+        toolExited: 'Exited',
+        toolFailed: 'Failed',
+        awaitingApproval: 'Awaiting Approval',
+        noParameters: 'No parameters',
+        moreArguments: count => `(+${count} more)`,
+        parameters: 'Parameters',
+        result: 'Result',
+        executionError: 'Execution Error',
+        executionErrorWhy: 'The sandbox or execution environment failed to run the code.',
+        errorHeading: 'Error',
+        processExited: 'Process Exited',
+        exitedWithCode: code => `Process exited with code ${code}`,
+        nonZeroExit: 'The code called sys.exit() with a non-zero exit code.',
+        toolRunning: { before: 'Using ', after: '…' },
+        toolDone: { before: 'Done: ', after: '' },
+        toolFailedLine: { before: '', after: ' failed' },
+        approve: 'Approve',
+        deny: 'Deny',
+        approveAll: 'Approve all',
+        approvalNeeded: 'This tool requires your approval to run.',
+        approvedRunning: 'Approved. Executing tool.',
+        approvedElsewhere: 'Approved from sidebar.',
+        deniedWontRun: 'Denied. Tool will not run.',
+        decidedElsewhere: 'Decision came from sidebar.',
+        approvalsPending: count => `${count} tool ${count === 1 ? 'approval' : 'approvals'} pending`,
+        toolApprovalsPending: 'Tool approvals pending',
+        collapse: 'Collapse',
+        review: 'Review',
+        dismiss: 'Dismiss',
+        approvalTitle: 'Tool Approval Required',
+        arguments: 'Arguments:',
+        approvalWarning: 'This tool will perform an action on your behalf. Please review the arguments before approving.',
+        rememberChoice: 'Remember my choice for this tool',
+        waitingOpen: 'Waiting for you — open the conversation to answer.',
+        waitingForYou: 'Waiting for you',
+        paused: 'Paused — it answers again once it is resumed.',
+        moreWaiting: count => `${count} more`,
+        showMore: 'more',
+        showLess: 'less',
+        now: 'Now',
+        conversation: 'Conversation',
+        suggestions: 'Suggestions',
+        expandConversation: 'Expand the conversation',
+        expand: 'Expand',
+        expandWhat: what => `Expand ${what}`,
+        theVisual: 'the visual',
+        talkTo: name => `Talk to ${name}`,
+    },
+    fr: {
+        placeholder: 'Demandez ce que vous voulez, tapez / pour les commandes ou @ pour mentionner',
+        typeMessage: 'Écrivez un message...',
+        messageInput: 'Saisie du message',
+        send: 'Envoyer',
+        stop: 'Arrêter',
+        pauseKernelBusy: 'Pause (noyau occupé)',
+        suggestedPrompts: 'Suggestions de questions',
+        demoKeyExpired: 'Cette démo utilise une clé partagée, et son temps est écoulé. Connectez-vous pour continuer.',
+        keyExpired: 'Votre clé a expiré. Connectez-vous pour continuer.',
+        startConversation: 'Commencer une conversation',
+        sendToBegin: 'Envoyez un message pour commencer',
+        copyTurn: 'Copier cet échange',
+        removeTurn: 'Supprimer cet échange',
+        error: message => `Erreur : ${message}`,
+        thinking: 'Réflexion…',
+        toolPreparing: 'Préparation...',
+        toolExecuting: 'Exécution...',
+        toolComplete: 'Terminé',
+        toolExecutionFailed: 'Échec de l’exécution',
+        toolCodeError: 'Erreur dans le code',
+        toolExited: 'Arrêté',
+        toolFailed: 'Échec',
+        awaitingApproval: 'En attente d’approbation',
+        noParameters: 'Aucun paramètre',
+        moreArguments: count => `(+${count} de plus)`,
+        parameters: 'Paramètres',
+        result: 'Résultat',
+        executionError: 'Erreur d’exécution',
+        executionErrorWhy: 'Le bac à sable ou l’environnement d’exécution n’a pas pu exécuter le code.',
+        errorHeading: 'Erreur',
+        processExited: 'Processus arrêté',
+        exitedWithCode: code => `Le processus s’est arrêté avec le code ${code}`,
+        nonZeroExit: 'Le code a appelé sys.exit() avec un code de sortie non nul.',
+        toolRunning: { before: 'Utilise ', after: '…' },
+        toolDone: { before: 'Terminé : ', after: '' },
+        toolFailedLine: { before: '', after: ' a échoué' },
+        approve: 'Approuver',
+        deny: 'Refuser',
+        approveAll: 'Tout approuver',
+        approvalNeeded: 'Cet outil a besoin de votre approbation pour s’exécuter.',
+        approvedRunning: 'Approuvé. Exécution de l’outil.',
+        approvedElsewhere: 'Approuvé depuis le panneau latéral.',
+        deniedWontRun: 'Refusé. L’outil ne s’exécutera pas.',
+        decidedElsewhere: 'Décision prise depuis le panneau latéral.',
+        approvalsPending: count => count === 1
+            ? '1 approbation d’outil en attente'
+            : `${count} approbations d’outil en attente`,
+        toolApprovalsPending: 'Approbations d’outil en attente',
+        collapse: 'Réduire',
+        review: 'Examiner',
+        dismiss: 'Fermer',
+        approvalTitle: 'Approbation d’outil requise',
+        arguments: 'Arguments :',
+        approvalWarning: 'Cet outil va agir en votre nom. Vérifiez ses arguments avant de l’approuver.',
+        rememberChoice: 'Mémoriser mon choix pour cet outil',
+        waitingOpen: 'Il vous attend — ouvrez la conversation pour répondre.',
+        waitingForYou: 'Il vous attend',
+        paused: 'En pause — il répondra de nouveau une fois relancé.',
+        moreWaiting: count => `${count} de plus`,
+        showMore: 'plus',
+        showLess: 'moins',
+        now: 'Maintenant',
+        conversation: 'Conversation',
+        suggestions: 'Suggestions',
+        expandConversation: 'Agrandir la conversation',
+        expand: 'Agrandir',
+        expandWhat: what => `Agrandir ${what}`,
+        theVisual: 'le visuel',
+        talkTo: name => `Parler à ${name}`,
+    },
+    es: {
+        placeholder: 'Pregunta lo que quieras, escribe / para comandos o @ para mencionar',
+        typeMessage: 'Escribe un mensaje...',
+        messageInput: 'Entrada del mensaje',
+        send: 'Enviar',
+        stop: 'Detener',
+        pauseKernelBusy: 'Pausa (kernel ocupado)',
+        suggestedPrompts: 'Preguntas sugeridas',
+        demoKeyExpired: 'Esta demo usa una clave compartida y su tiempo se ha agotado. Inicia sesión para continuar.',
+        keyExpired: 'Tu clave ha caducado. Inicia sesión para continuar.',
+        startConversation: 'Empieza una conversación',
+        sendToBegin: 'Envía un mensaje para empezar',
+        copyTurn: 'Copiar este turno',
+        removeTurn: 'Eliminar este turno',
+        error: message => `Error: ${message}`,
+        thinking: 'Pensando…',
+        toolPreparing: 'Preparando...',
+        toolExecuting: 'Ejecutando...',
+        toolComplete: 'Completado',
+        toolExecutionFailed: 'Falló la ejecución',
+        toolCodeError: 'Error en el código',
+        toolExited: 'Terminado',
+        toolFailed: 'Falló',
+        awaitingApproval: 'Esperando aprobación',
+        noParameters: 'Sin parámetros',
+        moreArguments: count => `(+${count} más)`,
+        parameters: 'Parámetros',
+        result: 'Resultado',
+        executionError: 'Error de ejecución',
+        executionErrorWhy: 'El sandbox o el entorno de ejecución no pudo ejecutar el código.',
+        errorHeading: 'Error',
+        processExited: 'Proceso terminado',
+        exitedWithCode: code => `El proceso terminó con el código ${code}`,
+        nonZeroExit: 'El código llamó a sys.exit() con un código de salida distinto de cero.',
+        toolRunning: { before: 'Usando ', after: '…' },
+        toolDone: { before: 'Hecho: ', after: '' },
+        toolFailedLine: { before: '', after: ' falló' },
+        approve: 'Aprobar',
+        deny: 'Rechazar',
+        approveAll: 'Aprobar todo',
+        approvalNeeded: 'Esta herramienta necesita tu aprobación para ejecutarse.',
+        approvedRunning: 'Aprobado. Ejecutando la herramienta.',
+        approvedElsewhere: 'Aprobado desde el panel lateral.',
+        deniedWontRun: 'Rechazado. La herramienta no se ejecutará.',
+        decidedElsewhere: 'Decisión tomada desde el panel lateral.',
+        approvalsPending: count => count === 1
+            ? '1 aprobación de herramienta pendiente'
+            : `${count} aprobaciones de herramientas pendientes`,
+        toolApprovalsPending: 'Aprobaciones de herramientas pendientes',
+        collapse: 'Contraer',
+        review: 'Revisar',
+        dismiss: 'Cerrar',
+        approvalTitle: 'Se necesita aprobar la herramienta',
+        arguments: 'Argumentos:',
+        approvalWarning: 'Esta herramienta actuará en tu nombre. Revisa sus argumentos antes de aprobarla.',
+        rememberChoice: 'Recordar mi elección para esta herramienta',
+        waitingOpen: 'Te está esperando: abre la conversación para responder.',
+        waitingForYou: 'Te está esperando',
+        paused: 'En pausa: responderá de nuevo cuando se reanude.',
+        moreWaiting: count => `${count} más`,
+        showMore: 'más',
+        showLess: 'menos',
+        now: 'Ahora',
+        conversation: 'Conversación',
+        suggestions: 'Sugerencias',
+        expandConversation: 'Ampliar la conversación',
+        expand: 'Ampliar',
+        expandWhat: what => `Ampliar ${what}`,
+        theVisual: 'el visual',
+        talkTo: name => `Hablar con ${name}`,
+    },
+    de: {
+        placeholder: 'Frag, was du willst – / für Befehle, @ zum Erwähnen',
+        typeMessage: 'Nachricht schreiben...',
+        messageInput: 'Nachrichteneingabe',
+        send: 'Senden',
+        stop: 'Stoppen',
+        pauseKernelBusy: 'Pause (Kernel beschäftigt)',
+        suggestedPrompts: 'Vorgeschlagene Fragen',
+        demoKeyExpired: 'Diese Demo läuft mit einem geteilten Schlüssel, und ihre Zeit ist abgelaufen. Melde dich an, um weiterzumachen.',
+        keyExpired: 'Dein Schlüssel ist abgelaufen. Melde dich an, um weiterzumachen.',
+        startConversation: 'Ein Gespräch beginnen',
+        sendToBegin: 'Sende eine Nachricht, um zu beginnen',
+        copyTurn: 'Diesen Austausch kopieren',
+        removeTurn: 'Diesen Austausch entfernen',
+        error: message => `Fehler: ${message}`,
+        thinking: 'Denkt nach…',
+        toolPreparing: 'Wird vorbereitet...',
+        toolExecuting: 'Wird ausgeführt...',
+        toolComplete: 'Fertig',
+        toolExecutionFailed: 'Ausführung fehlgeschlagen',
+        toolCodeError: 'Fehler im Code',
+        toolExited: 'Beendet',
+        toolFailed: 'Fehlgeschlagen',
+        awaitingApproval: 'Wartet auf Freigabe',
+        noParameters: 'Keine Parameter',
+        moreArguments: count => `(+${count} weitere)`,
+        parameters: 'Parameter',
+        result: 'Ergebnis',
+        executionError: 'Ausführungsfehler',
+        executionErrorWhy: 'Die Sandbox oder die Ausführungsumgebung konnte den Code nicht ausführen.',
+        errorHeading: 'Fehler',
+        processExited: 'Prozess beendet',
+        exitedWithCode: code => `Der Prozess wurde mit Code ${code} beendet`,
+        nonZeroExit: 'Der Code hat sys.exit() mit einem Exit-Code ungleich null aufgerufen.',
+        toolRunning: { before: 'Verwendet ', after: '…' },
+        toolDone: { before: 'Fertig: ', after: '' },
+        toolFailedLine: { before: '', after: ' fehlgeschlagen' },
+        approve: 'Freigeben',
+        deny: 'Ablehnen',
+        approveAll: 'Alle freigeben',
+        approvalNeeded: 'Dieses Werkzeug braucht deine Freigabe, um zu laufen.',
+        approvedRunning: 'Freigegeben. Das Werkzeug wird ausgeführt.',
+        approvedElsewhere: 'In der Seitenleiste freigegeben.',
+        deniedWontRun: 'Abgelehnt. Das Werkzeug wird nicht ausgeführt.',
+        decidedElsewhere: 'In der Seitenleiste entschieden.',
+        approvalsPending: count => count === 1
+            ? '1 Werkzeugfreigabe ausstehend'
+            : `${count} Werkzeugfreigaben ausstehend`,
+        toolApprovalsPending: 'Werkzeugfreigaben ausstehend',
+        collapse: 'Einklappen',
+        review: 'Prüfen',
+        dismiss: 'Schließen',
+        approvalTitle: 'Werkzeugfreigabe erforderlich',
+        arguments: 'Argumente:',
+        approvalWarning: 'Dieses Werkzeug handelt in deinem Namen. Prüfe seine Argumente, bevor du es freigibst.',
+        rememberChoice: 'Meine Wahl für dieses Werkzeug merken',
+        waitingOpen: 'Wartet auf dich – öffne das Gespräch, um zu antworten.',
+        waitingForYou: 'Wartet auf dich',
+        paused: 'Pausiert – antwortet wieder, sobald es fortgesetzt wird.',
+        moreWaiting: count => `${count} weitere`,
+        showMore: 'mehr',
+        showLess: 'weniger',
+        now: 'Jetzt',
+        conversation: 'Gespräch',
+        suggestions: 'Vorschläge',
+        expandConversation: 'Gespräch vergrößern',
+        expand: 'Vergrößern',
+        expandWhat: what => `${what} vergrößern`,
+        theVisual: 'die Darstellung',
+        talkTo: name => `Mit ${name} sprechen`,
+    },
+    it: {
+        placeholder: 'Chiedi quello che vuoi, digita / per i comandi o @ per menzionare',
+        typeMessage: 'Scrivi un messaggio...',
+        messageInput: 'Campo del messaggio',
+        send: 'Invia',
+        stop: 'Interrompi',
+        pauseKernelBusy: 'Pausa (kernel occupato)',
+        suggestedPrompts: 'Domande suggerite',
+        demoKeyExpired: 'Questa demo usa una chiave condivisa e il suo tempo è scaduto. Accedi per continuare.',
+        keyExpired: 'La tua chiave è scaduta. Accedi per continuare.',
+        startConversation: 'Inizia una conversazione',
+        sendToBegin: 'Invia un messaggio per iniziare',
+        copyTurn: 'Copia questo scambio',
+        removeTurn: 'Rimuovi questo scambio',
+        error: message => `Errore: ${message}`,
+        thinking: 'Sta pensando…',
+        toolPreparing: 'Preparazione...',
+        toolExecuting: 'Esecuzione...',
+        toolComplete: 'Completato',
+        toolExecutionFailed: 'Esecuzione non riuscita',
+        toolCodeError: 'Errore nel codice',
+        toolExited: 'Terminato',
+        toolFailed: 'Non riuscito',
+        awaitingApproval: 'In attesa di approvazione',
+        noParameters: 'Nessun parametro',
+        moreArguments: count => `(+${count} altri)`,
+        parameters: 'Parametri',
+        result: 'Risultato',
+        executionError: 'Errore di esecuzione',
+        executionErrorWhy: 'La sandbox o l’ambiente di esecuzione non è riuscito a eseguire il codice.',
+        errorHeading: 'Errore',
+        processExited: 'Processo terminato',
+        exitedWithCode: code => `Il processo è terminato con il codice ${code}`,
+        nonZeroExit: 'Il codice ha chiamato sys.exit() con un codice di uscita diverso da zero.',
+        toolRunning: { before: 'Usa ', after: '…' },
+        toolDone: { before: 'Fatto: ', after: '' },
+        toolFailedLine: { before: '', after: ' non riuscito' },
+        approve: 'Approva',
+        deny: 'Rifiuta',
+        approveAll: 'Approva tutto',
+        approvalNeeded: 'Questo strumento ha bisogno della tua approvazione per essere eseguito.',
+        approvedRunning: 'Approvato. Esecuzione dello strumento.',
+        approvedElsewhere: 'Approvato dal pannello laterale.',
+        deniedWontRun: 'Rifiutato. Lo strumento non verrà eseguito.',
+        decidedElsewhere: 'Decisione presa dal pannello laterale.',
+        approvalsPending: count => count === 1
+            ? '1 approvazione di strumento in attesa'
+            : `${count} approvazioni di strumenti in attesa`,
+        toolApprovalsPending: 'Approvazioni di strumenti in attesa',
+        collapse: 'Comprimi',
+        review: 'Esamina',
+        dismiss: 'Chiudi',
+        approvalTitle: 'Approvazione dello strumento richiesta',
+        arguments: 'Argomenti:',
+        approvalWarning: 'Questo strumento agirà per tuo conto. Controlla i suoi argomenti prima di approvarlo.',
+        rememberChoice: 'Ricorda la mia scelta per questo strumento',
+        waitingOpen: 'Ti sta aspettando: apri la conversazione per rispondere.',
+        waitingForYou: 'Ti sta aspettando',
+        paused: 'In pausa: risponderà di nuovo quando verrà ripreso.',
+        moreWaiting: count => `altri ${count}`,
+        showMore: 'altro',
+        showLess: 'meno',
+        now: 'Ora',
+        conversation: 'Conversazione',
+        suggestions: 'Suggerimenti',
+        expandConversation: 'Espandi la conversazione',
+        expand: 'Espandi',
+        expandWhat: what => `Espandi ${what}`,
+        theVisual: 'la visualizzazione',
+        talkTo: name => `Parla con ${name}`,
+    },
+    pt: {
+        placeholder: 'Pergunte o que quiser, digite / para comandos ou @ para mencionar',
+        typeMessage: 'Escreva uma mensagem...',
+        messageInput: 'Campo da mensagem',
+        send: 'Enviar',
+        stop: 'Parar',
+        pauseKernelBusy: 'Pausar (kernel ocupado)',
+        suggestedPrompts: 'Perguntas sugeridas',
+        demoKeyExpired: 'Esta demonstração usa uma chave compartilhada e o tempo dela acabou. Entre para continuar.',
+        keyExpired: 'Sua chave expirou. Entre para continuar.',
+        startConversation: 'Comece uma conversa',
+        sendToBegin: 'Envie uma mensagem para começar',
+        copyTurn: 'Copiar esta troca',
+        removeTurn: 'Remover esta troca',
+        error: message => `Erro: ${message}`,
+        thinking: 'Pensando…',
+        toolPreparing: 'Preparando...',
+        toolExecuting: 'Executando...',
+        toolComplete: 'Concluído',
+        toolExecutionFailed: 'Falha na execução',
+        toolCodeError: 'Erro no código',
+        toolExited: 'Encerrado',
+        toolFailed: 'Falhou',
+        awaitingApproval: 'Aguardando aprovação',
+        noParameters: 'Sem parâmetros',
+        moreArguments: count => `(+${count} mais)`,
+        parameters: 'Parâmetros',
+        result: 'Resultado',
+        executionError: 'Erro de execução',
+        executionErrorWhy: 'O sandbox ou o ambiente de execução não conseguiu executar o código.',
+        errorHeading: 'Erro',
+        processExited: 'Processo encerrado',
+        exitedWithCode: code => `O processo terminou com o código ${code}`,
+        nonZeroExit: 'O código chamou sys.exit() com um código de saída diferente de zero.',
+        toolRunning: { before: 'Usando ', after: '…' },
+        toolDone: { before: 'Concluído: ', after: '' },
+        toolFailedLine: { before: '', after: ' falhou' },
+        approve: 'Aprovar',
+        deny: 'Recusar',
+        approveAll: 'Aprovar tudo',
+        approvalNeeded: 'Esta ferramenta precisa da sua aprovação para ser executada.',
+        approvedRunning: 'Aprovado. Executando a ferramenta.',
+        approvedElsewhere: 'Aprovado pelo painel lateral.',
+        deniedWontRun: 'Recusado. A ferramenta não será executada.',
+        decidedElsewhere: 'Decisão tomada pelo painel lateral.',
+        approvalsPending: count => count === 1
+            ? '1 aprovação de ferramenta pendente'
+            : `${count} aprovações de ferramentas pendentes`,
+        toolApprovalsPending: 'Aprovações de ferramentas pendentes',
+        collapse: 'Recolher',
+        review: 'Revisar',
+        dismiss: 'Fechar',
+        approvalTitle: 'Aprovação da ferramenta necessária',
+        arguments: 'Argumentos:',
+        approvalWarning: 'Esta ferramenta vai agir em seu nome. Revise os argumentos antes de aprovar.',
+        rememberChoice: 'Lembrar minha escolha para esta ferramenta',
+        waitingOpen: 'Esperando por você — abra a conversa para responder.',
+        waitingForYou: 'Esperando por você',
+        paused: 'Em pausa — volta a responder quando for retomado.',
+        moreWaiting: count => `mais ${count}`,
+        showMore: 'mais',
+        showLess: 'menos',
+        now: 'Agora',
+        conversation: 'Conversa',
+        suggestions: 'Sugestões',
+        expandConversation: 'Ampliar a conversa',
+        expand: 'Ampliar',
+        expandWhat: what => `Ampliar ${what}`,
+        theVisual: 'o visual',
+        talkTo: name => `Falar com ${name}`,
+    },
+};
+/** The English words: what the chat says when nothing says a language. */
+export const ENGLISH_CHAT_WORDS = CHAT_WORDS.en;
+/**
+ * The language the chat speaks to a person who prefers these, as BCP 47
+ * tags them: the first it is said in (`fr-CA` reads `fr`), else English.
+ */
+export function chatLanguage(preferred) {
+    return pickLanguage(Object.keys(CHAT_WORDS), preferred) ?? 'en';
+}
+/** The chat's words in a language: its own, else its language's, else English. */
+export function chatWords(language) {
+    return CHAT_WORDS[chatLanguage(language ? [language] : [])];
+}

package/lib/components/a2ui/custom/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Components an application's developer wrote, drawn (LOOP P-17): an A2UI
+ * component of that application only, made as Datalayer's own are — its
+ * schema from its declaration (`componentSchemaOf`), its view by A2UI's own
+ * factory — so that it binds and acts as a Table does, and drawn in a
+ * sandboxed frame of no origin (`./sandbox`): its properties and what it
+ * shows go in, what it sends comes out, written where its binding points and
+ * then its action dispatched.
+ *
+ * Never global: `customImplementations(app)` is handed to the catalog of
+ * that application's page (`catalogOfBlocks`), and to no other.
+ *
+ * @module components/a2ui/custom
+ */
+import type { JSX } from 'react';
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import type { AppCustomComponentSpec, AppSpec } from '../../../types/agentspecs';
+type CustomProps = Record<string, unknown> & {
+    action?: () => void;
+    weight?: number;
+};
+/** What the frame is given: its declared properties and what it shows, nothing else. */
+export declare function givenToFrame(component: AppCustomComponentSpec, props: Record<string, unknown>): Record<string, unknown>;
+/** A component its developer wrote, in its frame. */
+export declare function CustomComponentView({ component, props, fetcher, }: {
+    component: AppCustomComponentSpec;
+    props: CustomProps;
+    /** How its module is fetched; the page's `fetch` unless given (tests). */
+    fetcher?: typeof fetch;
+}): JSX.Element;
+/**
+ * A component its developer wrote as A2UI's renderer registers one: its
+ * schema from its declaration, its view by A2UI's own factory, drawn in its
+ * frame.
+ */
+export declare function customImplementation(component: AppCustomComponentSpec, version?: string, fetcher?: typeof fetch): ReactComponentImplementation;
+/** The renderers of the components an application's developer wrote, for its page alone. */
+export declare function customImplementations(app: Pick<AppSpec, 'interface' | 'version'>, fetcher?: typeof fetch): ReactComponentImplementation[];
+export { CUSTOM_FRAME_SANDBOX, customFrameDocument, customFramePolicy, customModule, fromFrame, integrityHolds, } from './sandbox';

package/lib/components/a2ui/custom/index.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { createComponentImplementation, } from '@a2ui/react/v0_9';
+import { customComponentEntry } from '../../../loop/apps/customComponents';
+import { componentSchemaOf } from '../datalayer/schema';
+import { BlockFrame, Problem } from '../datalayer/parts';
+import { CUSTOM_FRAME_SANDBOX, FRAME_TAG, customFrameDocument, customModule, frameNonce, fromFrame, } from './sandbox';
+/** What the frame is given: its declared properties and what it shows, nothing else. */
+export function givenToFrame(component, props) {
+    const declared = Object.keys((component.props.properties ?? {}));
+    const names = new Set([...declared, ...component.shows, ...component.sends]);
+    return Object.fromEntries(Object.entries(props).filter(([name, value]) => names.has(name) && typeof value !== 'function'));
+}
+/** The setter A2UI gives a binding: `setValue` for `value`. */
+const setterOf = (name) => `set${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+/** A component its developer wrote, in its frame. */
+export function CustomComponentView({ component, props, fetcher, }) {
+    const frame = useRef(null);
+    const [problem, setProblem] = useState(null);
+    const [ready, setReady] = useState(false);
+    const srcDoc = useMemo(() => customFrameDocument(frameNonce(), component.name), [component.name]);
+    // What it is given, told again only when a value of it changes.
+    const givenKey = JSON.stringify(givenToFrame(component, props));
+    const given = useMemo(() => JSON.parse(givenKey), [givenKey]);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const tell = (message) => frame.current?.contentWindow?.postMessage(message, '*');
+    useEffect(() => {
+        const listen = (event) => {
+            const said = fromFrame(event, frame.current?.contentWindow);
+            if (!said) {
+                return;
+            }
+            if (said.kind === 'ready') {
+                customModule(component.source, component.integrity, fetcher)
+                    .then(code => {
+                    tell({
+                        tag: FRAME_TAG,
+                        kind: 'props',
+                        props: givenToFrame(component, propsRef.current),
+                    });
+                    tell({ tag: FRAME_TAG, kind: 'module', code });
+                    setReady(true);
+                })
+                    .catch((error) => setProblem(error instanceof Error ? error.message : String(error)));
+            }
+            else if (said.kind === 'failed') {
+                setProblem(`It could not be drawn: ${said.message}.`);
+            }
+            else if (said.kind === 'send') {
+                // What it sends is what it declares, and nothing else.
+                if (!component.sends.includes(said.name)) {
+                    setProblem(`It sent “${said.name}”, which it does not declare under \`sends\`.`);
+                    return;
+                }
+                const set = propsRef.current[setterOf(said.name)];
+                if (typeof set === 'function') {
+                    set(said.value);
+                }
+                propsRef.current.action?.();
+            }
+        };
+        window.addEventListener('message', listen);
+        return () => window.removeEventListener('message', listen);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [component, fetcher]);
+    useEffect(() => {
+        if (ready) {
+            tell({ tag: FRAME_TAG, kind: 'props', props: given });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [ready, given]);
+    return (_jsxs(BlockFrame, { label: component.description || component.name, weight: props.weight, testId: `custom-${component.name}`, children: [problem ? _jsx(Problem, { children: problem }) : null, _jsx("iframe", { ref: frame, title: component.description || component.name, sandbox: CUSTOM_FRAME_SANDBOX, srcDoc: srcDoc, referrerPolicy: "no-referrer", style: {
+                    width: '100%',
+                    height: `${component.height}px`,
+                    border: 0,
+                    display: 'block',
+                } })] }));
+}
+/**
+ * A component its developer wrote as A2UI's renderer registers one: its
+ * schema from its declaration, its view by A2UI's own factory, drawn in its
+ * frame.
+ */
+export function customImplementation(component, version = '0.0.0', fetcher) {
+    const entry = customComponentEntry(component, version);
+    const api = { name: component.name, schema: componentSchemaOf(entry) };
+    const Render = ({ props }) => (_jsx(CustomComponentView, { component: component, props: props, fetcher: fetcher }));
+    return createComponentImplementation(api, Render);
+}
+/** The renderers of the components an application's developer wrote, for its page alone. */
+export function customImplementations(app, fetcher) {
+    return (app.interface.customComponents ?? []).map(component => customImplementation(component, app.version, fetcher));
+}
+export { CUSTOM_FRAME_SANDBOX, customFrameDocument, customFramePolicy, customModule, fromFrame, integrityHolds, } from './sandbox';

package/lib/components/a2ui/custom/sandbox.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The frame a component its developer wrote is drawn in (LOOP P-17), and
+ * what passes between it and the page.
+ *
+ * A hosted application lives on the origin where people are signed in, and
+ * no script an application supplies reaches that page (LOOP D-22). A custom
+ * component's module is such a script, so it never runs in the page: it runs
+ * in an `<iframe sandbox="allow-scripts">` — no `allow-same-origin`, so the
+ * frame has an origin of its own that is no one's: no cookie, no storage, no
+ * access to the page, its DOM or its tokens — whose document allows nothing
+ * but its own bootstrap and the module it is handed (`default-src 'none'`):
+ * no request leaves the frame, no form, no navigation of the page.
+ *
+ * The page fetches the module — without credentials — checks it against the
+ * hash it was reviewed with when the spec gives one (`integrity`), and hands
+ * its text to the frame, which imports it from a `blob:` address. Its
+ * default export draws it: `export default function (root, {props, send})`,
+ * returning `{update(props)}` to be told of new properties. What it is given
+ * is its properties and what it shows; what it gives back is what it sends,
+ * by name, each refused unless declared.
+ *
+ * @module components/a2ui/custom/sandbox
+ */
+/** What the frame of a custom component may do: run scripts, nothing else. */
+export declare const CUSTOM_FRAME_SANDBOX = "allow-scripts";
+/** The largest module the page hands to a frame, in bytes. */
+export declare const MAX_MODULE_BYTES: number;
+/** The tag every message between the page and a frame carries. */
+export declare const FRAME_TAG = "loop.component";
+/** What the page tells the frame. */
+export type ToFrame = {
+    tag: typeof FRAME_TAG;
+    kind: 'module';
+    code: string;
+} | {
+    tag: typeof FRAME_TAG;
+    kind: 'props';
+    props: Record<string, unknown>;
+};
+/** What the frame tells the page. */
+export type FromFrame = {
+    kind: 'ready';
+} | {
+    kind: 'drawn';
+} | {
+    kind: 'failed';
+    message: string;
+} | {
+    kind: 'send';
+    name: string;
+    value: unknown;
+};
+/** The policy of the frame's document: its bootstrap, the module it is handed, nothing else. */
+export declare function customFramePolicy(nonce: string): string;
+/** A nonce for one frame's bootstrap. */
+export declare function frameNonce(): string;
+/**
+ * The document of a custom component's frame (its `srcdoc`): the policy,
+ * the root it draws into, and the bootstrap that imports the module it is
+ * handed and passes properties in and what it sends out.
+ */
+export declare function customFrameDocument(nonce: string, label: string): string;
+/** What a frame said, when it is a message of the frame drawn here; null otherwise. */
+export declare function fromFrame(event: Pick<MessageEvent, 'source' | 'data'>, frame: Window | null | undefined): FromFrame | null;
+/** Whether a module's bytes are the ones its Subresource Integrity hash names. */
+export declare function integrityHolds(bytes: ArrayBuffer, integrity: string): Promise<boolean>;
+/**
+ * The text of a custom component's module, fetched without credentials and
+ * checked against its hash when one is given. It throws, with a sentence,
+ * for a module that cannot be fetched, is too large, or is not the one
+ * reviewed.
+ */
+export declare function customModule(source: string, integrity: string, fetcher?: typeof fetch): Promise<string>;