@datalayer/agent-runtimes 1.3.97 → 1.3.98

package/lib/apps/apps/AppRenderer.js

@@ -71,6 +71,7 @@ import { keepsFeedback } from './feedback';
 import { keptBeforeFirstMessage } from './kept';
 import { ChatLanguage } from '../../chat/ChatLanguage';
 import { defineAppRuntimePlugin } from './AppRuntimePlugins';
+import { hasFolderModules } from './customComponents';
 import { appPluginPair } from './pluginPair';
 /** The id of an agent or a Cog, without its version. */
 export const agentIdOf = (app) => {
@@ -232,8 +233,10 @@ export function appPreset(app, options = {}) {
     return {
         plugins: [
             defineAppPlugin(app, shown),
-            // What its runtime holds, told to the page (F-15).
-            defineAppRuntimePlugin(app.id),
+            // What its runtime holds, told to the page (F-15), and its packaged
+            // page side read from it when its components are files of its folder
+            // (P-29).
+            defineAppRuntimePlugin(app.id, { pageSide: hasFolderModules(app) }),
             ...(withPage ? [defineAppPagePlugin(shown), ...blocks] : []),
             // The components its developer wrote (LOOP P-17): blocks of its page
             // and renderers of its page, its elements and its answers — its own.

package/lib/apps/apps/AppRuntimePlugins.d.ts

@@ -1,8 +1,12 @@
 import { type ReactorPlugin } from '@datalayer/reactor';
 export declare const APP_RUNTIME_PLUGIN_NAME = "@datalayer/loop-plugin-app-runtime";
 /** Follows the application's runtime, and tells the page what it holds. */
-export declare function AppRuntimePlugins({ appId }: {
+export declare function AppRuntimePlugins({ appId, pageSide, }: {
     appId: string;
+    /** Its page side is packaged, to be read from its runtime (P-29). */
+    pageSide?: boolean;
 }): null;
 /** The plugin that follows an application's runtime for its page. */
-export declare function defineAppRuntimePlugin(appId: string): ReactorPlugin<Record<string, never>, unknown, unknown>;
+export declare function defineAppRuntimePlugin(appId: string, { pageSide }?: {
+    pageSide?: boolean;
+}): ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/apps/apps/AppRuntimePlugins.js

@@ -23,13 +23,22 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *   its own runtime, and the pair is whole: nothing stands down, nothing is
  *   blank.
  *
+ * An application whose components are files of its folder (LOOP P-29) has
+ * its page side in its package, installed beside the server that runs it:
+ * once on a runtime, the page reads it there with Reactor's
+ * `bootstrapExtensions` (`<base>/plugins/frontend-extensions`) and installs
+ * it into the running platform — the extension `loop-app-<id>`, the
+ * application's, its page-side plugin saying where the folder's files are
+ * (`LoopAppFiles`). A runtime with no package of it answers nothing, and its
+ * components say so.
+ *
  * A plugin of its own, with no backend requirement, so that it keeps
  * listening while the application's plugin is stood down. It renders nothing.
  *
  * @module apps/apps/AppRuntimePlugins
  */
 import { useCallback, useEffect } from 'react';
-import { definePlugin } from '@datalayer/reactor';
+import { bootstrapExtensions, definePlugin, } from '@datalayer/reactor';
 import { registerReactor, useBackendPluginStream, useReactorPlatform, useSignalValue, } from '@datalayer/reactor/react';
 import { IDLE_SANDBOX_SNAPSHOT_SIGNAL, IDLE_SANDBOX_TARGET_SIGNAL, LoopSlots, } from '../core';
 import { useOptionalSandboxService } from '../plugins/agents/useSandboxService';
@@ -38,7 +47,7 @@ export const APP_RUNTIME_PLUGIN_NAME = '@datalayer/loop-plugin-app-runtime';
 /** A host's answer to "is this runtime plugin running?", from a list. */
 const runningOf = (names) => (name) => names.includes(name);
 /** Follows the application's runtime, and tells the page what it holds. */
-export function AppRuntimePlugins({ appId }) {
+export function AppRuntimePlugins({ appId, pageSide = false, }) {
     const reactor = useReactorPlatform();
     const service = useOptionalSandboxService();
     const target = useSignalValue(service?.target ?? IDLE_SANDBOX_TARGET_SIGNAL);
@@ -64,11 +73,29 @@ export function AppRuntimePlugins({ appId }) {
     useBackendPluginStream(runtime ? appPluginsBase(runtime, appId) : undefined, {
         onState,
     });
+    // Its packaged page side, installed from its runtime (P-29): the
+    // application's extension only, whatever else the server holds.
+    useEffect(() => {
+        if (!runtime || !pageSide) {
+            return;
+        }
+        let current = true;
+        void bootstrapExtensions(appPluginsBase(runtime, appId)).then(found => {
+            for (const extension of found.filter(item => item.name === name)) {
+                if (current) {
+                    void reactor.install(extension);
+                }
+            }
+        });
+        return () => {
+            current = false;
+        };
+    }, [reactor, runtime, appId, name, pageSide]);
     return null;
 }
 /** The plugin that follows an application's runtime for its page. */
-export function defineAppRuntimePlugin(appId) {
-    const Follow = () => _jsx(AppRuntimePlugins, { appId: appId });
+export function defineAppRuntimePlugin(appId, { pageSide = false } = {}) {
+    const Follow = () => _jsx(AppRuntimePlugins, { appId: appId, pageSide: pageSide });
     return definePlugin({
         name: APP_RUNTIME_PLUGIN_NAME,
         displayName: 'Its runtime',

package/lib/apps/apps/customComponents.d.ts

@@ -7,10 +7,23 @@ export declare const CUSTOM_PROPERTY_TYPES: readonly ["string", "integer", "numb
 export declare const CUSTOM_RESERVED_NAMES: readonly ["id", "component", "action", "weight", "visible_when", "children", "child"];
 /**
  * Where its module is loaded from: an address served over HTTPS, or this
- * machine while it is written. A file of the application's folder waits for
- * its packaging (P-29).
+ * machine while it is written.
  */
 export declare const CUSTOM_SOURCE: RegExp;
+/**
+ * Or a file of the application's folder, by its path in it (LOOP P-29): a
+ * `.js` or `.mjs` file inside the folder — no absolute path, no `..`.
+ * Packaged with the application (`loop apps package`), it is served by the
+ * server its package is installed beside (`LoopAppFiles`).
+ */
+export declare const CUSTOM_FILE: RegExp;
+/** Whether a component's module is a file of its application's folder. */
+export declare const isFolderSource: (source: string) => boolean;
+/**
+ * The address a file of the folder is fetched from, under the base its
+ * package's page side said (`LoopAppFiles`).
+ */
+export declare const folderSourceUrl: (source: string, base: string) => string;
 /** A Subresource Integrity hash: the module as it was reviewed. */
 export declare const INTEGRITY: RegExp;
 /**
@@ -21,6 +34,11 @@ export declare const INTEGRITY: RegExp;
 export declare function customPropsRefused(component: AppCustomComponentSpec, props: Record<string, unknown>, bound?: readonly string[]): string[];
 /** What stops one component its developer wrote from being reviewed, in sentences. */
 export declare function customComponentProblems(component: AppCustomComponentSpec): string[];
+/**
+ * Whether an application's page side is packaged (LOOP P-29): a component
+ * its developer wrote is a file of its folder.
+ */
+export declare const hasFolderModules: (app: Pick<AppSpec, "interface">) => boolean;
 /** What stops the components an application's developer wrote, in sentences. */
 export declare function customComponentsProblems(app: AppSpec): string[];
 /** A component its developer wrote, by name, or undefined. */

package/lib/apps/apps/customComponents.js

@@ -40,10 +40,24 @@ export const CUSTOM_RESERVED_NAMES = [
 ];
 /**
  * Where its module is loaded from: an address served over HTTPS, or this
- * machine while it is written. A file of the application's folder waits for
- * its packaging (P-29).
+ * machine while it is written.
  */
 export const CUSTOM_SOURCE = /^(?:https:\/\/[A-Za-z0-9.-]+(?::\d+)?|http:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?)\/\S*$/;
+/**
+ * Or a file of the application's folder, by its path in it (LOOP P-29): a
+ * `.js` or `.mjs` file inside the folder — no absolute path, no `..`.
+ * Packaged with the application (`loop apps package`), it is served by the
+ * server its package is installed beside (`LoopAppFiles`).
+ */
+export const CUSTOM_FILE = /^(?:\.\/)?(?:[A-Za-z0-9_][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_][A-Za-z0-9_.-]*\.m?js$/;
+/** Whether a component's module is a file of its application's folder. */
+export const isFolderSource = (source) => !/^[a-z][a-z0-9+.-]*:/.test(source) && CUSTOM_FILE.test(source);
+/**
+ * The address a file of the folder is fetched from, under the base its
+ * package's page side said (`LoopAppFiles`).
+ */
+export const folderSourceUrl = (source, base) => new URL(source.replace(/^\.\//, ''), base.endsWith('/') ? base : `${base}/`)
+    .href;
 /** A Subresource Integrity hash: the module as it was reviewed. */
 export const INTEGRITY = /^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/;
 const PROPERTY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -117,7 +131,9 @@ export function customComponentProblems(component) {
         problems.push(`${said} says what it is for, under \`description\`.`);
     }
     if (!/^[a-z][a-z0-9+.-]*:/.test(component.source)) {
-        problems.push(`${said}'s module “${component.source}” is a file of the application's folder: it is drawn once the application is packaged with it (LOOP P-29); give the address of a built ES module.`);
+        if (!CUSTOM_FILE.test(component.source)) {
+            problems.push(`${said}'s module “${component.source}” is a file of the application's folder, named by its path in it: a \`.js\` or \`.mjs\` file inside the folder (\`gauge.js\`, \`components/gauge.js\`).`);
+        }
     }
     else if (!CUSTOM_SOURCE.test(component.source)) {
         problems.push(`${said}'s module “${component.source}” is loaded over \`https://\`, or from \`http://localhost\` while it is written.`);
@@ -197,6 +213,11 @@ export function customComponentProblems(component) {
     }
     return problems;
 }
+/**
+ * Whether an application's page side is packaged (LOOP P-29): a component
+ * its developer wrote is a file of its folder.
+ */
+export const hasFolderModules = (app) => (app.interface.customComponents ?? []).some(component => isFolderSource(component.source));
 /** What stops the components an application's developer wrote, in sentences. */
 export function customComponentsProblems(app) {
     const own = app.interface.customComponents ?? [];

package/lib/apps/core/appFiles.d.ts

@@ -0,0 +1,7 @@
+export type AppFilesContribution = {
+    /** The application whose folder it is, by id. */
+    app: string;
+    /** The absolute address its folder's files are served under, ending in `/`. */
+    base: string;
+};
+export declare const LoopAppFiles: import("@datalayer/reactor").ContributionPoint<AppFilesContribution>;

package/lib/apps/core/appFiles.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Where the files of an application's folder are served (LOOP P-29), as a
+ * contribution point, re-exported by `apps/core`.
+ *
+ * A component its developer wrote may be a file of its folder (`source:
+ * gauge.js`). `loop apps package` puts the folder's files in the
+ * application's wheel, beside a generated page-side plugin
+ * (`loop-app-<id>/page`, `agent_runtimes/loop/apps/packaging.py`) whose one
+ * contribution is to this point: the address its own directory is served at
+ * by the server the wheel is installed beside. The page installs that plugin
+ * through Reactor's `bootstrapExtensions` (`AppRuntimePlugins`), and a file
+ * of the folder is fetched from there and drawn in its sandboxed frame.
+ *
+ * The plugin is a plain object of no import, so the point is named by its
+ * id: `loop.app.files` is what the generated module says too.
+ *
+ * @module apps/core/appFiles
+ */
+import { defineContributionPoint } from '@datalayer/reactor';
+export const LoopAppFiles = defineContributionPoint('loop.app.files');

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

@@ -600,6 +600,7 @@ export declare const LoopAssistantMenu: import("@datalayer/reactor").Contributio
 export { LoopCanvasBlock, type CanvasBlockContribution } from './canvasBlocks';
 export { LoopCanvasPart, type CanvasPartContribution, type CanvasPartKind, } from './canvasParts';
 export { LoopA2uiComponent, type A2uiComponentContribution, } from './a2uiComponents';
+export { LoopAppFiles, type AppFilesContribution } from './appFiles';
 /**
  * The per-example chat extras a host feeds the loop's conversation live.
  *

package/lib/apps/core/index.js

@@ -178,6 +178,9 @@ export { LoopCanvasPart, } from './canvasParts';
 // A component an application adds to the catalog it is drawn with (LOOP
 // P-17): the components its developer wrote, for its workspace alone.
 export { LoopA2uiComponent, } from './a2uiComponents';
+// Where the files of an application's folder are served (LOOP P-29): said
+// by the page side its package carries.
+export { LoopAppFiles } from './appFiles';
 export const LoopChatExtras = defineContributionPoint('loop.chat.extras');
 export const LoopOpeningNotebook = defineContributionPoint('loop.notebook.opening');
 export const LoopOpeningDocument = defineContributionPoint('loop.document.opening');

package/lib/apps/embed/AppEmbed.js

@@ -359,7 +359,11 @@ export function EmbedThemed({ accent, colorMode, font, variant, children, style,
     _jsx("div", { "data-color-mode": colorMode, style: { display: 'contents' }, children: _jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: getThemeConfig(variant).primerTheme, themeStyles: themeStyles, baseStyles: style, children: children }) }));
 }
 export function AppEmbed({ app, mode, accent, colorMode, font, language, serverUrl, instance, embedToken, visitors, height = 640, ownPortal = false, plugins = NO_PLUGINS, host, resume = true, }) {
-    const bridge = useHostBridge(app, host);
+    const shownAs = mode ?? app.deployment.embedded?.mode ?? 'inline';
+    // Inline, the page is bridged here; in a bubble, a panel or the assistant,
+    // `AppFloating` bridges it itself. Bridged twice, every window message of a
+    // turn reached the page twice (seen 2026-10-10 with P-27's copilot).
+    const bridge = useHostBridge(app, shownAs === 'inline' ? host : undefined);
     // Where a visitor without an account runs it (D-07): one object, so that
     // the renderer never reads a change.
     const renderer = useMemo(() => (visitors ? { datalayerVisitors: visitors } : undefined), [visitors]);
@@ -377,7 +381,6 @@ export function AppEmbed({ app, mode, accent, colorMode, font, language, serverU
     const variant = app.interface.theme?.variant ?? 'loop';
     const asked = colorMode ?? app.interface.theme?.mode ?? 'auto';
     const resolvedMode = asked === 'auto' ? system : asked;
-    const shownAs = mode ?? app.deployment.embedded?.mode ?? 'inline';
     const view = floatingViewOf(shownAs);
     const worn = accent ?? app.interface.accent;
     const themeOverrides = useMemo(() => embedThemeOverrides({ accent: worn, font, variant }), [worn, font, variant]);

package/lib/apps/index.d.ts

@@ -76,4 +76,4 @@ export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSn
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 export { loopPlugins, type LoopPresetOptions } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, type AppCheck, type CheckContext, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, pageOutputShows, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, type AppCheck, type CheckContext, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, folderSourceUrl, hasFolderModules, isFolderSource, pageOutputShows, } from './apps';

package/lib/apps/index.js

@@ -103,4 +103,4 @@ export { loopPlugins } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
 // Applications: what one does when its agent calls a tool — the rules a
 // person wrote, decided on what the tool does.
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, defineAppPlugin, appLayoutOptions, readAppspecYaml, writeAppspecYaml, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, pageOutputShows, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, defineAppPlugin, appLayoutOptions, readAppspecYaml, writeAppspecYaml, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, folderSourceUrl, hasFolderModules, isFolderSource, pageOutputShows, } from './apps';

package/lib/apps/plugins/app-components/index.js

@@ -49,7 +49,7 @@ export function defineAppComponentsPlugin(app, fetcher) {
             contribution(LoopA2uiComponent, {
                 id: component.name,
                 app: app.id,
-                implementation: customImplementation(component, app.version, fetcher),
+                implementation: customImplementation(component, app.version, fetcher, app.id),
             }, { id: component.name }),
         ]),
     });

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

@@ -21,19 +21,31 @@ type CustomProps = Record<string, unknown> & {
 };
 /** 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>;
+/**
+ * Where the files of an application's folder are served, as its package's
+ * page side said (`LoopAppFiles`, LOOP P-29); undefined until it says it —
+ * while its runtime starts, or for ever on a server it is not installed
+ * beside.
+ */
+export declare function useAppFilesBase(appId: string): string | undefined;
 /** A component its developer wrote, in its frame. */
-export declare function CustomComponentView({ component, props, fetcher, }: {
+export declare function CustomComponentView({ component, props, fetcher, appId, }: {
     component: AppCustomComponentSpec;
     props: CustomProps;
     /** How its module is fetched; the page's `fetch` unless given (tests). */
     fetcher?: typeof fetch;
+    /**
+     * Its application's id: where a module that is a file of its folder is
+     * served is said for that application (LOOP P-29).
+     */
+    appId?: string;
 }): 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;
+export declare function customImplementation(component: AppCustomComponentSpec, version?: string, fetcher?: typeof fetch, appId?: string): 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 declare function customImplementations(app: Pick<AppSpec, 'id' | 'interface' | 'version'>, fetcher?: typeof fetch): ReactComponentImplementation[];
 export { CUSTOM_FRAME_SANDBOX, customFrameDocument, customFramePolicy, customModule, fromFrame, integrityHolds, } from './sandbox';

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

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { useOptionalReactorPlatform } from '@datalayer/reactor/react';
 import { createComponentImplementation, } from '@a2ui/react/v0_9';
-import { customComponentEntry } from '../../../apps/apps/customComponents';
+import { customComponentEntry, folderSourceUrl, isFolderSource, } from '../../../apps/apps/customComponents';
+import { LoopAppFiles } from '../../../apps/core/appFiles';
 import { componentSchemaOf } from '../datalayer/schema';
 import { BlockFrame, Problem } from '../datalayer/parts';
 import { CUSTOM_FRAME_SANDBOX, FRAME_TAG, customFrameDocument, customModule, frameNonce, fromFrame, } from './sandbox';
@@ -13,11 +15,37 @@ export function givenToFrame(component, props) {
 }
 /** The setter A2UI gives a binding: `setValue` for `value`. */
 const setterOf = (name) => `set${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+/**
+ * Where the files of an application's folder are served, as its package's
+ * page side said (`LoopAppFiles`, LOOP P-29); undefined until it says it —
+ * while its runtime starts, or for ever on a server it is not installed
+ * beside.
+ */
+export function useAppFilesBase(appId) {
+    const reactor = useOptionalReactorPlatform();
+    const subscribe = useCallback((listener) => reactor ? reactor.subscribe(listener) : () => undefined, [reactor]);
+    const revision = useSyncExternalStore(subscribe, () => reactor?.getRevision() ?? 0);
+    return useMemo(() => reactor
+        ?.getContributions(LoopAppFiles)
+        .find(entry => entry.value.app === appId)?.value.base, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [reactor, revision, appId]);
+}
 /** A component its developer wrote, in its frame. */
-export function CustomComponentView({ component, props, fetcher, }) {
+export function CustomComponentView({ component, props, fetcher, appId = '', }) {
     const frame = useRef(null);
     const [problem, setProblem] = useState(null);
     const [ready, setReady] = useState(false);
+    const [frameReady, setFrameReady] = useState(false);
+    // Its module's address: its own, or a file of its folder under the base
+    // its package's page side said — none until said.
+    const folder = isFolderSource(component.source);
+    const base = useAppFilesBase(appId);
+    const source = folder
+        ? base
+            ? folderSourceUrl(component.source, base)
+            : undefined
+        : component.source;
     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));
@@ -32,17 +60,7 @@ export function CustomComponentView({ component, props, fetcher, }) {
                 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)));
+                setFrameReady(true);
             }
             else if (said.kind === 'failed') {
                 setProblem(`It could not be drawn: ${said.message}.`);
@@ -62,13 +80,41 @@ export function CustomComponentView({ component, props, fetcher, }) {
         };
         window.addEventListener('message', listen);
         return () => window.removeEventListener('message', listen);
-    }, [component, fetcher]);
+    }, [component]);
+    // Its module, handed over once the frame is ready and its address known.
+    useEffect(() => {
+        if (!frameReady || !source) {
+            return;
+        }
+        let current = true;
+        customModule(source, component.integrity, fetcher)
+            .then(code => {
+            if (!current) {
+                return;
+            }
+            tell({
+                tag: FRAME_TAG,
+                kind: 'props',
+                props: givenToFrame(component, propsRef.current),
+            });
+            tell({ tag: FRAME_TAG, kind: 'module', code });
+            setReady(true);
+        })
+            .catch((error) => {
+            if (current) {
+                setProblem(error instanceof Error ? error.message : String(error));
+            }
+        });
+        return () => {
+            current = false;
+        };
+    }, [frameReady, source, component, fetcher]);
     useEffect(() => {
         if (ready) {
             tell({ tag: FRAME_TAG, kind: 'props', props: given });
         }
     }, [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: {
+    return (_jsxs(BlockFrame, { label: component.description || component.name, weight: props.weight, testId: `custom-${component.name}`, children: [problem ? _jsx(Problem, { children: problem }) : null, !problem && folder && !source ? (_jsx(Problem, { children: `Its module “${component.source}” is a file of its application's folder: it is drawn once the server running the application serves its package (loop apps package, installed beside that server).` })) : 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,
@@ -80,14 +126,14 @@ export function CustomComponentView({ component, props, fetcher, }) {
  * schema from its declaration, its view by A2UI's own factory, drawn in its
  * frame.
  */
-export function customImplementation(component, version = '0.0.0', fetcher) {
+export function customImplementation(component, version = '0.0.0', fetcher, appId = '') {
     const entry = customComponentEntry(component, version);
     const api = { name: component.name, schema: componentSchemaOf(entry) };
-    const Render = ({ props }) => (_jsx(CustomComponentView, { component: component, props: props, fetcher: fetcher }));
+    const Render = ({ props }) => (_jsx(CustomComponentView, { component: component, props: props, fetcher: fetcher, appId: appId }));
     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));
+    return (app.interface.customComponents ?? []).map(component => customImplementation(component, app.version, fetcher, app.id));
 }
 export { CUSTOM_FRAME_SANDBOX, customFrameDocument, customFramePolicy, customModule, fromFrame, integrityHolds, } from './sandbox';

package/lib/specs/appspecSchema.js

@@ -269,7 +269,7 @@ export const APPSPEC_SCHEMA = {
                     type: 'array',
                 },
                 source: {
-                    description: "The address of its module, a built ES module whose default export draws it (`export default function (root, {props, send})`): over `https://`, or `http://localhost` while it is written. A module of the application's folder waits for its packaging (LOOP P-29)",
+                    description: "Its module, a built ES module whose default export draws it (`export default function (root, {props, send})`): an address over `https://`, or `http://localhost` while it is written; or a file of the application's folder, by its path in it (`gauge.js`), packaged with the application and served by the server its package is installed beside (LOOP P-29)",
                     title: 'Source',
                     type: 'string',
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.97",
+    "version": "1.3.98",
     "type": "module",
     "workspaces": [
         ".",