@braidlabs/console 0.7.1 → 0.8.1

package/src/lib/styles.js

@@ -488,6 +488,16 @@ export const CONSOLE_STYLES = `
 .braid-console__area:focus-visible { outline: 2px solid var(--bc-accent); outline-offset: 1px; }
 .braid-console__areaname { font-family: var(--bc-mono); font-size: 11px; opacity: 0.85; }
 .braid-console__areafragment { font-family: var(--bc-mono); font-size: 13px; font-weight: 600; }
+.braid-console__area.is-workspace {
+  border: 1px solid var(--bc-accent); color: var(--bc-text);
+  background: repeating-linear-gradient(135deg, var(--bc-surface) 0 10px, var(--bc-surface-alt) 10px 20px);
+}
+.braid-console__areaapps { display: flex; flex-wrap: wrap; gap: 4px; font-family: var(--bc-mono); font-size: 12px; }
+.braid-console__areaapps > span { padding: 1px 6px; border: 1px solid var(--bc-border-strong); border-radius: 999px; background: var(--bc-bg); }
+.braid-console__areaapps > em { color: var(--bc-muted); }
+.braid-console__applist { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; font-size: 13px; }
+.braid-console__applist > li { display: flex; align-items: center; gap: 6px; }
+.braid-console__preview > .braid-console__check { align-items: baseline; padding-bottom: 0; }
 .braid-console__head { border: 1px solid var(--bc-border); border-radius: var(--bc-radius); margin: 0; }
 .braid-console__head .braid-console__notice, .braid-console__subhead, .braid-console__head > .braid-console__desc, .braid-console__add { grid-column: 1 / -1; }
 .braid-console__subhead { margin: 6px 0 0; font-size: 13px; font-weight: 600; }

package/src/lib/styles.js.map

@@ -1 +1 @@
-{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/lib/styles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqf7B,GAAG,UAAU,CAAC;AAEf,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,MAAgB,QAAQ;IACnD,IAAI,GAAG,CAAC,cAAc,CAAC,gBAAgB,CAAC;QAAE,OAAO;IAEjD,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,GAAG,gBAAgB,CAAC;IAC5B,KAAK,CAAC,WAAW,GAAG,cAAc,CAAC;IACnC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/lib/styles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+f7B,GAAG,UAAU,CAAC;AAEf,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,MAAgB,QAAQ;IACnD,IAAI,GAAG,CAAC,cAAc,CAAC,gBAAgB,CAAC;QAAE,OAAO;IAEjD,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,GAAG,gBAAgB,CAAC;IAC5B,KAAK,CAAC,WAAW,GAAG,cAAc,CAAC;IACnC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}

package/src/workspace/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where the workspace keeps what it remembers for a user: intent choices, host preferences, each
+ * app's settings and saved layouts. Values are JSON; keys are `/`-separated paths such as
+ * `apps/billing/theme` (see {@link isStoreKey}).
+ *
+ * Two are provided, and any other storage can implement the interface:
+ *
+ * - {@link localStorageStore} — in the browser, for this origin and browser profile.
+ * - {@link serverStore} — on the gateway (`createGateway({ preferences })`), keyed by the
+ *   signed-in user, so it follows them to any browser.
+ */
+export interface PreferenceStore {
+    /** The value, or undefined when there is none. */
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys that start with `prefix`, sorted. */
+    list(prefix: string): Promise<string[]>;
+}
+/**
+ * Whether `key` can be stored: up to 512 characters in at most eight `/`-separated segments of
+ * `A-Z a-z 0-9 . _ ~ % -`, none of them `.` or `..`. The gateway checks the same rule.
+ */
+export declare function isStoreKey(key: string): boolean;
+/** A segment for a store key from any string — a layout's name, an intent, an app id. */
+export declare function keySegment(value: string): string;
+/** Entries in memory, gone on reload. For tests, and where nothing should persist. */
+export declare function memoryStore(): PreferenceStore;
+export interface LocalStorageStoreOptions {
+    /** Prepended to every key in `localStorage`, so the workspace's entries stay apart from the page's. Defaults to `braid.workspace/`. */
+    prefix?: string;
+    /** Defaults to `localStorage`. */
+    storage?: Storage;
+}
+/**
+ * Entries in `localStorage`: per origin and browser profile, kept across reloads. Where
+ * `localStorage` is unavailable (blocked, or not a browser) it keeps them in memory instead, so a
+ * page never fails to compose over its preferences.
+ */
+export declare function localStorageStore(options?: LocalStorageStoreOptions): PreferenceStore;
+export interface ServerStoreOptions {
+    /** The gateway's preferences endpoint. Defaults to `/__braid/preferences`. */
+    url?: string;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Entries on the gateway (`createGateway({ preferences })`), keyed by the signed-in user: they
+ * follow the user to any browser. Requests carry the page's cookies (`credentials: 'same-origin'`);
+ * a failed request rejects with the status, so the caller sees it rather than silently losing a
+ * write.
+ */
+export declare function serverStore(options?: ServerStoreOptions): PreferenceStore;

package/src/workspace/store.js

@@ -0,0 +1,139 @@
+const SEGMENT = /^[A-Za-z0-9._~%-]{1,128}$/;
+/**
+ * Whether `key` can be stored: up to 512 characters in at most eight `/`-separated segments of
+ * `A-Z a-z 0-9 . _ ~ % -`, none of them `.` or `..`. The gateway checks the same rule.
+ */
+export function isStoreKey(key) {
+    if (key.length === 0 || key.length > 512)
+        return false;
+    const segments = key.split('/');
+    return segments.length <= 8 && segments.every((segment) => SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+}
+/** A segment for a store key from any string — a layout's name, an intent, an app id. */
+export function keySegment(value) {
+    // encodeURIComponent leaves only A-Z a-z 0-9 - _ . ! ~ * ' ( ) unescaped; escape the rest of those too
+    const encoded = encodeURIComponent(value).replace(/[!*'()]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return encoded === '.' ? '%2E' : encoded === '..' ? '%2E%2E' : encoded || '%00';
+}
+function checkKey(key) {
+    if (!isStoreKey(key))
+        throw new TypeError(`braid-workspace: "${key}" is not a store key`);
+}
+/** A JSON round trip: what a store holds is data, never a live object shared with the caller. */
+function toJson(value) {
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new TypeError('braid-workspace: a stored value must be JSON');
+    return json;
+}
+/** Entries in memory, gone on reload. For tests, and where nothing should persist. */
+export function memoryStore() {
+    const entries = new Map();
+    return {
+        async get(key) {
+            checkKey(key);
+            const json = entries.get(key);
+            return json === undefined ? undefined : JSON.parse(json);
+        },
+        async set(key, value) {
+            checkKey(key);
+            entries.set(key, toJson(value));
+        },
+        async delete(key) {
+            checkKey(key);
+            entries.delete(key);
+        },
+        async list(prefix) {
+            return [...entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+        },
+    };
+}
+/**
+ * Entries in `localStorage`: per origin and browser profile, kept across reloads. Where
+ * `localStorage` is unavailable (blocked, or not a browser) it keeps them in memory instead, so a
+ * page never fails to compose over its preferences.
+ */
+export function localStorageStore(options = {}) {
+    const prefix = options.prefix ?? 'braid.workspace/';
+    let storage;
+    try {
+        storage = options.storage ?? globalThis.localStorage;
+    }
+    catch {
+        // reading localStorage throws a SecurityError where storage is blocked
+    }
+    if (!storage)
+        return memoryStore();
+    const local = storage;
+    return {
+        async get(key) {
+            checkKey(key);
+            const json = local.getItem(prefix + key);
+            if (json === null)
+                return undefined;
+            try {
+                return JSON.parse(json);
+            }
+            catch {
+                // someone else's write under our prefix: not ours to interpret
+                return undefined;
+            }
+        },
+        async set(key, value) {
+            checkKey(key);
+            local.setItem(prefix + key, toJson(value));
+        },
+        async delete(key) {
+            checkKey(key);
+            local.removeItem(prefix + key);
+        },
+        async list(keyPrefix) {
+            const keys = [];
+            for (let index = 0; index < local.length; index++) {
+                const name = local.key(index);
+                if (name?.startsWith(prefix + keyPrefix) && isStoreKey(name.slice(prefix.length)))
+                    keys.push(name.slice(prefix.length));
+            }
+            return keys.sort();
+        },
+    };
+}
+/**
+ * Entries on the gateway (`createGateway({ preferences })`), keyed by the signed-in user: they
+ * follow the user to any browser. Requests carry the page's cookies (`credentials: 'same-origin'`);
+ * a failed request rejects with the status, so the caller sees it rather than silently losing a
+ * write.
+ */
+export function serverStore(options = {}) {
+    const base = (options.url ?? '/__braid/preferences').replace(/\/+$/, '');
+    const send = (input, init = {}) => (options.fetch ?? globalThis.fetch)(input, { credentials: 'same-origin', cache: 'no-store', ...init });
+    const url = (key) => {
+        checkKey(key);
+        return `${base}/${key.split('/').map(encodeURIComponent).join('/')}`;
+    };
+    async function ok(response, what) {
+        if (!response.ok)
+            throw new Error(`braid-workspace: ${what} failed with ${response.status}`);
+        return response;
+    }
+    return {
+        async get(key) {
+            const response = await send(url(key), { headers: { accept: 'application/json' } });
+            if (response.status === 404)
+                return undefined;
+            return (await ok(response, `reading "${key}"`)).json();
+        },
+        async set(key, value) {
+            await ok(await send(url(key), { method: 'PUT', headers: { 'content-type': 'application/json' }, body: toJson(value) }), `writing "${key}"`);
+        },
+        async delete(key) {
+            await ok(await send(url(key), { method: 'DELETE' }), `deleting "${key}"`);
+        },
+        async list(prefix) {
+            const response = await ok(await send(`${base}?prefix=${encodeURIComponent(prefix)}`), `listing "${prefix}"`);
+            const { keys } = (await response.json());
+            return Array.isArray(keys) ? keys.filter((key) => typeof key === 'string').sort() : [];
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/src/workspace/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/workspace/store.ts"],"names":[],"mappings":"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"}

package/src/workspace/workspace.d.ts

@@ -0,0 +1,159 @@
+import { type PreferenceStore } from './store.js';
+/**
+ * A workspace for one Braid page: an area of the page where apps are launched as
+ * `<fragment-slot>`s, plus what the page remembers for its user — preferences, each app's
+ * settings, and named layouts of that area.
+ *
+ * It is a feature of the page, not of any interop standard, and needs none: with no FDC3 agent it
+ * launches, saves and restores plain fragments. Beside `@braidlabs/fdc3` it composes around the
+ * agent through the agent's two hooks, and adds what FDC3 leaves to the platform:
+ *
+ * ```ts
+ * const workspace = createWorkspace();                       // the page's [data-braid-workspace]
+ * const agent = createBraidDesktopAgent({
+ *   directory,
+ *   ...workspace.fdc3(dialogResolver(document, { remember: true })),
+ * });
+ * initBraid({ realmGlobals: workspace.realmGlobals(agent.realmGlobals) });
+ * ```
+ */
+export interface WorkspaceOptions {
+    /**
+     * The workspace area: launched apps are mounted here, and a layout is its `<fragment-slot>`
+     * children. Defaults to the page's `[data-braid-workspace]` element, which is what a shell
+     * designed in the console with a workspace area renders — looked up when first needed, so a
+     * framework may render it after the workspace is created. `null` is no area. Without one,
+     * preferences and app settings still work; launching and layouts reject.
+     */
+    container?: Element | null;
+    /**
+     * Where preferences, app settings and layouts are kept. Defaults to {@link localStorageStore};
+     * {@link serverStore} keeps them on the gateway, per signed-in user.
+     */
+    store?: PreferenceStore;
+}
+/** The user's preferences for the whole page. */
+export interface HostPreferences {
+    /** An FDC3 user channel id (`fdc3.channel.1`…`8`) every fragment joins before its code runs. Needs an FDC3 agent. */
+    defaultUserChannel?: string;
+    /** App ids never offered as a choice when resolving an intent. */
+    hiddenApps?: string[];
+}
+/** What {@link Workspace.layouts} saves: the workspace area's slots, in order. */
+export interface SavedLayout {
+    version: 1;
+    savedAt: string;
+    slots: SavedSlot[];
+}
+export interface SavedSlot {
+    appId: string;
+    src?: string;
+    props?: Record<string, unknown>;
+    /** The FDC3 user channel the instance was on, when the page runs an agent. */
+    channel?: string;
+    /** What the app returned from `braidDesktop.onSaveLayout`. */
+    state?: unknown;
+}
+/** The workspace's additions for one fragment, as `window.braidDesktop`. */
+export interface BraidDesktopApi {
+    /** This app's settings for the signed-in user: shared by its instances, apart from other apps'. */
+    settings: {
+        get(key: string): Promise<unknown>;
+        set(key: string, value: unknown): Promise<void>;
+        delete(key: string): Promise<void>;
+        keys(): Promise<string[]>;
+    };
+    /**
+     * Supplies this instance's state when the workspace's layout is saved: JSON, within 2 seconds.
+     * The handler registered last is the one asked. Returns an unsubscribe.
+     */
+    onSaveLayout(handler: () => unknown): () => void;
+    /** The state this instance saved, when it was mounted by restoring a layout; otherwise undefined. */
+    readonly restoredState: unknown;
+}
+/** What `initBraid({ realmGlobals })` calls for each fragment. */
+export interface WorkspaceFragment {
+    fragmentId: string;
+    signal: AbortSignal;
+    /** The `<fragment-slot>` the fragment boots in. */
+    slot?: Element;
+}
+/** A `realmGlobals` hook, such as an FDC3 agent's. */
+export type RealmGlobals<F extends WorkspaceFragment = WorkspaceFragment> = (fragment: F) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+/** The parts of an intent candidate the workspace reads; an FDC3 agent's `IntentCandidate` is one. */
+export interface WorkspaceIntentCandidate {
+    intent: string;
+    appId: string;
+    instanceId?: string;
+}
+/** An intent resolver hook, as `createBraidDesktopAgent({ resolveIntent })` takes. */
+export type WorkspaceIntentResolver<C extends WorkspaceIntentCandidate, R extends {
+    context?: {
+        type?: unknown;
+    };
+    candidates: C[];
+}> = (request: R) => Promise<{
+    candidate: C;
+    remember?: boolean;
+} | undefined>;
+export interface Workspace {
+    /** The workspace area, or undefined when the page has none. */
+    readonly container: Element | undefined;
+    /**
+     * The hook for `initBraid({ realmGlobals })`. Every fragment gets `braidDesktop`, on top of
+     * whatever `inner` gives it — pass an FDC3 agent's `realmGlobals` and a fragment with an `fdc3`
+     * also joins its saved channel, or the user's default one, before any of its code runs.
+     */
+    realmGlobals<F extends WorkspaceFragment>(inner?: RealmGlobals<F>): (fragment: F) => Promise<Record<string, unknown>>;
+    /**
+     * Wraps an intent resolver with the user's preferences: hidden apps are never offered, a
+     * remembered choice answers without asking, and an answer with `remember: true` is kept.
+     * Without `inner`, a raise that still has several candidates is cancelled.
+     *
+     * Hiding governs the choice, not delivery: an agent asks a resolver only when several apps
+     * could take an intent, so an app that is the only one able to still gets it.
+     */
+    intentResolver<C extends WorkspaceIntentCandidate, R extends {
+        context?: {
+            type?: unknown;
+        };
+        candidates: C[];
+    }>(inner?: WorkspaceIntentResolver<C, R>): WorkspaceIntentResolver<C, R>;
+    /**
+     * The options that put an FDC3 agent on this workspace, to spread into
+     * `createBraidDesktopAgent({ directory, ...workspace.fdc3(resolver) })`: the agent launches into
+     * the workspace area (looked up at each launch, so a framework may render it late), and `inner`
+     * is wrapped as {@link Workspace.intentResolver} does.
+     */
+    fdc3<C extends WorkspaceIntentCandidate, R extends {
+        context?: {
+            type?: unknown;
+        };
+        candidates: C[];
+    }>(inner?: WorkspaceIntentResolver<C, R>): {
+        container: () => Element | undefined;
+        resolveIntent: WorkspaceIntentResolver<C, R>;
+    };
+    /** Mounts an app at the end of the workspace area, and returns its `<fragment-slot>`. */
+    open(appId: string, options?: {
+        src?: string;
+        props?: Record<string, unknown>;
+    }): Element;
+    preferences: {
+        getHost(): Promise<HostPreferences>;
+        /** Replaces the page's preferences; fragments that boot from now on get them. */
+        setHost(preferences: HostPreferences): Promise<void>;
+        /** The app remembered for an intent and context type, if any. */
+        intentChoice(intent: string, contextType: string): Promise<string | undefined>;
+        forgetIntentChoice(intent: string, contextType: string): Promise<void>;
+    };
+    /** Saved layouts of the workspace area. */
+    layouts: {
+        save(name: string): Promise<SavedLayout>;
+        /** Replaces the area's slots with the saved ones. Rejects if there is no such layout. */
+        restore(name: string): Promise<void>;
+        list(): Promise<string[]>;
+        delete(name: string): Promise<void>;
+    };
+}
+export declare function createWorkspace(options?: WorkspaceOptions): Workspace;

package/src/workspace/workspace.js

@@ -0,0 +1,274 @@
+import { keySegment, localStorageStore } from './store.js';
+/** How long saving a layout waits for each app's state. */
+const SAVE_STATE_TIMEOUT_MS = 2_000;
+/** How long a fragment's boot waits to read the page's preferences before going without. */
+const HOST_READ_TIMEOUT_MS = 1_000;
+/** How long a fragment's boot waits to join its channel. */
+const JOIN_TIMEOUT_MS = 2_000;
+const HOST_KEY = 'host';
+const intentKey = (intent, contextType) => `intents/${keySegment(intent)}/${keySegment(contextType)}`;
+const layoutKey = (name) => `layouts/${keySegment(name)}`;
+const appPrefix = (appId) => `apps/${keySegment(appId)}/`;
+export function createWorkspace(options = {}) {
+    let found;
+    /** The area: the one given, or the page's, once it is there. */
+    const area = () => {
+        if (options.container !== undefined)
+            return options.container ?? undefined;
+        if (!found?.isConnected)
+            found = (typeof document === 'undefined' ? null : document.querySelector('[data-braid-workspace]')) ?? undefined;
+        return found;
+    };
+    const store = options.store ?? localStorageStore();
+    /** What a slot mounted by a restore gives its fragment when it boots. */
+    const restores = new WeakMap();
+    /** Booted fragments, by the slot they are in. */
+    const bySlot = new WeakMap();
+    /**
+     * The page's preferences, read once and kept: every fragment's boot waits on them, so a slow
+     * store must not slow every boot. A read that fails or takes too long is no preferences — not a
+     * fragment that fails to boot — and is tried again next time.
+     */
+    let host;
+    function hostPreferences() {
+        host ??= withTimeout(store.get(HOST_KEY), HOST_READ_TIMEOUT_MS).then((stored) => (stored && typeof stored === 'object' ? stored : {}), () => {
+            host = undefined;
+            return {};
+        });
+        return host;
+    }
+    /**
+     * The remembered app's candidate: its one running instance, or the app itself when it is not
+     * running. Anything else — two instances, or the app no longer a candidate — is the user's call.
+     */
+    async function remembered(candidates, contextType) {
+        const matches = [];
+        for (const intent of new Set(candidates.map((candidate) => candidate.intent))) {
+            let appId;
+            try {
+                appId = (await store.get(intentKey(intent, contextType)))?.appId;
+            }
+            catch {
+                continue;
+            }
+            const ofApp = candidates.filter((candidate) => candidate.intent === intent && candidate.appId === appId);
+            const running = ofApp.filter((candidate) => candidate.instanceId);
+            const pick = running.length === 1 ? running[0] : running.length === 0 && ofApp.length === 1 ? ofApp[0] : undefined;
+            if (pick)
+                matches.push(pick);
+        }
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    function braidDesktopFor(appId, instance, restoredState) {
+        const prefix = appPrefix(appId);
+        return Object.freeze({
+            settings: Object.freeze({
+                get: (key) => store.get(prefix + keySegment(String(key))),
+                set: (key, value) => store.set(prefix + keySegment(String(key)), value),
+                delete: (key) => store.delete(prefix + keySegment(String(key))),
+                keys: async () => decodedSegments(await store.list(prefix), prefix),
+            }),
+            onSaveLayout(handler) {
+                if (typeof handler !== 'function')
+                    throw new TypeError('braidDesktop.onSaveLayout takes a function');
+                instance.saveHandlers.add(handler);
+                return () => void instance.saveHandlers.delete(handler);
+            },
+            restoredState: restoredState === undefined ? undefined : structuredClone(restoredState),
+        });
+    }
+    function needContainer() {
+        const container = area();
+        if (!container) {
+            throw new Error('braid-workspace: the page has no workspace area (createWorkspace({ container }), or a [data-braid-workspace] element)');
+        }
+        return container;
+    }
+    /** The state an instance gives for a layout: JSON, within the timeout, or nothing. */
+    async function stateOf(instance) {
+        const handler = instance && [...instance.saveHandlers].at(-1);
+        if (!handler)
+            return undefined;
+        try {
+            const state = await withTimeout(Promise.resolve().then(handler), SAVE_STATE_TIMEOUT_MS);
+            return state === undefined ? undefined : JSON.parse(JSON.stringify(state));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function savedSlot(slot) {
+        const saved = { appId: slot.getAttribute('name') };
+        const instance = bySlot.get(slot);
+        const src = slot.getAttribute('src');
+        if (src !== null)
+            saved.src = src;
+        const props = slot.props;
+        if (props && typeof props === 'object' && Object.keys(props).length > 0)
+            saved.props = JSON.parse(JSON.stringify(props));
+        const fdc3 = instance?.fdc3;
+        const [channel, state] = await Promise.all([
+            fdc3 ? withTimeout(fdc3.getCurrentChannel(), SAVE_STATE_TIMEOUT_MS).catch(() => null) : null,
+            stateOf(instance),
+        ]);
+        if (channel?.type === 'user' && typeof channel.id === 'string')
+            saved.channel = channel.id;
+        if (state !== undefined)
+            saved.state = state;
+        return saved;
+    }
+    /** The candidates left once the user's hidden apps are taken out. */
+    async function visible(candidates) {
+        const { hiddenApps = [] } = await hostPreferences();
+        const hidden = Array.isArray(hiddenApps) ? hiddenApps : [];
+        return candidates.filter((candidate) => !hidden.includes(candidate.appId));
+    }
+    const workspace = {
+        get container() {
+            return area();
+        },
+        fdc3(inner) {
+            return { container: area, resolveIntent: workspace.intentResolver(inner) };
+        },
+        realmGlobals(inner) {
+            return async (fragment) => {
+                const { fragmentId, signal, slot } = fragment;
+                // a hook that fails has given nothing: the fragment still gets its braidDesktop
+                const globals = (inner ? await Promise.resolve(inner(fragment)).catch(() => undefined) : undefined) ?? {};
+                const restore = slot ? restores.get(slot) : undefined;
+                const fdc3 = isFdc3(globals.fdc3) ? globals.fdc3 : undefined;
+                if (fdc3 && !signal.aborted) {
+                    const channel = restore?.channel ?? (await hostPreferences()).defaultUserChannel;
+                    // a channel the agent does not have, or one slow to join, is no channel
+                    if (typeof channel === 'string')
+                        await withTimeout(fdc3.joinUserChannel(channel), JOIN_TIMEOUT_MS).catch(() => undefined);
+                }
+                const instance = { ...(fdc3 ? { fdc3 } : {}), saveHandlers: new Set() };
+                if (slot && !signal.aborted) {
+                    restores.delete(slot);
+                    bySlot.set(slot, instance);
+                    signal.addEventListener('abort', () => void (bySlot.get(slot) === instance && bySlot.delete(slot)), { once: true });
+                }
+                return { ...globals, braidDesktop: braidDesktopFor(fragmentId, instance, restore?.state) };
+            };
+        },
+        intentResolver(inner) {
+            return async (request) => {
+                const candidates = await visible(request.candidates);
+                if (candidates.length === 0)
+                    return undefined;
+                if (candidates.length === 1)
+                    return { candidate: candidates[0] };
+                const contextType = typeof request.context?.type === 'string' ? request.context.type : 'fdc3.nothing';
+                const known = await remembered(candidates, contextType);
+                if (known)
+                    return { candidate: known };
+                const answer = await inner?.({ ...request, candidates });
+                if (!answer)
+                    return undefined;
+                // only what was offered is remembered: the agent refuses anything else anyway
+                const offered = candidates.find((candidate) => candidate.intent === answer.candidate?.intent &&
+                    candidate.appId === answer.candidate.appId &&
+                    (candidate.instanceId ?? null) === (answer.candidate.instanceId ?? null));
+                if (offered && answer.remember)
+                    await store.set(intentKey(offered.intent, contextType), { appId: offered.appId }).catch(() => undefined);
+                return answer;
+            };
+        },
+        open(appId, app = {}) {
+            if (typeof appId !== 'string' || appId === '')
+                throw new TypeError('braid-workspace: open takes an app id');
+            return mountSlot(needContainer(), { appId, ...app });
+        },
+        preferences: {
+            getHost: hostPreferences,
+            async setHost(preferences) {
+                const value = JSON.parse(JSON.stringify(preferences ?? {}));
+                await store.set(HOST_KEY, value);
+                host = Promise.resolve(value);
+            },
+            async intentChoice(intent, contextType) {
+                const stored = (await store.get(intentKey(intent, contextType)));
+                return typeof stored?.appId === 'string' ? stored.appId : undefined;
+            },
+            async forgetIntentChoice(intent, contextType) {
+                await store.delete(intentKey(intent, contextType));
+            },
+        },
+        layouts: {
+            async save(name) {
+                // every app at once: one that is slow to give its state does not hold up the rest
+                const named = slotsIn(needContainer()).filter((slot) => slot.getAttribute('name'));
+                const layout = { version: 1, savedAt: new Date().toISOString(), slots: await Promise.all(named.map(savedSlot)) };
+                await store.set(layoutKey(name), layout);
+                return layout;
+            },
+            async restore(name) {
+                const target = needContainer();
+                const layout = (await store.get(layoutKey(name)));
+                if (!layout || layout.version !== 1 || !Array.isArray(layout.slots)) {
+                    throw new Error(`braid-workspace: no saved layout "${name}"`);
+                }
+                for (const slot of slotsIn(target))
+                    slot.remove();
+                for (const saved of layout.slots) {
+                    if (typeof saved?.appId !== 'string' || saved.appId === '')
+                        continue;
+                    mountSlot(target, saved, (slot) => restores.set(slot, { channel: saved.channel, state: saved.state }));
+                }
+            },
+            async list() {
+                return decodedSegments(await store.list('layouts/'), 'layouts/');
+            },
+            async delete(name) {
+                await store.delete(layoutKey(name));
+            },
+        },
+    };
+    return workspace;
+}
+function isFdc3(value) {
+    const agent = value;
+    return typeof agent?.joinUserChannel === 'function' && typeof agent.getCurrentChannel === 'function';
+}
+/** `promise`, or a rejection once `ms` have passed; the timer does not outlive it. */
+function withTimeout(promise, ms) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error('timed out')), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+/** Keys under `prefix`, decoded back to the names they were made from; one that does not decode is skipped. */
+function decodedSegments(keys, prefix) {
+    return keys.flatMap((key) => {
+        try {
+            return [decodeURIComponent(key.slice(prefix.length))];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The `<fragment-slot>` children of the workspace area, in document order. */
+function slotsIn(container) {
+    return [...container.children].filter((child) => child.localName === 'fragment-slot');
+}
+/**
+ * Mounts a `<fragment-slot>` for an app at the end of the area. `prepare` runs before the slot
+ * connects — which is when it boots and its fragment asks for its globals.
+ */
+function mountSlot(container, app, prepare) {
+    const slot = container.ownerDocument.createElement('fragment-slot');
+    slot.setAttribute('name', app.appId);
+    if (typeof app.src === 'string')
+        slot.setAttribute('src', app.src);
+    if (app.props && typeof app.props === 'object')
+        slot.setAttribute('props', JSON.stringify(app.props));
+    prepare?.(slot);
+    container.append(slot);
+    return slot;
+}
+//# sourceMappingURL=workspace.js.map