@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/loop/shell/LoopWorkspace.js

@@ -0,0 +1,231 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Box } from '@primer/react';
+import { buildReactorFromPlugins, onView, } from '@datalayer/reactor';
+import { ReactorSlot, ReactorViewHost, useContributions, useReactorEvent, useSlotComponents, useReactor, } from '@datalayer/reactor/react';
+import { LoopCommand, LoopSlots, LoopViewType, canOpenView, createPromptChannel, parseCommand, loopSurfaceId, } from '../core';
+import { SIDEBAR_WIDTH } from '../plugins/plugins-panel';
+import { ViewSwitcher } from './ViewSwitcher';
+/** Build the platform for a set of plugins. */
+export function buildLoopReactor(extensions) {
+    return buildReactorFromPlugins(extensions);
+}
+export function LoopWorkspace(props) {
+    const { serverUrl, agentId, conversationId, model, sandbox = { state: 'idle' }, extensions = [], reactor: providedReactor, manageReactor = true, initialViewType, onSend, layout = 'page', showViewSelector = true, showHeader = true, chatHeaderActions, headerActions, } = props;
+    // Building the platform is a one-time act: rebuilding it on every render
+    // would restart every plugin.
+    const reactor = useMemo(() => providedReactor ?? buildLoopReactor(extensions), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [providedReactor]);
+    useReactor(reactor, { autoStart: manageReactor });
+    return (_jsx(WorkspaceBody, { serverUrl: serverUrl, agentId: agentId, conversationId: conversationId, model: model, initialSandbox: sandbox, initialViewType: initialViewType, onSend: onSend, layout: layout, showViewSelector: showViewSelector, showHeader: showHeader, chatHeaderActions: chatHeaderActions, headerActions: headerActions }));
+}
+/**
+ * Split from `LoopWorkspace` so the hooks below run with the platform already
+ * registered — `useContributions` needs a reactor in the store, and `useReactor`
+ * registers it during the parent's render.
+ */
+function WorkspaceBody({ serverUrl, agentId: initialAgentId, conversationId, model, initialSandbox, initialViewType, onSend, layout = 'page', showViewSelector = true, showHeader = true, chatHeaderActions, headerActions, }) {
+    /*
+     * Which agent the session is talking to.
+     *
+     * State rather than the prop straight through, because it can change from
+     * inside: a picker in the header points the session at another agent, and
+     * everything downstream — the chat's endpoint, the sandbox connection, the
+     * notebook's id — reads it from the workspace.
+     */
+    const [agentId, setAgentId] = useState(initialAgentId);
+    /* Minted once per mount, and deliberately not derived from `agentId`: the
+     * surfaces outlive whichever agent is currently attached to them. */
+    const surfaceIdRef = useRef(loopSurfaceId(conversationId ?? `session-${Date.now().toString(36)}`));
+    // A host that re-mounts the workspace on a different agent wins: its prop is
+    // the session it means to open, and a stale in-page choice must not survive.
+    useEffect(() => {
+        setAgentId(initialAgentId);
+    }, [initialAgentId]);
+    const [activeViewType, setActiveViewType] = useState(initialViewType ?? '');
+    // Seeded by the host (a handoff carries what the terminal knew), then kept
+    // current by whichever plugin owns the sandbox.
+    const [sandbox, setSandbox] = useState(initialSandbox);
+    // One channel per workspace, created once: recreating it would drop whatever
+    // the mounted view had subscribed with.
+    const [prompts] = useState(createPromptChannel);
+    const [viewControls, setViewControlsState] = useState({});
+    const setViewControls = useCallback((controls) => {
+        setViewControlsState(controls ?? {});
+    }, []);
+    const views = useContributions(LoopViewType);
+    const commands = useContributions(LoopCommand);
+    // Read to decide whether the column exists at all, not to render it: the
+    // slot does that.
+    const sidebar = useSlotComponents(LoopSlots.sidebar);
+    const commandsRef = useRef(commands);
+    const currentWorkspace = useRef(null);
+    const compact = layout === 'panel';
+    // Dispatch stays with the shell because only the shell sees every command
+    // every plugin contributed. Whoever renders a prompt calls this.
+    const submit = useCallback(async (message) => {
+        const command = parseCommand(message);
+        if (!command) {
+            onSend?.(message, currentWorkspace.current);
+            const heard = prompts.submit(message);
+            return heard || onSend
+                ? { handled: true }
+                : {
+                    handled: false,
+                    reason: 'Nothing is listening for prompts in this view yet.',
+                };
+        }
+        const match = commandsRef.current.find(entry => entry.value.name === command.name ||
+            (entry.value.aliases ?? []).includes(command.name));
+        if (!match) {
+            return {
+                handled: false,
+                command: command.name,
+                reason: `Unknown command: /${command.name}. Type /help to see what there is.`,
+            };
+        }
+        const result = await match.value.run({
+            workspace: currentWorkspace.current,
+            argv: command.argv,
+        });
+        if (result?.prompt) {
+            onSend?.(result.prompt, currentWorkspace.current);
+        }
+        return {
+            handled: true,
+            command: command.name,
+            result: result ?? undefined,
+        };
+    }, [onSend, prompts]);
+    const workspace = useMemo(() => ({
+        serverUrl,
+        agentId,
+        surfaceId: surfaceIdRef.current,
+        setAgentId,
+        conversationId,
+        model,
+        sandbox,
+        setSandbox,
+        activeViewType,
+        setActiveViewType,
+        prompts,
+        submit,
+        viewControls,
+        setViewControls,
+        chatHeaderActions,
+    }), [
+        serverUrl,
+        agentId,
+        conversationId,
+        model,
+        sandbox,
+        activeViewType,
+        prompts,
+        submit,
+        viewControls,
+        setViewControls,
+        chatHeaderActions,
+    ]);
+    // `submit` must not be rebuilt whenever the workspace object changes — the
+    // chat holds on to it — so it reads the current values through refs.
+    currentWorkspace.current = workspace;
+    commandsRef.current = commands;
+    // With nothing chosen, open the first view that can be opened. Falling back
+    // to "nothing" would leave a shell that looks broken on first paint.
+    const effectiveViewType = useMemo(() => {
+        if (activeViewType) {
+            return activeViewType;
+        }
+        const openable = views.find(entry => canOpenView(entry.value, workspace));
+        return openable?.value.viewType ?? '';
+    }, [activeViewType, views, workspace]);
+    // Tell the reactor which view is open, so plugins that only matter inside
+    // one can wait for it and stand down when it closes. One line, and it is
+    // both halves: `fire` deactivates whatever declared this event before it
+    // activates whatever was waiting for it. A plugin that declares neither is
+    // untouched, so this costs nothing until somebody uses it.
+    useReactorEvent(effectiveViewType ? onView(effectiveViewType) : undefined);
+    return (_jsxs(Box
+    /*
+      Marked so a plugin inside can find the workspace it is part of.
+
+      The chat's full-screen button promotes *this* element rather than its
+      own view, which is what keeps the header's controls — the agent picker,
+      where the code runs — reachable at full screen instead of leaving them
+      behind on the page underneath. A data attribute rather than a ref
+      through the context: the plugin needs a DOM node and nothing else, and
+      the shell should not have to publish one to be found.
+    */
+    , { "data-loop-workspace": "", sx: {
+            display: 'flex',
+            flexDirection: 'column',
+            height: '100%',
+            minHeight: 0,
+            // The containing block for anything in the root slot that positions
+            // itself absolutely — the floating prompt does. Without this it would
+            // resolve against whatever ancestor happens to be positioned, and
+            // float over the host's page instead of over the workspace.
+            position: 'relative',
+            bg: 'canvas.default',
+            color: 'fg.default',
+        }, children: [showHeader ? (_jsxs(Box, { as: "header", sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    // In a column there is no room for a row: the header wraps rather
+                    // than pushing the model chip off the edge.
+                    justifyContent: compact ? 'flex-start' : 'space-between',
+                    /*
+                      Allowed to wrap at any width.
+                      
+                      `nowrap` meant the row absorbed whatever a plugin put in it by
+                      squeezing everything else — a sandbox failure message, a long
+                      agent name — instead of taking a second line. The controls stayed
+                      on one row and got narrower, which is the wrong trade: a header
+                      two lines tall is legible, a compressed one is not.
+                    */
+                    flexWrap: 'wrap',
+                    gap: 2,
+                    px: compact ? 2 : 3,
+                    py: 2,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                    flex: '0 0 auto',
+                }, children: [headerActions, _jsx(ReactorSlot, { slot: LoopSlots.header, props: { workspace } }), showViewSelector ? (_jsx(ViewSwitcher, { views: views, workspace: workspace, compact: compact })) : null] })) : null, _jsxs(Box, { sx: { flex: '1 1 auto', minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: {
+                            flex: '1 1 auto',
+                            minWidth: 0,
+                            minHeight: 0,
+                            position: 'relative',
+                        }, children: _jsx(ReactorViewHost, { point: LoopViewType, active: effectiveViewType, props: { viewType: effectiveViewType, workspace }, fallback: _jsx(Centered, { children: "Loading\u2026" }), empty: _jsx(Centered, { children: "No view is available yet." }), errorFallback: error => (_jsxs(Centered, { children: ["This view failed to load: ", error.message] })) }) }), sidebar.length > 0 ? (_jsx(Box, { as: "aside", sx: {
+                            flex: '0 0 auto',
+                            // Wide enough for a plugin's name, its description and a switch
+                            // on one line. The panel truncates to the same number, and takes
+                            // it from `SIDEBAR_WIDTH` so the two cannot drift.
+                            width: compact ? '100%' : `${SIDEBAR_WIDTH}px`,
+                            minWidth: 0,
+                            // On the trailing edge: the work is what a person reads first,
+                            // and the switches belong beside it rather than in front of it.
+                            borderLeft: compact ? 'none' : '1px solid',
+                            borderTop: compact ? '1px solid' : 'none',
+                            borderColor: 'border.default',
+                            bg: 'canvas.subtle',
+                            overflowY: 'auto',
+                            // The shell's chrome, not the plugins': a contributed panel
+                            // should not have to guess how far its host keeps things from
+                            // the edge, and two of them would guess differently.
+                            px: 3,
+                            py: 3,
+                        }, children: _jsx(ReactorSlot, { slot: LoopSlots.sidebar, props: { workspace } }) })) : null] }), _jsxs(Box, { sx: { flex: '0 0 auto' }, children: [_jsx(ReactorSlot, { slot: LoopSlots.footer, props: { workspace } }), _jsx(ReactorSlot, { slot: LoopSlots.status, props: { workspace } })] }), _jsx(ReactorSlot, { slot: LoopSlots.root, props: { workspace } })] }));
+}
+function Centered({ children }) {
+    return (_jsx(Box, { sx: {
+            height: '100%',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: 'fg.muted',
+            fontSize: 1,
+            px: 3,
+            textAlign: 'center',
+        }, children: children }));
+}

package/lib/loop/shell/PluginToggles.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A checkbox per plugin.
+ *
+ * An extension model is a claim until someone can turn a plugin off and watch
+ * the workspace carry on. This is the smallest surface that makes the claim
+ * checkable: the list comes from the reactor rather than from a hard-coded
+ * array, so it cannot lie about how many plugins there are.
+ *
+ * Not part of the workspace itself — the workspace has one navigation element
+ * and no settings tree (§3.5). This belongs to the examples that demonstrate it.
+ *
+ * @module loop/shell/PluginToggles
+ */
+import type { JSX } from 'react';
+export type PluginTogglesProps = {
+    /** Extensions the example does not let you switch off (the shell's own). */
+    locked?: readonly string[];
+    title?: string;
+};
+export declare function PluginToggles({ locked, title, }: PluginTogglesProps): JSX.Element;
+export default PluginToggles;

package/lib/loop/shell/PluginToggles.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useSyncExternalStore } from 'react';
+import { Box, Text } from '@primer/react';
+import { useReactorPlatform } from '@datalayer/reactor/react';
+/** Trim the package scope so the list reads as names rather than paths. */
+function shortName(name) {
+    return name
+        .replace(/^@datalayer\/loop-plugin-/, '')
+        .replace(/^@datalayer\//, '');
+}
+export function PluginToggles({ locked = [], title = 'Plugins', }) {
+    const reactor = useReactorPlatform();
+    // The revision changes on every enable/disable, so the list follows the
+    // reactor rather than a copy of it.
+    useSyncExternalStore(reactor.subscribe, () => reactor.getRevision());
+    const toggle = useCallback((name, next) => {
+        if (next) {
+            reactor.enable(name);
+        }
+        else {
+            reactor.disable(name);
+        }
+    }, [reactor]);
+    return (_jsxs(Box, { sx: {
+            p: 3,
+            borderBottom: '1px solid',
+            borderColor: 'border.default',
+            bg: 'canvas.subtle',
+        }, children: [_jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold', color: 'fg.muted' }, children: title }), _jsx(Box, { sx: { display: 'flex', flexWrap: 'wrap', gap: 3, mt: 2 }, children: reactor.listPlugins().map(name => {
+                    const isLocked = locked.includes(name);
+                    return (_jsxs(Box, { as: "label", sx: {
+                            display: 'inline-flex',
+                            alignItems: 'center',
+                            gap: 1,
+                            fontSize: 1,
+                            cursor: isLocked ? 'not-allowed' : 'pointer',
+                            opacity: isLocked ? 0.6 : 1,
+                        }, children: [_jsx("input", { type: "checkbox", checked: reactor.isEnabled(name), disabled: isLocked, onChange: event => toggle(name, event.target.checked) }), shortName(name)] }, name));
+                }) })] }));
+}
+export default PluginToggles;

package/lib/loop/shell/ViewSwitcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The workspace's one piece of navigation.
+ *
+ * It is built from contributions rather than a hard-coded list of modes, which
+ * is the whole difference from `EphemeralSurfaceControl`: a fifth view costs a
+ * plugin, not an edit to a union type.
+ *
+ * @module loop/shell/ViewSwitcher
+ */
+import type { JSX } from 'react';
+import type { Contribution } from '@datalayer/reactor';
+import { type LoopWorkspaceContext, type ViewTypeContribution } from '../core';
+export type ViewSwitcherProps = {
+    views: Contribution<ViewTypeContribution>[];
+    workspace: LoopWorkspaceContext;
+    /**
+     * Drop the labels and keep the icons.
+     *
+     * For a side panel, where four labelled tabs would use the width the views
+     * need. The tooltip still carries the title, so nothing is lost but space.
+     */
+    compact?: boolean;
+};
+export declare function ViewSwitcher({ views, workspace, compact, }: ViewSwitcherProps): JSX.Element | null;

package/lib/loop/shell/ViewSwitcher.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Tooltip } from '@primer/react';
+import { canOpenView, } from '../core';
+export function ViewSwitcher({ views, workspace, compact = false, }) {
+    // One choice is not a choice.
+    if (views.length < 2) {
+        return null;
+    }
+    return (_jsx(Box, { role: "tablist", "aria-label": "Workspace views", sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            bg: 'neutral.muted',
+            borderRadius: '6px',
+            p: '2px',
+            gap: '1px',
+        }, children: views.map(entry => {
+            const view = entry.value;
+            const open = canOpenView(view, workspace);
+            const active = workspace.activeViewType === view.viewType;
+            const Icon = view.icon;
+            // A greyed-out tab with no explanation is worse than no tab.
+            // In compact mode the tooltip is the only place the title appears, so
+            // it says the title even when the view is fine.
+            const label = open
+                ? view.title
+                : `${view.title} — ${view.unavailableReason?.(workspace) ?? 'unavailable'}`;
+            return (_jsx(Tooltip, { text: label, direction: "n", children: _jsxs(Box, { as: "button", role: "tab", "aria-selected": active, "aria-disabled": !open, onClick: () => open && workspace.setActiveViewType(view.viewType), sx: {
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        gap: 1,
+                        border: 'none',
+                        borderRadius: '5px',
+                        px: 2,
+                        py: '4px',
+                        fontSize: 0,
+                        cursor: open ? 'pointer' : 'not-allowed',
+                        opacity: open ? 1 : 0.5,
+                        bg: active ? 'canvas.default' : 'transparent',
+                        color: active ? 'fg.default' : 'fg.muted',
+                        boxShadow: active ? 'shadow.small' : 'none',
+                    }, children: [Icon ? _jsx(Icon, { size: 14 }) : null, compact && Icon ? null : view.title] }) }, view.viewType));
+        }) }));
+}

package/lib/loop/shell/WorkspaceFullScreenAction.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The full-screen control, as a standalone icon.
+ *
+ * The chat header has always carried one; this is the same behaviour —
+ * `useWorkspaceFullScreen`, promoting the whole workspace — packaged for
+ * anywhere else a host or plugin wants it. The window-frame plugin puts it in
+ * the workspace header, which is what keeps the control reachable for a shell
+ * that hides the chat's chrome.
+ *
+ * Unlike the chat view's own control, this one is a bare icon with no view of
+ * its own to paint an overlay on — so it asks the hook to paint one for it
+ * (`paintOverlay`), offset by `ChatPluginConfig.fullScreenTopOffset` for a
+ * host whose own fixed header needs to survive full screen. A host that never
+ * sets that config gets `0`: the same full-viewport overlay, or the same
+ * native-API promotion, as before this existed.
+ *
+ * No hint animation here, deliberately: the chat's control breathes when the
+ * first answer arrives because that is where the reader is looking; a header
+ * icon that pulsed would be chrome asking for attention it has not earned.
+ *
+ * @module loop/shell/WorkspaceFullScreenAction
+ */
+import type { JSX } from 'react';
+export declare function WorkspaceFullScreenAction(): JSX.Element;
+export default WorkspaceFullScreenAction;

package/lib/loop/shell/WorkspaceFullScreenAction.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { IconButton } from '@primer/react';
+import { ScreenFullIcon, ScreenNormalIcon } from '@primer/octicons-react';
+import { useReactorPlatform } from '@datalayer/reactor/react';
+import { useWorkspaceFullScreen } from './useWorkspaceFullScreen';
+import { CHAT_PLUGIN_NAME } from '../plugins/chat';
+export function WorkspaceFullScreenAction() {
+    /* The button itself anchors the lookup: it is inside the workspace, which
+       is all `useWorkspaceFullScreen` needs to find what to promote. */
+    const anchorRef = useRef(null);
+    const reactor = useReactorPlatform();
+    const fullScreenTopOffset = reactor.getConfig(CHAT_PLUGIN_NAME)
+        ?.fullScreenTopOffset ?? 0;
+    const { fullScreen, toggle } = useWorkspaceFullScreen(anchorRef, {
+        paintOverlay: Boolean(fullScreenTopOffset),
+        topOffset: fullScreenTopOffset,
+    });
+    return (_jsx(IconButton, { ref: anchorRef, icon: fullScreen ? ScreenNormalIcon : ScreenFullIcon, "aria-label": fullScreen ? 'Exit full screen' : 'Enter full screen', variant: "invisible", size: "small", 
+        // The far end of the trailing cluster: past the editor selector's auto
+        // margin, after the trial clock's `order: 1`.
+        sx: { order: 2 }, onClick: toggle }));
+}
+export default WorkspaceFullScreenAction;

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

@@ -0,0 +1,10 @@
+/**
+ * The workspace shell: a prompt at the bottom, one view above it.
+ *
+ * @module loop/shell
+ */
+export { LoopWorkspace, buildLoopReactor, type LoopWorkspaceProps, } from './LoopWorkspace';
+export { ViewSwitcher, type ViewSwitcherProps } from './ViewSwitcher';
+export { PluginToggles, type PluginTogglesProps } from './PluginToggles';
+export { useWorkspaceFullScreen, type WorkspaceFullScreen, } from './useWorkspaceFullScreen';
+export { WorkspaceFullScreenAction } from './WorkspaceFullScreenAction';

package/lib/loop/shell/index.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The workspace shell: a prompt at the bottom, one view above it.
+ *
+ * @module loop/shell
+ */
+export { LoopWorkspace, buildLoopReactor, } from './LoopWorkspace';
+export { ViewSwitcher } from './ViewSwitcher';
+export { PluginToggles } from './PluginToggles';
+export { useWorkspaceFullScreen, } from './useWorkspaceFullScreen';
+export { WorkspaceFullScreenAction } from './WorkspaceFullScreenAction';

package/lib/loop/shell/useWorkspaceFullScreen.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Full screen for the workspace, from wherever the control is drawn.
+ *
+ * Extracted from the chat view so the same behaviour can be offered twice —
+ * the chat's own header keeps its control, and the workspace header gains one
+ * — without either copying the machinery.
+ *
+ * Done with the Fullscreen API rather than by drawing a big box, because a
+ * component cannot know what it is inside of. `position: fixed` escapes only
+ * as far as the nearest ancestor with a transform, and a page that animates
+ * its sections in — the landing does — leaves one behind permanently: the
+ * "full screen" chat then filled the card it was already in. The API promotes
+ * the element to the browser's top layer, where no ancestor can hold it, and
+ * unlike a portal it does not move in the DOM — so every inherited theme
+ * variable the editors read still resolves.
+ *
+ * A CSS overlay is kept as the fallback for where the API is refused — an
+ * iframe without `allow="fullscreen"`, mostly. The hook only reports which of
+ * the two is in play (`usingApi`); painting the overlay stays with the caller,
+ * which is the one that knows what it looks like.
+ *
+ * @module loop/shell/useWorkspaceFullScreen
+ */
+import type { RefObject } from 'react';
+export type WorkspaceFullScreen = {
+    /** Whether the workspace is at full screen, by either door. */
+    fullScreen: boolean;
+    /** Whether the browser's API is the door in use; read `.current`. */
+    usingApi: RefObject<boolean>;
+    /** Enter or leave, whichever applies. */
+    toggle: () => void;
+    /**
+     * The `topOffset` in pixels while the overlay is up — measured from a
+     * selector's element when `topOffset` is one — for a caller that paints
+     * its own overlay. 0 otherwise.
+     */
+    topOffsetPx: number;
+};
+/**
+ * A top offset as pixels: a number as given, or the bottom edge of the
+ * element a CSS selector names — a host's fixed header, whose height depends
+ * on the width it wraps at and is never a number worth hard-coding. A
+ * selector that matches nothing, or no document, is 0.
+ */
+export declare function resolveTopOffset(offset: number | string | undefined): number;
+export type WorkspaceFullScreenOptions = {
+    /**
+     * Never ask the browser's API for full screen — go straight to the CSS
+     * overlay, every time.
+     *
+     * The API promotes the workspace above *everything* on the page, a fixed
+     * header the host drew around the workspace included: there is no partial
+     * form of it that leaves a sibling element on screen, because promoting an
+     * element removes the rest of the page from the compositor entirely. A
+     * host whose header must survive full screen has no choice but to give up
+     * the API's own benefits (see the module doc) and ask for the overlay
+     * outright. False (the default) keeps trying the API first, the way every
+     * other host wants it.
+     */
+    forceOverlay?: boolean;
+    /**
+     * Paint the CSS-overlay fallback itself, directly on the promoted node's
+     * own inline styles, for a caller with no overlay of its own to paint —
+     * `WorkspaceFullScreenAction`, which is a bare icon and never had one.
+     * Implies `forceOverlay`: painting an overlay is moot if the API took the
+     * workspace instead.
+     *
+     * `ChatView`'s own call leaves this off and keeps painting its own —
+     * scoped to its own view rather than the whole workspace — so the two
+     * never stack on top of one another.
+     */
+    paintOverlay?: boolean;
+    /**
+     * Room left clear at the top of the overlay, for a host's own fixed
+     * header: pixels, or a CSS selector for the header itself, whose bottom
+     * edge is measured when the overlay goes up and again on every resize.
+     * Painted by the hook when `paintOverlay` is set; reported as
+     * `topOffsetPx` for a caller that paints its own.
+     */
+    topOffset?: number | string;
+};
+/**
+ * Full-screen state and the toggle, anchored by any element inside the
+ * workspace.
+ *
+ * The element promoted is the whole workspace — the nearest
+ * `[data-loop-workspace]` above the anchor — so the header's controls come
+ * along instead of being left on the page underneath. With no workspace
+ * around it, the anchor's own element is promoted, which is what a view
+ * mounted without a shell would want.
+ */
+export declare function useWorkspaceFullScreen(anchorRef: RefObject<HTMLElement | null>, options?: WorkspaceFullScreenOptions): WorkspaceFullScreen;
+export default useWorkspaceFullScreen;