@parity/product-lab 0.0.1-placeholder → 0.1.0

package/composition/src/default-session.js

@@ -0,0 +1,594 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { ScenarioJournal } from "@parity/product-lab/chain";
+import { CHAIN_GATES_SWITCH, hostRoutesFor, sessionChainGates } from "@parity/product-lab/host";
+import { SESSION_PORTS_VARIABLE, resolveSessionPorts } from "@parity/product-lab";
+import { environmentConditions } from "./actor-conditions.js";
+import { AccountAddress, AppAccountSource, AppDevServer, AppReadiness, PublicTarget, UnsupportedHostOperation, actorHost, appBuildMessage, withNetworkNote, appDevServerProtocol, framingRefusalAnywhere, framingRefusalMessage } from "@parity/product-lab/domain";
+import { Sr25519KeyDerivation } from "@parity/product-lab/keys-sr25519";
+import { FileEvidenceJournal } from "@parity/product-lab/storage-filesystem";
+import { activePages, sessionPage } from "./default-session-page.js";
+import { readPageAccount, waitUntilReady } from "./app-readiness.js";
+import { identityFunding } from "./identity-funding.js";
+import { actorFunds, observedFunds } from "./actor-funds.js";
+import { serveApp } from "./app-server.js";
+import { deployedAppServer, refuseLaunches } from "./deployed-app-server.js";
+import { deployLocalApp, refuseUnbuildable } from "./deployed-local-app.js";
+import { AppUpdateHub } from "./app-updates.js";
+import { preOnboardedIdentity, preOnboardedViews } from "./pre-onboarded-identities.js";
+import { publicIdentityCreation } from "./public-identities.js";
+import { newIdentity, sessionPersons, withCleanupFailures } from "./default-session-persons.js";
+import { sessionKeep, stopRunning } from "./default-session-keep.js";
+import { personReadings } from "./people-dev/readings.js";
+import { deniesByDefault, resolverBackstop } from "./default-session-browser.js";
+import { SessionHosts } from "./session-hosts.js";
+import { reopenPlaced } from "./session-placement.js";
+import { identityPageFrames } from "./session-frames.js";
+const WELL_KNOWN_EXTRAS = ["asset-hub", "bulletin", "identity-backend"];
+const DEV_AUTHORITY = "//Alice";
+const FUNDING_PLANCK = 10n ** 12n;
+const CREATION_CONCURRENCY = 4;
+const message = (error) => (error instanceof Error ? error.message : String(error));
+export function defaultRunDir(root) {
+    return join(root, ".product-lab", "sessions", `default-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+}
+export async function defaultSessions(context) {
+    const declared = Object.keys(context.apps);
+    if (!declared.length)
+        throw new Error(`The default session needs at least one declared app; ${context.environmentId} declares none. Declare apps in lab.config.ts.`);
+    const offered = declared.filter((id) => !context.unavailable.some((item) => item.app === id));
+    const skipped = context.unavailable.filter((item) => declared.includes(item.app));
+    if (!offered.length)
+        throw new Error(`${skipped[0].app} is unavailable in ${context.environmentId}: ${skipped[0].reason}`);
+    refuseLaunches(offered.map((id) => [id, context.apps[id].launch]));
+    const hostId = context.defaultHost ?? Object.keys(context.hosts)[0];
+    const selection = hostId ? context.hosts[hostId] : undefined;
+    if (!hostId || !selection)
+        throw new Error(`The default session needs a host; declare defaultHost or exactly one entry in hosts`);
+    const hostKind = selection.kind;
+    const publicTarget = context.offer.public ? PublicTarget.parse(context.offer.public, `Environment ${context.environmentId}`) : undefined;
+    const existingApprovals = publicTarget && !publicTarget.writable ? "deny-all" : "approve-all";
+    const runDir = defaultRunDir(context.root);
+    const deployedOf = (id) => context.apps[id].deployed === undefined ? undefined : deployedAppServer(id, context.apps[id].deployed, { id: context.environmentId, ...(context.environment.endpoints ? { endpoints: context.environment.endpoints } : {}), ...(publicTarget ? { public: { ...(publicTarget.network ? { network: publicTarget.network } : {}) } } : {}) }, join(runDir, `gateway-${id}.json`));
+    const declarations = offered.map((id) => ({
+        id,
+        label: context.apps[id].label ?? id,
+        readiness: AppReadiness.parse(id, context.apps[id].ready),
+        accountSource: AppAccountSource.parse(id, context.apps[id].account),
+        deployed: deployedOf(id),
+    })).map((app) => ({ ...app, devServer: app.deployed?.server ?? AppDevServer.parse(app.id, context.apps[app.id].devServer) }));
+    for (const app of declarations)
+        if (context.apps[app.id].launch === "deployed-local")
+            refuseUnbuildable(app.id, app.devServer);
+    const primary = declarations[0];
+    const { system, browsers } = context;
+    if (!browsers || !system.processes || !system.commands || !system.ports || !system.locks || !system.appProxies)
+        throw new Error("The default session needs the lab's system ports and browser launcher; load it through the composition root (@product-lab/composition)");
+    const appProxies = system.appProxies;
+    const progress = context.progress ?? (() => { });
+    const extraPorts = context.sessionPorts ?? resolveSessionPorts({ variable: system.environment?.get(SESSION_PORTS_VARIABLE), declared: { ...(context.environment.endpoints ? { endpoints: context.environment.endpoints } : {}), hosts: context.hosts, apps: context.apps }, fromBlock: true });
+    progress(extraPorts.note);
+    if (extraPorts.source === "fallback")
+        system.logger?.warn(extraPorts.note);
+    const extras = Object.fromEntries(await Promise.all(WELL_KNOWN_EXTRAS.map(async (id) => [id, await system.ports.reserve(extraPorts)])));
+    const routes = await hostRoutesFor(context.environment, extras, { ports: system.ports });
+    const gates = sessionChainGates(system.chainGates, routes, () => system.ports.reserve(extraPorts), { off: system.environment?.get(CHAIN_GATES_SWITCH), progress, ...(system.logger ? { warn: (line) => system.logger.warn(line) } : {}) });
+    progress("Launching the browser (headless Chromium)");
+    const denies = deniesByDefault({ hosts: context.hosts, defaultId: hostId, registry: context.hostRegistry, routes, environmentId: context.environmentId, publicTarget: publicTarget !== undefined, deps: { routes, system: { processes: system.processes, commands: system.commands, locks: system.locks, ports: system.ports }, ...(gates.source ? { chainGates: gates.source } : {}) } });
+    const browser = await browsers.launch({ headless: true, ...resolverBackstop(denies, routes) });
+    const abandoned = await system.processes.reapAbandoned?.(join(context.root, ".product-lab", "sessions"));
+    for (const entry of abandoned?.reaped ?? [])
+        progress(`Stopped ${entry.stopped.join(", ")} left running by an earlier lab process (${entry.owner.pid}) that exited without stopping them`);
+    for (const entry of abandoned?.failed ?? [])
+        system.logger?.warn(`Could not stop what an exited lab process left in ${entry.directory}: ${entry.error}`);
+    const supervisor = system.processes.open(join(runDir, "processes"));
+    const apps = new Map();
+    const ownProxies = new Set();
+    const closeAll = async (errors) => {
+        await gates.close(errors);
+        for (const proxy of ownProxies)
+            await proxy.close().catch((error) => errors.push(error));
+        ownProxies.clear();
+        for (const app of apps.values())
+            await app.served.proxy.close().catch((error) => errors.push(error));
+        await supervisor.stopAll().catch((error) => errors.push(error));
+        supervisor.close();
+        await browser.close().catch((error) => errors.push(error));
+    };
+    try {
+        for (const [index, app] of declarations.entries()) {
+            if (context.apps[app.id].launch !== "deployed-local")
+                continue;
+            const { files, clock, ids, environment, rpc } = system;
+            if (!files || !clock || !ids || !environment || !rpc)
+                throw new Error("The deployed-local launch needs the lab's system ports; load the lab through the composition root (@product-lab/composition)");
+            progress(`Building ${app.id} and deploying it to ${context.environmentId}'s Bulletin and DotNS (deployed-local)`);
+            const deployed = await deployLocalApp({
+                app: app.id,
+                devServer: app.devServer,
+                root: context.root,
+                runDir,
+                endpoints: context.environment.endpoints ?? {},
+                chains: Object.fromEntries(Object.entries(routes.chains).map(([id, route]) => [id, { ...(route.genesis ? { genesis: route.genesis } : {}) }])),
+                system: { processes: system.processes, commands: system.commands, files, clock, ids, environment, rpc },
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            const plan = deployedAppServer(app.id, deployed, { id: context.environmentId, ...(context.environment.endpoints ? { endpoints: context.environment.endpoints } : {}) }, join(runDir, `gateway-${app.id}.json`));
+            declarations[index] = { ...app, deployed: plan, devServer: plan.server };
+        }
+        for (const app of declarations) {
+            const productId = app.deployed?.productId ?? `${app.id}.${routes.namespace}`;
+            const devServerPort = await system.ports.reserve(extraPorts);
+            const appPort = await system.ports.reserve(extraPorts);
+            progress(app.deployed?.starting ?? `Starting ${app.id}'s dev server: ${app.devServer.describe()}`);
+            const served = await serveApp({
+                app: app.id,
+                devServer: app.devServer,
+                root: context.root,
+                productId,
+                routes,
+                ...(context.environment.endpoints ? { endpoints: context.environment.endpoints } : {}),
+                ports: { devServer: devServerPort, proxy: appPort },
+                processes: supervisor,
+                processName: declarations.length === 1 ? "app" : `app-${app.id}`,
+                proxies: appProxies,
+                signal: context.signal,
+            });
+            apps.set(app.id, { ...app, productId, served, proxyTaken: false });
+        }
+    }
+    catch (error) {
+        const cleanup = [];
+        await closeAll(cleanup);
+        throw withCleanupFailures(error, cleanup);
+    }
+    const found = [];
+    const say = (notice) => {
+        if (found.includes(notice))
+            return;
+        found.push(notice);
+        progress(notice);
+    };
+    for (const item of skipped)
+        say(`${item.app} is not served: it is unavailable in ${context.environmentId} (${item.reason}).`);
+    const updates = new AppUpdateHub({ root: context.root });
+    for (const app of apps.values()) {
+        const { served } = app;
+        if (app.deployed)
+            progress(app.deployed.served(served.url));
+        else
+            progress(`Serving ${app.id} on ${served.url} (the lab's proxy in front of its dev server on ${served.devServerUrl})`);
+        if (!app.deployed)
+            progress(served.settings.length ? `${app.id}'s dev server was given: ${served.settings.map((setting) => `${setting.name} (${setting.what})`).join(", ")}` : `${app.id}'s dev server was given no settings (apps.${app.id}.devServer.settings names none)`);
+        for (const notice of served.notices ?? [])
+            say(notice);
+        const framing = served.framing();
+        const refusal = framing ? framingRefusalAnywhere(framing, served.url) : undefined;
+        if (refusal)
+            say(`${framingRefusalMessage(app.id, refusal, "The lab window")} Headless runs on the truAPI CLI host open the app as a page of its own and are not affected; ` +
+                "a host that frames its product (the WASM test host, dot.li) refuses it for the same reason.");
+        updates.follow(app.id, { ...(context.apps[app.id].label ? { label: context.apps[app.id].label } : {}), ...(app.devServer.updates ? { protocol: appDevServerProtocol(app.devServer.updates) } : {}) });
+    }
+    const stopListening = updates.subscribe((event) => {
+        if (event.type === "unknown-socket")
+            say(appBuildMessage(apps.get(event.app)?.label ?? event.app, { kind: "not-held", app: event.app, path: event.path, ...(event.stream ? { stream: true } : {}) }));
+    });
+    const hostDeps = { browser, routes, system: { processes: system.processes, commands: system.commands, locks: system.locks, ports: system.ports, ...(system.environment ? { environment: system.environment } : {}), ...(system.conditionedLinks ? { conditionedLinks: system.conditionedLinks } : {}), ...(system.inspectAppFraming ? { inspectAppFraming: system.inspectAppFraming } : {}) }, ...(gates.source ? { chainGates: gates.source } : {}) };
+    const keep = sessionKeep({ keep: context.keep, environmentId: context.environmentId, ...(context.environment.provenance ? { provenance: context.environment.provenance } : {}), root: context.root, hostKind, hosts: context.hosts, system: { files: system.files, locks: system.locks, ids: system.ids } });
+    const hosts = new SessionHosts({ hosts: keep.hosts, defaultId: hostId, registry: context.hostRegistry, routes, deps: hostDeps, environmentId: context.environmentId, publicTarget: publicTarget !== undefined, progress });
+    let host;
+    try {
+        host = await hosts.get();
+    }
+    catch (error) {
+        const cleanup = [];
+        await closeAll(cleanup);
+        throw withCleanupFailures(error, cleanup);
+    }
+    const sessionKinds = new WeakMap();
+    const authority = new Sr25519KeyDerivation().derive(DEV_AUTHORITY).signer;
+    const journal = new ScenarioJournal(new FileEvidenceJournal(join(runDir, "journal")).open(), () => { }, { clock: system.clock });
+    const transactions = [];
+    const signing = (appId, chainId) => context.apps[appId].fundingSigning?.[chainId];
+    const funding = identityFunding({ chains: context.chains ?? {}, authority, journal, signal: context.signal, clock: system.clock, planck: FUNDING_PLANCK, signing, transactions });
+    const creation = publicTarget && publicIdentityCreation({ target: publicTarget, hostKind, chains: context.chains ?? {}, secrets: context.secrets, system: { processes: system.processes, commands: system.commands }, dataRoot: join(runDir, "identities"), journal, signal: context.signal, clock: system.clock, signing, transactions });
+    const persons = publicTarget ? undefined : sessionPersons({ app: context.apps[primary.id], environmentId: context.environmentId, environment: context.environment, routes, runDir, system: { processes: system.processes, commands: system.commands }, journal, signal: context.signal, transactions, log: progress });
+    const actors = new Map();
+    let placements;
+    let created = 0;
+    const order = new Map();
+    let started = 0;
+    let closed = false;
+    const contexts = [];
+    const ready = async (app, session, page, signal) => {
+        const gone = app.served.exited();
+        if (gone)
+            throw gone;
+        await waitUntilReady(app.readiness, { page, host: sessionKinds.get(session) ?? hostKind, ...(session.connection ? { connection: () => session.connection() } : {}) }, 
+        { signal, hint: () => app.served.settingsHint() });
+    };
+    async function hostAccount(session) {
+        try {
+            const verified = await session.account();
+            return { account: verified.address, source: verified.source === "identity" ? "the host identity (derived)" : verified.source === "app" ? "the host adapter's reader of the page" : "the host" };
+        }
+        catch (error) {
+            if (error instanceof UnsupportedHostOperation)
+                return { account: undefined, missing: error.missing };
+            throw error;
+        }
+    }
+    async function pageAccount(app, page, missing, kind = hostKind) {
+        if (!app.accountSource.reader)
+            throw new Error(`The ${kind} host cannot tell which account it gives ${app.id} (${missing}), and the lab does not require an app to show its account. ` +
+                `If ${app.id}'s page shows it, declare where in lab.config.ts: apps.${app.id}.account = { testId: "…", attribute: "…" } (or a selector).`);
+        const shown = await readPageAccount(app.accountSource, page, app.readiness.timeoutMs);
+        const address = AccountAddress.parse(shown);
+        return { account: address.kind === "account" ? address.ss58() : address.hex, source: `the app's page (${app.accountSource.describe()})` };
+    }
+    async function proxyFor(app) {
+        if (!app.proxyTaken) {
+            app.proxyTaken = true;
+            return { proxy: app.served.proxy, own: false };
+        }
+        const proxy = await appProxies.open({ port: await system.ports.reserve(extraPorts), target: app.served.devServerUrl, ...(app.devServer.updates ? { updates: app.devServer.updates } : {}) });
+        ownProxies.add(proxy);
+        return { proxy, own: true };
+    }
+    const releaseProxy = async (app, proxy, own) => {
+        if (!own) {
+            proxy.bridge(undefined);
+            app.proxyTaken = false;
+            return;
+        }
+        ownProxies.delete(proxy);
+        await proxy.close();
+    };
+    const consoleListeners = new Set();
+    const unwatchedConsoles = new Map();
+    const emitConsole = (event) => {
+        for (const listener of consoleListeners)
+            listener(event);
+    };
+    function followConsole(actor, app) {
+        const key = `${actor}\u0000${app}`;
+        let stop = () => undefined;
+        let generation = 0;
+        const unwatched = (reason) => {
+            const event = { kind: "unwatched", actor, app, reason };
+            unwatchedConsoles.set(key, event);
+            emitConsole(event);
+        };
+        return {
+            follow(document) {
+                const mine = ++generation;
+                stop();
+                stop = () => undefined;
+                void import("@parity/product-lab/browser-playwright").then(({ PageConsoleWatch }) => {
+                    if (mine !== generation)
+                        return;
+                    const watch = PageConsoleWatch.watch(document, (message) => emitConsole({ kind: "message", actor, app, type: message.type, text: message.text, at: message.at }));
+                    if ("unwatched" in watch)
+                        return unwatched(watch.unwatched);
+                    unwatchedConsoles.delete(key);
+                    stop = watch.stop;
+                }, (error) => unwatched(`the browser adapter could not be loaded: ${message(error)}`));
+            },
+            stop() {
+                generation++;
+                stop();
+                stop = () => undefined;
+                unwatchedConsoles.delete(key);
+            },
+        };
+    }
+    async function openSession(actor, app, signal, path) {
+        const pass = actor.existing || actor.unfunded ? undefined : (publicTarget ? creation : { funding })?.funding.begin(app.id);
+        try {
+            return await openFunded(actor, app, signal, pass, path);
+        }
+        finally {
+            pass?.end();
+        }
+    }
+    async function openFunded(actor, app, signal, pass, path) {
+        signal.throwIfAborted();
+        const { proxy, own } = await proxyFor(app);
+        const unfollow = updates.attach(actor.id, app.id, proxy.updates, () => app.served.answering(), { starting: true, source: proxy.target });
+        const failed = async (error, session) => {
+            unfollow();
+            const cleanup = [];
+            await session?.stop().catch((failure) => cleanup.push(failure));
+            await releaseProxy(app, proxy, own).catch((failure) => cleanup.push(failure));
+            return withCleanupFailures(error, cleanup);
+        };
+        let session;
+        try {
+            session = await (await hosts.get(actor.host)).createSession({
+                actor: { id: actor.id, name: actor.name, identity: actor.identity },
+                ...(actor.existing ? { approvals: existingApprovals } : {}),
+                app: {
+                    id: app.id,
+                    productId: app.productId,
+                    url: ({ hostBridgeUrl }) => {
+                        if (hostBridgeUrl)
+                            proxy.bridge(hostBridgeUrl);
+                        return proxy.url;
+                    },
+                },
+                ...(path ? { path } : {}),
+                ...(actor.conditions ? { conditions: true } : {}),
+                ...(placements && hosts.capabilities(actor.host)?.placement && placements(actor.id) ? { placement: placements(actor.id) } : {}),
+            });
+        }
+        catch (error) {
+            throw await failed(error);
+        }
+        contexts.push(session);
+        sessionKinds.set(session, hosts.kind(actor.host));
+        const printed = followConsole(actor.id, app.id);
+        try {
+            const first = await session.page();
+            let current = first;
+            printed.follow(first);
+            const page = sessionPage(first, session, (shown) => ready(app, session, shown, signal), (now) => {
+                current = now;
+                printed.follow(now);
+            });
+            const fromHost = await hostAccount(session);
+            const funded = pass && fromHost.account !== undefined ? pass.fund(actor.name, fromHost.account) : undefined;
+            progress(`Waiting for ${app.id} to be ready for ${actor.name}: ${app.readiness.describe()}`);
+            try {
+                await ready(app, session, first, signal);
+            }
+            catch (error) {
+                await funded;
+                throw error;
+            }
+            const known = fromHost.account !== undefined ? fromHost : await pageAccount(app, first, fromHost.missing, hosts.kind(actor.host));
+            for (const warning of await (funded ?? (pass ? pass.fund(actor.name, known.account) : Promise.resolve([]))))
+                journal.message(warning);
+            return { app, session, page, current: () => current, account: known.account, accountSource: known.source, proxy, unfollow, unwatch: () => printed.stop() };
+        }
+        catch (error) {
+            printed.stop();
+            throw await failed(error, session);
+        }
+    }
+    const stopOpened = async (opened, errors) => {
+        opened.unfollow();
+        opened.unwatch();
+        await opened.session.stop().catch((error) => errors.push(error));
+        await releaseProxy(opened.app, opened.proxy, ownProxies.has(opened.proxy)).catch((error) => errors.push(error));
+    };
+    async function dropActor(state) {
+        actors.delete(state.id);
+        order.delete(state.id);
+        activePages.delete(state.id);
+        const errors = [];
+        for (const opened of state.apps.values())
+            await stopOpened(opened, errors);
+        return errors;
+    }
+    async function openActor(actor, signal, shown, check) {
+        order.set(actor.id, ++started);
+        const opened = await openSession(actor, apps.get(primary.id), signal).catch((error) => {
+            order.delete(actor.id);
+            throw error;
+        });
+        const shownHost = hosts.shown(actorHost(await hosts.get(actor.host)), actor.host), host = withNetworkNote(shownHost, opened.session.networkNote);
+        const view = { id: actor.id, name: actor.name, ...shown, appUrl: opened.current().url(), account: opened.account, status: "running", ...(host ? { host } : {}) };
+        const state = { ...actor, apps: new Map([[primary.id, opened]]), active: primary.id, view, ...(shownHost ? { shownHost } : {}) };
+        actors.set(actor.id, state);
+        activePages.set(actor.id, opened.page);
+        try {
+            check?.(opened);
+            await updates.ready(actor.id, primary.id);
+        }
+        catch (error) {
+            throw withCleanupFailures(error, await dropActor(state));
+        }
+        return state;
+    }
+    async function createActor(request = {}, kept) {
+        if (closed)
+            throw new Error("The default session is closed");
+        const options = hosts.withReference(request);
+        if (options.host !== undefined && options.host !== hostId && options.conditions && !hosts.capabilities(options.host)?.conditions)
+            throw new Error(`${options.name ?? "The actor"} cannot have conditions on the "${options.host}" host: it declares no per-identity conditions`);
+        const number = ++created;
+        const id = kept?.id ?? `actor${randomBytes(3).toString("hex")}`;
+        const name = options.name ?? `Person ${number}`;
+        const signal = options.signal ? AbortSignal.any([context.signal, options.signal]) : context.signal;
+        const identity = kept?.identity ?? (await newIdentity(creation || persons?.onboarding, { id, name }, signal));
+        const actor = { id, name, identity, ...(options.funds === "none" || persons || kept ? { unfunded: true } : {}), ...(options.conditions ? { conditions: true } : {}), ...(options.host !== undefined && options.host !== hostId ? { host: options.host } : {}) };
+        const { view } = await openActor(actor, signal, { username: identity.liteUsername ?? "" });
+        if (!kept)
+            keep.made(view, identity, actor.host);
+        return view;
+    }
+    const openedExisting = new Map();
+    const declaredExisting = context.preOnboarded ?? [];
+    async function openPreOnboarded(request) {
+        if (closed)
+            throw new Error("The default session is closed");
+        const declared = declaredExisting.find((actor) => actor.name === request.name);
+        if (!declared)
+            throw new Error(`${request.name} is not a pre-onboarded actor of this lab (defineLab({ actors }))`);
+        const already = openedExisting.get(declared.name);
+        if (already && actors.has(already))
+            return actors.get(already).view;
+        const signal = request.signal ? AbortSignal.any([context.signal, request.signal]) : context.signal;
+        const actor = { id: `actor${randomBytes(3).toString("hex")}`, name: declared.name, identity: await preOnboardedIdentity(declared, context.secrets), existing: true };
+        const state = await openActor(actor, signal, { username: declared.liteUsername ?? "", kind: "preOnboarded" }, (opened) => {
+            if (declared.account !== undefined && !AccountAddress.parse(declared.account).same(AccountAddress.parse(opened.account)))
+                throw new Error(`${declared.name}'s host gives ${primary.id} the account ${opened.account} (from ${opened.accountSource}), not the declared ${declared.account}: secret ${declared.secret} holds another wallet`);
+        });
+        openedExisting.set(declared.name, actor.id);
+        return state.view;
+    }
+    const running = (actorId) => {
+        const state = closed ? undefined : actors.get(actorId);
+        if (!state)
+            throw new Error(`The default session has no running identity ${actorId}`);
+        return state;
+    };
+    const frames = identityPageFrames((id) => (closed ? undefined : actors.get(id)?.apps.get(actors.get(id).active)?.current()));
+    const several = apps.size > 1;
+    const capabilities = host.capabilities;
+    const concurrent = !!capabilities && capabilities.concurrentSessions !== false;
+    const others = hosts.entries().filter((entry) => !entry.default && entry.available).map((entry) => hosts.capabilities(entry.id));
+    const conditions = environmentConditions(host.capabilities, (actorId) => {
+        const state = closed ? undefined : actors.get(actorId);
+        return state ? [...state.apps.values()].map((opened) => opened.session) : undefined;
+    }, others);
+    const keepDeps = { open: (person) => createActor({ name: person.name, ...(person.host ? { host: person.host } : {}) }, person), stop: (id) => stopRunning(running(id), order.get(id) ?? 0, dropActor), running: (id) => !closed && actors.has(id), place: (id, at) => void order.set(id, at) };
+    if (!context.restoring)
+        await keep.reopen(keepDeps);
+    return {
+        name: `${[...apps.keys()].join(" + ")} (${context.environmentId})`,
+        provider: `composition default session + ${selection.kind}`,
+        provenance: {},
+        get notices() {
+            return [
+                publicTarget
+                    ? `Default session on a public network: its actors are the lab's pre-onboarded identities${declaredExisting.length ? ` (${declaredExisting.map((actor) => actor.name).join(", ")})` : " (none declared)"}, opened with their own wallets; the lab creates and funds no identity${existingApprovals === "deny-all" ? ", and their hosts deny every request (read only)" : ""}.`
+                    : several
+                        ? `Default session: one throwaway host wallet per actor, funded by the dev authority; it serves ${[...apps.keys()].join(", ")}. An actor opens ${primary.id} first and another app with "{actor} opens {app} at {route}".`
+                        : "Default session: one throwaway host wallet per actor, funded by the dev authority.",
+                ...[...apps.values()].map((app) => `The actor's account comes from the host (not the app's page); ${app.id} is ready when: ${app.readiness.describe()}.`),
+                ...found,
+                ...keep.lines,
+            ];
+        },
+        actors: () => keep.listed([...actors.values()].map((state) => ({ view: state.view.host ? { ...state.view, host: hosts.current(state.view.host, state.host) } : state.view, at: order.get(state.id) ?? 0 }))),
+        hostSessions: async () => (closed ? [] : [...contexts]),
+        hosts: () => hosts.entries(), unconfiguredHosts: () => hosts.unconfigured(),
+        probeHost: (id, request) => hosts.probe(id, request),
+        hostBypassScope: context.offer.local ? "all-local-extrinsics" : "run-accounts-only",
+        chainEndpoints: () => ({
+            ...Object.fromEntries(context.offer.chains.flatMap((id) => context.environment.endpoints?.[id] ? [[id, context.environment.endpoints[id]]] : [])),
+            ...Object.fromEntries(Object.entries(context.environment.routes?.chains ?? {}).map(([id, route]) => [id, route.ws])),
+        }),
+        transactionDeclarations: () => [...transactions],
+        scenarios: [],
+        async observe(actor) {
+            const state = actors.get(actor.id);
+            const opened = state?.apps.get(primary.id);
+            return {
+                account: state?.view.account,
+                ...(opened ? { accountFrom: opened.accountSource } : {}),
+                ready: primary.readiness.describe(),
+                ...(several && state ? { active: state.active, apps: Object.fromEntries([...state.apps].map(([id, item]) => [id, { account: item.account, accountFrom: item.accountSource }])) } : {}),
+                ...(state && Object.keys(context.chains ?? {}).length ? await observedFunds(context.chains, state.view.account, state.name) : {}),
+            };
+        },
+        console(listener) {
+            consoleListeners.add(listener);
+            for (const event of unwatchedConsoles.values())
+                listener(event);
+            return () => {
+                consoleListeners.delete(listener);
+            };
+        },
+        chains: () => Object.fromEntries(Object.entries(context.chains ?? {}).map(([id, chain]) => [id, chain.access])),
+        async signing(actorId) {
+            const state = closed ? undefined : actors.get(actorId);
+            if (!state)
+                return undefined;
+            const records = await Promise.all([...state.apps.values()].map((opened) => opened.session.approvals.signing?.()));
+            const kept = records.filter((record) => record !== undefined);
+            return kept.length ? kept.flat() : undefined;
+        },
+        async hostRequests(actorId) {
+            const state = closed ? undefined : actors.get(actorId);
+            if (!state)
+                return undefined;
+            return Object.fromEntries(await Promise.all([...state.apps].map(async ([id, opened]) => [id, await opened.session.approvals.decisions?.()])));
+        },
+        frames: () => frames,
+        ...(conditions ? { conditions } : {}),
+        appUpdates: () => (closed ? undefined : updates),
+        async openApp({ actorId, app: appId, path }) {
+            const state = running(actorId);
+            const app = apps.get(appId);
+            if (!app)
+                throw new Error(`${appId} is not an app this default session serves (${[...apps.keys()].join(", ")})`);
+            let opened = state.apps.get(appId);
+            if (!opened) {
+                opened = await openSession(state, app, context.signal, path);
+                state.apps.set(appId, opened);
+                try {
+                    await updates.ready(actorId, appId);
+                }
+                catch (error) {
+                    state.apps.delete(appId);
+                    const cleanup = [];
+                    await stopOpened(opened, cleanup);
+                    throw withCleanupFailures(error, cleanup);
+                }
+            }
+            else {
+                await opened.page.open(path);
+                await opened.page.ready();
+            }
+            state.active = appId;
+            activePages.set(actorId, opened.page);
+            return { actorId, app: appId, url: opened.current().url(), account: opened.account };
+        },
+        async placeSessions(next) {
+            placements = next;
+            await reopenPlaced([...actors.values()], { placeable: (state) => !!hosts.capabilities(state.host)?.placement, stop: async (opened) => { const errors = []; await stopOpened(opened, errors); return errors; },
+                open: (state, opened, path) => openFunded(state, opened.app, context.signal, undefined, path),
+                moved: (state, appId, again) => { if (state.active === appId) {
+                    activePages.set(state.id, again.page);
+                    const { host: _was, ...view } = state.view, host = withNetworkNote(state.shownHost, again.session.networkNote);
+                    state.view = { ...view, appUrl: again.current().url(), ...(host ? { host } : {}) };
+                } } });
+        },
+        async reloadApp(actorId, request) {
+            const state = running(actorId);
+            const appId = request?.app ?? state.active;
+            const opened = state.apps.get(appId);
+            if (!opened)
+                throw new Error(`${state.name} has not opened ${appId}`);
+            await opened.page.reload();
+            await opened.page.ready();
+            const fromHost = await hostAccount(opened.session);
+            const again = fromHost.account !== undefined ? fromHost : await pageAccount(opened.app, await opened.session.page(), fromHost.missing, sessionKinds.get(opened.session));
+            if (!AccountAddress.parse(again.account).same(AccountAddress.parse(opened.account)))
+                throw new Error(`after the reload the account of ${state.name}${several ? ` in ${opened.app.id}` : ""} is ${again.account} (from ${again.source}), not ${opened.account}`);
+        },
+        ...(publicTarget ? (creation ? { createActor: (request) => createActor(request) } : {}) : { createActor: (request) => createActor(request), fundsOf: (id) => actorFunds(context.chains ?? {}, actors.get(id)?.view.account, id), ...(concurrent ? { actorCreation: { concurrency: CREATION_CONCURRENCY } } : {}) }),
+        ...(publicTarget ? {} : keep.manage(keepDeps)),
+        ...(persons ? { actorReadings: async (id, signal) => { const state = running(id), opened = state.apps.get(primary.id); return personReadings({ name: state.name, account: opened.account, identity: state.identity, ready: () => opened.page.ready() }, persons.onboarding, context.chains?.people, signal); } } : {}),
+        ...(declaredExisting.length
+            ? {
+                preOnboarded: () => preOnboardedViews(declaredExisting, context.secrets, (name) => {
+                    const id = openedExisting.get(name);
+                    return id && actors.has(id) ? id : undefined;
+                }),
+                openPreOnboarded,
+            }
+            : {}),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            const errors = [];
+            stopListening();
+            for (const state of [...actors.values()])
+                errors.push(...(await dropActor(state)));
+            await hosts.dispose(errors);
+            await closeAll(errors);
+            persons?.close(errors);
+            keep.close();
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length)
+                throw new AggregateError(errors, `Closing the default session failed: ${errors.map(message).join("; ")}`);
+        },
+    };
+}

package/composition/src/demo-ports.d.ts

@@ -0,0 +1,8 @@
+import type { SlideRenderer } from "@parity/product-lab/ports/recording";
+import type { CommandRunner, EnvironmentVariables } from "@parity/product-lab/ports/system";
+import { FfmpegVideoEditor } from "@parity/product-lab/video-ffmpeg";
+export declare const FFMPEG_VARIABLE = "PRODUCT_LAB_FFMPEG";
+export declare function demoPorts(env: EnvironmentVariables, commands: CommandRunner): {
+    video: FfmpegVideoEditor;
+    slides: SlideRenderer;
+};

package/composition/src/demo-ports.js

@@ -0,0 +1,21 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { join } from "node:path";
+import { FfmpegVideoEditor } from "@parity/product-lab/video-ffmpeg";
+export const FFMPEG_VARIABLE = "PRODUCT_LAB_FFMPEG";
+export function demoPorts(env, commands) {
+    const folder = env.get(FFMPEG_VARIABLE)?.trim();
+    let renderer;
+    const slides = {
+        render: async (html, size, options) => {
+            renderer ??= import("@parity/product-lab/browser-playwright").then(({ PlaywrightSlideRenderer }) => new PlaywrightSlideRenderer());
+            return (await renderer).render(html, size, options);
+        },
+        close: async () => {
+            const opened = renderer;
+            renderer = undefined;
+            await (await opened)?.close();
+        },
+    };
+    return { video: new FfmpegVideoEditor({ commands, ...(folder ? { ffmpeg: join(folder, "ffmpeg"), ffprobe: join(folder, "ffprobe") } : {}) }), slides };
+}