@datalayer/agent-runtimes 1.3.82 → 1.3.84

package/lib/loop/apps/uploads.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The largest file a person may send an application, in megabytes. */
+export const MAX_UPLOAD_MB = 25;
+/** What a kind takes when it does not say, in megabytes. */
+export const DEFAULT_UPLOAD_MB = 10;
+/** How many files go with one message when it does not say. */
+export const DEFAULT_MAX_FILES = 5;
+/** A media type, a family of them, or an extension, lowercase. */
+export const UPLOAD_KIND = /^(?:[a-z0-9][a-z0-9.+-]*\/(?:\*|[a-z0-9][a-z0-9.+-]*)|\.[a-z0-9][a-z0-9_+-]*)$/;
+/**
+ * Whether a kind of file takes a file: an extension (`.csv`) by its name, a
+ * media type (`application/pdf`) or a family (`image/*`) by its type.
+ */
+export function kindTakes(kind, file) {
+    const wanted = kind.trim().toLowerCase();
+    if (wanted.startsWith('.')) {
+        return file.name.toLowerCase().endsWith(wanted);
+    }
+    const type = (file.type || '').split(';', 1)[0].trim().toLowerCase();
+    if (wanted.endsWith('/*')) {
+        return type.startsWith(wanted.slice(0, -1));
+    }
+    return type === wanted;
+}
+/** Whether any of `kinds` takes a file; any file when there are none. */
+export const acceptsFile = (kinds, file) => !kinds?.length || kinds.some(kind => kindTakes(kind, file));
+const megabytes = (size) => `${(size / (1024 * 1024)).toFixed(1)} MB`;
+/** The `accept` of a file input for what the application takes. */
+export const uploadsAccept = (uploads) => uploads.kinds.map(kind => kind.type).join(',');
+/**
+ * Why files sent without being asked are refused, in a sentence — the
+ * runtime's — or `null` when the application takes every one of them.
+ */
+export function uploadsRefusal(app, files) {
+    if (files.length === 0) {
+        return null;
+    }
+    const uploads = app.interface.uploads;
+    if (!uploads) {
+        return `${app.name} takes no file sent with a message: its Appspec names none it takes (interface.uploads).`;
+    }
+    if (files.length > uploads.maxFiles) {
+        return `${files.length} files were sent at once: ${app.name} takes at most ${uploads.maxFiles}.`;
+    }
+    for (const file of files) {
+        const kind = uploads.kinds.find(candidate => kindTakes(candidate.type, file));
+        if (!kind) {
+            const taken = uploads.kinds.map(candidate => candidate.type).join(', ');
+            return `${file.name} is not a kind of file ${app.name} takes: it takes ${taken}.`;
+        }
+        if (file.size > kind.maxMb * 1024 * 1024) {
+            return `${file.name} is ${megabytes(file.size)}: ${app.name} takes ${kind.type} of at most ${kind.maxMb} MB.`;
+        }
+    }
+    return null;
+}
+/** What the composer says it takes, in a sentence. */
+export function uploadsInWords(uploads) {
+    const kinds = uploads.kinds
+        .map(kind => `${kind.type} up to ${kind.maxMb} MB`)
+        .join(', ');
+    return `Takes ${kinds}; ${uploads.maxFiles} at most at once.`;
+}

package/lib/loop/core/index.d.ts

@@ -519,7 +519,7 @@ export type AgentBlueprintContribution = {
      * P-19) tell a run turned in the page, and the model it runs on — as the
      * runtime's session API applies them. Unsaid for an agent with no modes.
      */
-    modeEffect?: (chosen: Record<string, string>) => AppModeEffect;
+    modeEffect?: (chosen: Record<string, string>, profile?: string) => AppModeEffect;
 };
 export declare const LoopAgentBlueprint: import("@datalayer/reactor").ContributionPoint<AgentBlueprintContribution>;
 /** One conversation opener a plugin offers on the empty chat. */
@@ -529,6 +529,12 @@ export type ChatSuggestionItem = {
     /** What is submitted; the chip's words when absent. */
     message?: string;
     emoji?: string;
+    /**
+     * The heading it is offered under: openers of one group together, under
+     * its name, those without one first — an application's starter's category
+     * (LOOP P-20).
+     */
+    group?: string;
 };
 /**
  * Conversation openers, contributed ahead of the spec's own.
@@ -649,6 +655,13 @@ export type LoopChatExtrasValue = {
      * offering a first question to somebody who has already asked one.
      */
     hideOpeners?: boolean;
+    /**
+     * Openers in place of the contributed ones, live: what an application
+     * offers with the profile picked in its composer (LOOP P-20) — the empty
+     * chat offers these, and changes them when the profile changes, without
+     * rebuilding the reactor. `hiddenOpeners` still applies.
+     */
+    openers?: ChatSuggestionItem[];
     /**
      * Told what the agent has used, each time the chat learns it.
      *

package/lib/loop/embed/AppEmbed.d.ts

@@ -91,6 +91,20 @@ export declare function useEmbedSession({ app, serverUrl, embedToken, resume, }:
     embedToken?: string;
     resume?: boolean;
 }): EmbedSession;
+/**
+ * Window messages from the page (LOOP P-25): on the host's own server, the
+ * page is handed how to post one to the application's session
+ * (`host.onWindowPort`) — the session the chat goes on with, its uid known
+ * from its first message — and what the code answers is raised on the page
+ * as `window-message` events. The session returned is the one to draw: its
+ * thread told when it starts.
+ */
+export declare function useWindowPort({ serverUrl, embedToken, session, host, }: {
+    serverUrl?: string;
+    embedToken?: string;
+    session: EmbedSession;
+    host?: AppEmbedHost;
+}): EmbedSession;
 /**
  * The page and the application talking (LOOP D-10): the tools of the host
  * the Appspec names, given to its agent through a chat-extras plugin made

package/lib/loop/embed/AppEmbed.js

@@ -52,7 +52,8 @@ import { floatingViewOf } from './embedConfig';
 import { createChatExtrasPlugin } from '../plugins/chat-extras';
 import { hostFrontendTools } from './hostBridge';
 import { embedThemeOverrides, embedThemeStyles } from './embedTheme';
-import { embedSessionKey, reattachSession, sessionGoneSentence, sessionKeeper, visitOfToken, } from './embedSession';
+import { WINDOW_NOT_YET, embedSessionKey, postWindowMessage, reattachSession, sessionGoneSentence, sessionKeeper, visitOfToken, } from './embedSession';
+import { onLoopWindowMessage } from '../../chat/base/loopWindow';
 /**
  * The visit's session, kept and picked up again (LOOP D-13): on the host's
  * server with an embed token that names its visit, the session the chat
@@ -120,6 +121,55 @@ export function useEmbedSession({ app, serverUrl, embedToken, resume = true, })
         ...(found.said ? { said: found.said } : {}),
     };
 }
+/**
+ * Window messages from the page (LOOP P-25): on the host's own server, the
+ * page is handed how to post one to the application's session
+ * (`host.onWindowPort`) — the session the chat goes on with, its uid known
+ * from its first message — and what the code answers is raised on the page
+ * as `window-message` events. The session returned is the one to draw: its
+ * thread told when it starts.
+ */
+export function useWindowPort({ serverUrl, embedToken, session, host, }) {
+    const hostRef = useRef(host);
+    hostRef.current = host;
+    const given = session.thread;
+    const uid = useRef(given?.messages.length ? given.id : undefined);
+    // A thread of its own where the embed keeps none, so that its uid is known.
+    const own = useMemo(() => ({ id: generateMessageId(), messages: [] }), []);
+    const base = given ?? (serverUrl && session.ready ? own : undefined);
+    const thread = useMemo(() => base && {
+        ...base,
+        onStarted: (id) => {
+            uid.current = id;
+            base.onStarted?.(id);
+        },
+    }, [base]);
+    useEffect(() => {
+        const port = host?.onWindowPort;
+        if (!serverUrl || !port) {
+            return undefined;
+        }
+        port(async (data) => {
+            if (!uid.current) {
+                throw new Error(WINDOW_NOT_YET);
+            }
+            const said = await postWindowMessage({
+                serverUrl,
+                uid: uid.current,
+                ...(embedToken ? { token: embedToken } : {}),
+                data,
+            });
+            for (const answer of said) {
+                hostRef.current?.onEvent?.({
+                    type: 'window-message',
+                    detail: { data: answer },
+                });
+            }
+        });
+        return () => port(null);
+    }, [serverUrl, embedToken, host]);
+    return thread ? { ...session, thread } : session;
+}
 /** What the embed says once of its session, above the conversation. */
 function SessionSaid({ said }) {
     return said ? (_jsx(Text, { as: "p", role: "status", sx: { px: 3, py: 2, m: 0, fontSize: 1 }, children: said })) : null;
@@ -146,6 +196,11 @@ export function useHostBridge(app, host) {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [handle, key]);
     const plugins = useMemo(() => (bridge ? [handle.plugin] : NO_HOST_PLUGINS), [bridge, handle]);
+    // What its code tells the page during a turn (LOOP P-25), raised on it.
+    useEffect(() => onLoopWindowMessage(data => hostRef.current?.onEvent?.({
+        type: 'window-message',
+        detail: { data },
+    })), []);
     const said = useRef({ answering: false });
     const before = useRef('idle');
     const told = useRef('');
@@ -278,7 +333,14 @@ export function EmbedThemed({ accent, colorMode, font, variant, children, style,
 }
 export function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, embedToken, height = 640, ownPortal = false, plugins = NO_PLUGINS, host, resume = true, }) {
     const bridge = useHostBridge(app, host);
-    const session = useEmbedSession({ app, serverUrl, embedToken, resume });
+    const kept = useEmbedSession({ app, serverUrl, embedToken, resume });
+    // Window messages from the page, on the host's own server (P-25).
+    const session = useWindowPort({
+        serverUrl,
+        embedToken,
+        session: kept,
+        host,
+    });
     const system = useSystemMode();
     // The theme the application names (T-30), `loop` when none; its mode
     // the host's, else the application's, else the visitor's system's.

package/lib/loop/embed/element.js

@@ -38,6 +38,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * when it called a function of the page, beside `decision` and
  * `token-expired`.
  *
+ * Window messages (LOOP P-25), on the host's own server: the element raises
+ * `window-message` (`detail.data`) when the application's code tells the page
+ * something outside the conversation (`session.send_window_message`), and
+ * `element.postWindowMessage(data)` hands the page's to its `@app.window`.
+ *
  * On the host's server (`server`) with the visit's embed token, the
  * session the application opens is kept in the page's `localStorage`, under
  * the application and the visit its token names, and picked up again after
@@ -54,6 +59,7 @@ import { coreStore } from '@datalayer/core/lib/state/substates/CoreState';
 import { parseAppspec } from '../apps/appspec';
 import { readAppspecYaml } from '../apps/yaml';
 import { AppEmbed, embedAssistantCharacter } from './AppEmbed';
+import { WINDOW_NOT_YET } from './embedSession';
 import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, resumeOf, } from './embedConfig';
 import { embedShadowCss } from './embedTheme';
 /** What the framed run page and the element say to each other. */
@@ -193,10 +199,15 @@ export function defineDatalayerAppElement(options = {}) {
         passed = {};
         /** One object, its functions replaced in place: the host below holds it. */
         offered = {};
+        /** How a window message reaches the application's session, once it can (P-25). */
+        windowPort = null;
         /** What the page gives the application, read at each call (D-10). */
         host = {
             context: () => this.passed,
             functions: this.offered,
+            onWindowPort: post => {
+                this.windowPort = post;
+            },
             onEvent: event => this.dispatchEvent(new CustomEvent(event.type, {
                 detail: event.detail,
                 bubbles: true,
@@ -210,6 +221,18 @@ export function defineDatalayerAppElement(options = {}) {
         set context(value) {
             this.passed = { ...(value ?? {}) };
         }
+        /**
+         * Post a window message to the application (LOOP P-25): its code's
+         * `@app.window` reads it, and what it answers is raised as
+         * `window-message` events. Refused, in a sentence, before its
+         * conversation has started or off the host's own server.
+         */
+        postWindowMessage(data) {
+            const post = this.windowPort;
+            return post
+                ? post(data)
+                : Promise.reject(new Error(`datalayer-app: ${WINDOW_NOT_YET}`));
+        }
         /** The page's functions the application may call, by name (D-10). */
         get functions() {
             return this.offered;

package/lib/loop/embed/embedSession.d.ts

@@ -75,5 +75,19 @@ export declare function reattachSession({ serverUrl, uid, token, fetcher, }: {
     token: string;
     fetcher?: typeof fetch;
 }): Promise<Reattached>;
+/** Said when a window message is posted before the conversation has started. */
+export declare const WINDOW_NOT_YET = "The application takes a window message once its conversation has started, on its own server (the \"server\" attribute).";
+/**
+ * Post a window message to a session (LOOP P-25): its code's `@app.window`
+ * runs on it. Returns what the code told the page back; refused — the
+ * runtime's sentence — when the session or its code takes none.
+ */
+export declare function postWindowMessage({ serverUrl, uid, token, data, fetcher, }: {
+    serverUrl: string;
+    uid: string;
+    token?: string;
+    data: unknown;
+    fetcher?: typeof fetch;
+}): Promise<unknown[]>;
 /** What the page says, once, when the conversation it kept is gone. */
 export declare const sessionGoneSentence: (name: string) => string;

package/lib/loop/embed/embedSession.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { windowTurnOf } from '../../chat/base/loopWindow';
 /** Where a visit's session is kept in the host's storage: `<prefix>:<app>:<visit>`. */
 export const EMBED_SESSION_KEY_PREFIX = 'datalayer-app:session';
 /**
@@ -132,5 +133,38 @@ export async function reattachSession({ serverUrl, uid, token, fetcher = fetch,
         return { kind: 'gone', uid };
     }
 }
+/** Said when a window message is posted before the conversation has started. */
+export const WINDOW_NOT_YET = 'The application takes a window message once its conversation has started, on its own server (the "server" attribute).';
+/**
+ * Post a window message to a session (LOOP P-25): its code's `@app.window`
+ * runs on it. Returns what the code told the page back; refused — the
+ * runtime's sentence — when the session or its code takes none.
+ */
+export async function postWindowMessage({ serverUrl, uid, token, data, fetcher = fetch, }) {
+    const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}/window`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ data }),
+    });
+    if (!response.ok) {
+        let detail = '';
+        try {
+            const body = (await response.json());
+            detail = typeof body.detail === 'string' ? body.detail : '';
+        }
+        catch {
+            // No sentence: the status says it.
+        }
+        throw new Error(detail || `The window message was refused (${response.status}).`);
+    }
+    const turn = windowTurnOf(await response.text());
+    if (turn.error) {
+        throw new Error(turn.error);
+    }
+    return turn.said;
+}
 /** What the page says, once, when the conversation it kept is gone. */
 export const sessionGoneSentence = (name) => `Your earlier conversation with ${name} has ended, so this is a new one.`;

package/lib/loop/embed/hostBridge.d.ts

@@ -6,9 +6,16 @@
  * its Appspec names (`deployment.embedded.host.context`).
  *
  * Out: what the application does, as events — `message` when it has said
- * something, `action` when it called a function of the page — beside the
+ * something, `action` when it called a function of the page,
+ * `window-message` when its code told the page something outside the
+ * conversation (LOOP P-25, `session.send_window_message`) — beside the
  * `decision` and `token-expired` the element raises already.
  *
+ * Window messages, in (P-25): the page posts one with
+ * `element.postWindowMessage(data)`; its code's `@app.window` reads it, on
+ * the host's own server (`server`), and what it answers comes back as
+ * `window-message` events.
+ *
  * Offered: the functions of the page its Appspec names
  * (`deployment.embedded.host.functions`), each called by its agent as the
  * tool `host_<name>`. Every one of these tools is decided in the page by
@@ -42,7 +49,15 @@ export type HostEvent = {
         result?: unknown;
         error?: string;
     };
+} | {
+    type: 'window-message';
+    /** What its code told the page (LOOP P-25): anything JSON writes. */
+    detail: {
+        data: unknown;
+    };
 };
+/** Posts a window message to the application's session (LOOP P-25). */
+export type WindowPost = (data: unknown) => Promise<void>;
 /** A function of the page, as the page gives it. */
 export type HostFunction = (args: Record<string, unknown>) => unknown | Promise<unknown>;
 /** What the page gives an embedded application (LOOP D-10). */
@@ -58,6 +73,12 @@ export type AppEmbedHost = {
      * may be made; the browser's `confirm` when the page gives none.
      */
     ask?: (question: HostQuestion) => boolean | Promise<boolean>;
+    /**
+     * Handed how a window message is posted to the application's session once
+     * the embed can (LOOP P-25) — on the host's own server, its conversation
+     * started — and `null` when it no longer can.
+     */
+    onWindowPort?: (post: WindowPost | null) => void;
 };
 /** What the person is asked before a call of the page is made. */
 export type HostQuestion = {

package/lib/loop/plugins/app-elements/AppElements.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The elements an application's code opened beside the conversation (LOOP
+ * P-18): a side panel on the trailing edge, and a page of its own over the
+ * workspace — each drawn from the same A2UI surface an answer is drawn from
+ * (`InlineSurface`), its buttons sent to the application's actions as an
+ * answer's are (`answerAction`), and closed with its own button.
+ *
+ * Drawn from the workspace's root slot, positioned against the workspace:
+ * nothing is drawn, and nothing is laid out, while nothing is open.
+ *
+ * @module loop/plugins/app-elements/AppElements
+ */
+import type { JSX } from 'react';
+import { type LoopElement } from '../../../chat/base/loopElement';
+import type { LoopWorkspaceContext } from '../../core';
+/** How wide the side panel is, at most. */
+export declare const APP_PANEL_WIDTH = 380;
+/** What is open now: the panels in the order they opened, and the last page. */
+export declare function elementsByPlace(open: readonly LoopElement[]): {
+    panels: LoopElement[];
+    page: LoopElement | null;
+};
+/** Every element open in a side panel or on a page, drawn where it belongs. */
+export declare function AppElements({ workspace, }: {
+    workspace?: LoopWorkspaceContext;
+}): JSX.Element | null;
+export default AppElements;

package/lib/loop/plugins/app-elements/AppElements.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo, useSyncExternalStore } from 'react';
+import { IconButton, Text } from '@primer/react';
+import { XIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { closeLoopElement, onLoopElements, openLoopElements, } from '../../../chat/base/loopElement';
+import { InlineSurface, SURFACE_CATALOG_ID, } from '../a2ui-surface/InlineSurface';
+import { answerAction, readA2uiToolResult } from '../a2ui-surface/toolResult';
+/** How wide the side panel is, at most. */
+export const APP_PANEL_WIDTH = 380;
+/** What is open now: the panels in the order they opened, and the last page. */
+export function elementsByPlace(open) {
+    const pages = open.filter(element => element.where === 'page');
+    return {
+        panels: open.filter(element => element.where === 'panel'),
+        page: pages.length > 0 ? pages[pages.length - 1] : null,
+    };
+}
+function ElementBody({ element, send, }) {
+    const parsed = useMemo(() => readA2uiToolResult(element.shows, SURFACE_CATALOG_ID), [element.shows]);
+    const onAction = (action) => {
+        // A button of what its code shows: its action goes to the application,
+        // as a button of an answer does (LOOP P-04).
+        const pressed = answerAction(action);
+        if (pressed)
+            send?.(pressed.message, pressed.forwardedProps);
+    };
+    if (!parsed?.messages || parsed.messages.length === 0) {
+        return _jsx(Text, { sx: { color: 'fg.muted' }, children: "Nothing to show." });
+    }
+    return (_jsx(InlineSurface
+    // Drawn again whole when the code changes it.
+    , { messages: parsed.messages, onAction: onAction }, JSON.stringify(element.shows)));
+}
+function ElementHeader({ element }) {
+    return (_jsxs(Box, { sx: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 2,
+            mb: 2,
+        }, children: [_jsx(Text, { as: "h2", sx: { fontSize: 2, fontWeight: 'bold', m: 0 }, children: element.title }), _jsx(IconButton, { icon: XIcon, variant: "invisible", size: "small", "aria-label": `Close ${element.title}`, onClick: () => closeLoopElement(element.id) })] }));
+}
+/** Every element open in a side panel or on a page, drawn where it belongs. */
+export function AppElements({ workspace, }) {
+    const open = useSyncExternalStore(onLoopElements, openLoopElements, openLoopElements);
+    const { panels, page } = elementsByPlace(open);
+    const send = workspace?.viewControls.send;
+    if (panels.length === 0 && page === null)
+        return null;
+    return (_jsxs(_Fragment, { children: [panels.length > 0 ? (_jsx(Box, { as: "aside", "aria-label": "Side panel", sx: {
+                    position: 'absolute',
+                    top: 0,
+                    right: 0,
+                    bottom: 0,
+                    width: `min(${APP_PANEL_WIDTH}px, 100%)`,
+                    zIndex: 1,
+                    overflowY: 'auto',
+                    borderLeft: '1px solid',
+                    borderColor: 'border.default',
+                    bg: 'canvas.subtle',
+                    boxShadow: 'shadow.medium',
+                    p: 3,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 3,
+                }, children: panels.map(element => (_jsxs(Box, { as: "section", "aria-label": element.title, children: [_jsx(ElementHeader, { element: element }), _jsx(ElementBody, { element: element, send: send })] }, element.id))) })) : null, page !== null ? (_jsxs(Box, { role: "dialog", "aria-label": page.title, sx: {
+                    position: 'absolute',
+                    inset: 0,
+                    zIndex: 2,
+                    overflowY: 'auto',
+                    bg: 'canvas.default',
+                    p: [3, 4],
+                }, children: [_jsx(ElementHeader, { element: page }), _jsx(ElementBody, { element: page, send: send })] })) : null] }));
+}
+export default AppElements;

package/lib/loop/plugins/app-elements/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `app-elements` — what an application's code opens beside the
+ * conversation (LOOP P-18): `session.show(..., where="panel")` a side panel,
+ * `where="page"` a page of its own over the workspace, each closed by the
+ * code (`session.close`) or by the person. Inline, an element is a message,
+ * which the chat draws (P-04); this plugin draws the other two.
+ *
+ * The chat keeps what is open (`chat/base/loopElement`), from the session
+ * API's `loop.element` events; this plugin draws it from the workspace's
+ * root slot, positioned against the workspace, so that nothing is laid out
+ * while nothing is open.
+ *
+ * @module loop/plugins/app-elements
+ */
+import { type ReactorPlugin } from '@datalayer/reactor';
+export declare const APP_ELEMENTS_PLUGIN_NAME = "@datalayer/loop-plugin-app-elements";
+/** The plugin that draws an application's side panel and pages. */
+export declare const AppElementsPlugin: ReactorPlugin<Record<string, never>, unknown, unknown>;
+export { AppElements, APP_PANEL_WIDTH, elementsByPlace } from './AppElements';
+export default AppElementsPlugin;

package/lib/loop/plugins/app-elements/index.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `app-elements` — what an application's code opens beside the
+ * conversation (LOOP P-18): `session.show(..., where="panel")` a side panel,
+ * `where="page"` a page of its own over the workspace, each closed by the
+ * code (`session.close`) or by the person. Inline, an element is a message,
+ * which the chat draws (P-04); this plugin draws the other two.
+ *
+ * The chat keeps what is open (`chat/base/loopElement`), from the session
+ * API's `loop.element` events; this plugin draws it from the workspace's
+ * root slot, positioned against the workspace, so that nothing is laid out
+ * while nothing is open.
+ *
+ * @module loop/plugins/app-elements
+ */
+import { definePlugin } from '@datalayer/reactor';
+import { clearLoopElements } from '../../../chat/base/loopElement';
+import { LoopSlots } from '../../core';
+import { AppElements } from './AppElements';
+export const APP_ELEMENTS_PLUGIN_NAME = '@datalayer/loop-plugin-app-elements';
+/** The plugin that draws an application's side panel and pages. */
+export const AppElementsPlugin = definePlugin({
+    name: APP_ELEMENTS_PLUGIN_NAME,
+    displayName: 'Side panel and pages',
+    description: 'What an application opens beside the conversation: a side panel, or a page of its own.',
+    octicon: 'sidebar-expand',
+    build: () => ({
+        components: [
+            {
+                id: 'app-elements',
+                slot: LoopSlots.root,
+                Component: AppElements,
+            },
+        ],
+    }),
+    // A workspace that goes takes what it had open with it.
+    register: () => clearLoopElements,
+});
+export { AppElements, APP_PANEL_WIDTH, elementsByPlace } from './AppElements';
+export default AppElementsPlugin;

package/lib/loop/plugins/app-page/appPageModel.d.ts

@@ -23,7 +23,7 @@
  *
  * @module loop/plugins/app-page/appPageModel
  */
-import type { AppSettingSpec, AppSpec } from '../../../types/agentspecs';
+import type { AppFormField, AppFormSchema, AppSpec } from '../../../types/agentspecs';
 import type { ChatTurnSnapshot, ConversationEntry } from '../../core';
 /** The id of the editor surface an application's page is drawn in. */
 export declare const APP_PAGE_SURFACE = "app-page";
@@ -77,6 +77,15 @@ export declare const APP_KIND_PATHS: Record<AppPageKind, AppKindPaths>;
 export declare const isAppPageKind: (kind: string) => kind is AppPageKind;
 /** The path a setting, an input of the page, is kept at. */
 export declare const inputPath: (id: string) => string;
+/**
+ * The fields of an application's settings (C-16), by name, in the order its
+ * form says them; none when it has no settings.
+ */
+export declare function settingFields(settings: AppFormSchema | undefined): Array<[string, AppFormField]>;
+/** A setting as a person reads it: its field's `title`, else its name. */
+export declare const settingTitle: (id: string, field: AppFormField) => string;
+/** What each setting starts at: its field's `default`, for those that say one. */
+export declare function settingDefaults(settings: AppFormSchema | undefined): Record<string, unknown>;
 /**
  * What an application publishes and takes, with its own settings: the kind's
  * list, and for a kind that has inputs each setting at `/inputs/<id>`, both
@@ -95,8 +104,6 @@ export declare function hasAppPage(app: Pick<AppSpec, 'kind' | 'interface' | 'ag
  * none): the application's layout is `chat`, the conversation alone.
  */
 export declare function surfaceUnshown(app: Pick<AppSpec, 'kind' | 'interface' | 'agent'>): string | null;
-/** A setting's first value, as its input holds it. */
-export declare function initialInput(setting: AppSettingSpec): unknown;
 /**
  * What the conversation publishes to the page, by path, now: from its
  * current turn, and for a chat its whole conversation.
@@ -136,8 +143,10 @@ export declare function givenFiles(files: unknown): {
 };
 /**
  * The application's settings as the page holds them, as the session API
- * takes them: a choice as the option chosen, a number as a number, a toggle
- * as on or off — each setting the page has a value for.
+ * takes them, each as its field's type says (C-16): a number as a number, a
+ * boolean as on or off, a word as the option chosen — a ChoicePicker holds a
+ * list of them — each setting the page has a value for. The runtime checks
+ * them against the settings' form.
  */
 export declare function settingsOf(app: Pick<AppSpec, 'interface'>, inputs: unknown): Record<string, unknown>;
 /**