@dxos/plugin-assistant 0.8.4-main.e8ec1fe → 0.8.4-main.effb148878

package/src/capabilities/app-graph-builder.ts

@@ -2,209 +2,196 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom } from '@effect-atom/atom-react';
-import * as Function from 'effect/Function';
+import * as Effect from 'effect/Effect';
+import { pipe } from 'effect/Function';
 import * as Option from 'effect/Option';
 
-import {
-  Capabilities,
-  LayoutAction,
-  type PluginContext,
-  type PromiseIntentDispatcher,
-  contributes,
-  createIntent,
-} from '@dxos/app-framework';
-import { Prompt } from '@dxos/blueprints';
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, AppNode, getActiveSpace, getPersonalSpace } from '@dxos/app-toolkit';
+import { AgentPrompt, Chat } from '@dxos/assistant-toolkit';
+import { Blueprint, Operation, Routine } from '@dxos/compute';
 import { Sequence } from '@dxos/conductor';
-import { DXN, Obj } from '@dxos/echo';
+import { DXN, Database, Filter, Obj, type Ref } from '@dxos/echo';
+import { AtomObj } from '@dxos/echo-atom';
 import { invariant } from '@dxos/invariant';
 import { ClientCapabilities } from '@dxos/plugin-client';
-import { ATTENDABLE_PATH_SEPARATOR, PLANK_COMPANION_TYPE } from '@dxos/plugin-deck/types';
-import { ROOT_ID, atomFromSignal, createExtension } from '@dxos/plugin-graph';
-import { getActiveSpace } from '@dxos/plugin-space';
-import { SpaceAction } from '@dxos/plugin-space/types';
-import { Query, type Space, getSpace } from '@dxos/react-client/echo';
+import { GraphBuilder, Node, NodeMatcher } from '@dxos/plugin-graph';
+import { linkedSegment } from '@dxos/react-ui-attention';
 
-import { ASSISTANT_DIALOG, meta } from '../meta';
-import { Assistant, AssistantAction } from '../types';
+import { ASSISTANT_COMPANION_VARIANT, meta } from '#meta';
+import { AssistantCapabilities, AssistantOperation } from '#types';
 
-import { AssistantCapabilities } from './capabilities';
+/** Operation definitions to seed as `PersistentOperation` records for automation / triggers. */
+const computeOperationsToImport = [AgentPrompt] as const;
 
-export default (context: PluginContext) =>
-  contributes(Capabilities.AppGraphBuilder, [
-    createExtension({
-      id: `${meta.id}/root`,
-      actions: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => {
-              return Obj.instanceOf(Assistant.Chat, node.data) ? Option.some(node.data) : Option.none();
-            }),
-            Option.map((object) => {
-              const id = Obj.getDXN(object).toString();
-              return [
-                {
-                  id: `${AssistantAction.UpdateChatName._tag}/${id}`,
-                  data: async () => {
-                    const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                    await dispatch(createIntent(AssistantAction.UpdateChatName, { chat: object }));
-                  },
-                  properties: {
-                    label: ['chat update name label', { ns: meta.id }],
-                    icon: 'ph--magic-wand--regular',
-                    disposition: 'list-item',
-                  },
-                },
-              ];
+/** Match ECHO objects that are NOT chats. */
+const whenNonChatObject = NodeMatcher.whenAll(
+  NodeMatcher.whenEchoObject,
+  NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Chat.Chat)),
+);
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+
+    const extensions = yield* Effect.all([
+      GraphBuilder.createTypeExtension({
+        id: 'root',
+        type: Chat.Chat,
+        actions: (chat) => {
+          return Effect.succeed([
+            Node.makeAction({
+              id: AssistantOperation.UpdateChatName.meta.key,
+              data: () =>
+                Effect.gen(function* () {
+                  // TODO(dmaretskyi): This goes away when composer will have unified operation invocations.
+                  const db = Obj.getDatabase(chat);
+                  invariant(db);
+                  yield* Operation.invoke(AssistantOperation.UpdateChatName, { chat }, { spaceId: db.spaceId });
+                }),
+              properties: {
+                label: ['chat-update-name.label', { ns: meta.id }],
+                icon: 'ph--magic-wand--regular',
+                disposition: 'list-item',
+              },
             }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
+          ]);
+        },
+      }),
 
-    createExtension({
-      id: `${meta.id}/assistant`,
-      actions: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: `${LayoutAction.UpdateDialog._tag}/assistant/open`,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  const client = context.getCapability(ClientCapabilities.Client);
-                  const space = getActiveSpace(context) ?? client.spaces.default;
-                  const chat = await getOrCreateChat(dispatch, space);
-                  if (!chat) {
-                    return;
+      GraphBuilder.createExtension({
+        id: 'assistant',
+        match: NodeMatcher.whenRoot,
+        actions: () =>
+          Effect.succeed([
+            Node.makeAction({
+              id: 'import-compute-operations',
+              data: Effect.fnUntraced(function* () {
+                const capabilities = yield* Capability.Service;
+                const client = yield* Capability.get(ClientCapabilities.Client);
+                const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+                if (!space) {
+                  return;
+                }
+                for (const definition of computeOperationsToImport) {
+                  const key = definition.meta.key;
+                  if (!key) {
+                    continue;
                   }
-
-                  await dispatch(
-                    createIntent(LayoutAction.UpdateDialog, {
-                      part: 'dialog',
-                      subject: ASSISTANT_DIALOG,
-                      options: {
-                        state: true,
-                        blockAlign: 'end',
-                        props: {
-                          chat,
-                        },
-                      },
-                    }),
+                  const existing = yield* Effect.promise(
+                    (): Promise<Operation.PersistentOperation[]> =>
+                      space.db.query(Filter.and(Filter.type(Operation.PersistentOperation), Filter.key(key))).run(),
                   );
-                },
-                properties: {
-                  label: ['open assistant label', { ns: meta.id }],
-                  icon: 'ph--sparkle--regular',
-                  disposition: 'pin-end',
-                  position: 'hoist',
-                  keyBinding: {
-                    macos: 'shift+meta+k',
-                    windows: 'shift+ctrl+k',
-                  },
-                },
+                  if (existing.length === 0) {
+                    space.db.add(Operation.serialize(definition));
+                  }
+                }
+                yield* Database.flush();
+              }),
+              properties: {
+                label: ['import-compute-operations.label', { ns: meta.id }],
+                icon: 'ph--download-simple--regular',
               },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-
-    createExtension({
-      id: `${meta.id}/companion-chat`,
-      connector: (node) => {
-        return Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (Obj.isObject(node.data) ? Option.some(node.data) : Option.none())),
-            Option.flatMap((object) => {
-              const currentChatState = get(
-                atomFromSignal(
-                  () => context.getCapability(AssistantCapabilities.State).currentChat[Obj.getDXN(object).toString()],
-                ),
-              );
-              // If no state, continue to allow chat initialization.
-              if (!currentChatState) {
-                return Option.some({ object, currentChat: undefined });
-              }
-
-              const space = getSpace(object);
-              const currentChatDxn = DXN.tryParse(currentChatState);
-              const currentChatRef = currentChatDxn ? space?.db.ref(currentChatDxn) : undefined;
-              const currentChat = get(atomFromSignal(() => currentChatRef?.target));
-              return currentChat ? Option.some({ object, currentChat }) : Option.none();
             }),
-            Option.map(({ object, currentChat }) => {
-              return [
-                {
-                  id: [Obj.getDXN(object).toString(), 'assistant-chat'].join(ATTENDABLE_PATH_SEPARATOR),
-                  type: PLANK_COMPANION_TYPE,
-                  data: currentChat ?? 'assistant-chat',
-                  properties: {
-                    label: ['assistant chat label', { ns: meta.id }],
-                    icon: 'ph--sparkle--regular',
-                    position: 'hoist',
-                    disposition: 'hidden',
-                  },
-                },
-              ];
+            Node.makeAction({
+              id: AssistantOperation.ToggleTracePanelDebug.meta.key,
+              data: () => Operation.invoke(AssistantOperation.ToggleTracePanelDebug, {}),
+              properties: {
+                label: ['toggle-trace-panel-debug.label', { ns: meta.id }],
+                icon: 'ph--brackets-curly--regular',
+              },
             }),
-            Option.getOrElse(() => []),
-          ),
-        );
-      },
-    }),
-
-    createExtension({
-      id: `${meta.id}/invocations`,
-      connector: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) =>
-              Obj.instanceOf(Sequence, node.data) || Obj.instanceOf(Prompt.Prompt, node.data)
-                ? Option.some(node)
-                : Option.none(),
-            ),
-            Option.map((node) => [
-              {
-                id: [node.id, 'invocations'].join(ATTENDABLE_PATH_SEPARATOR),
-                type: PLANK_COMPANION_TYPE,
-                data: 'invocations',
-                properties: {
-                  label: ['invocations label', { ns: meta.id }],
-                  icon: 'ph--clock-countdown--regular',
-                  disposition: 'hidden',
-                },
+            Node.makeAction({
+              id: 'reset-blueprints',
+              data: Effect.fnUntraced(function* () {
+                const capabilities = yield* Capability.Service;
+                const client = yield* Capability.get(ClientCapabilities.Client);
+                const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+                if (!space) {
+                  return;
+                }
+                const blueprints = yield* Effect.promise(
+                  (): Promise<Blueprint.Blueprint[]> => space.db.query(Filter.type(Blueprint.Blueprint)).run(),
+                );
+                for (const blueprint of blueprints) {
+                  space.db.remove(blueprint);
+                }
+                yield* Database.flush();
+              }),
+              properties: {
+                label: ['reset-blueprints.label', { ns: meta.id }],
+                icon: 'ph--arrow-clockwise--regular',
               },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-  ]);
+            }),
+          ]),
+      }),
+
+      // Don't show assistant companion when a chat is already the primary object.
+      GraphBuilder.createExtension({
+        id: 'companion-chat',
+        match: whenNonChatObject,
+        connector: (object, get) =>
+          Effect.gen(function* () {
+            const state = get(yield* Capability.get(AssistantCapabilities.State));
+            const cache = get(yield* Capability.get(AssistantCapabilities.CompanionChatCache));
+            const objectUri = Obj.getURI(object);
 
-// TODO(burdon): Factor out.
-const getOrCreateChat = async (
-  dispatch: PromiseIntentDispatcher,
-  space: Space,
-): Promise<Assistant.Chat | undefined> => {
-  // TODO(wittjosiah): This should be possible with a single query.
-  const { objects: allChats } = await space.db.query(Query.type(Assistant.Chat)).run();
-  const { objects: relatedChats } = await space.db
-    .query(Query.type(Assistant.Chat).sourceOf(Assistant.CompanionTo).source())
-    .run();
+            // Resolve chat from persisted state or transient cache.
+            const chat = pipe(
+              Option.fromNullable(state.currentChat[objectUri]),
+              Option.flatMap((dxnStr) => Option.fromNullable(DXN.tryMake(dxnStr))),
+              Option.flatMap((dxn) => Option.fromNullable(Obj.getDatabase(object)?.makeRef(dxn))),
+              Option.map((ref) => get(AtomObj.make(ref as Ref.Ref<Obj.Unknown>))),
+              Option.filter(Obj.isObject),
+              Option.orElse(() => pipe(Option.fromNullable(cache[objectUri]), Option.filter(Obj.isObject))),
+              Option.getOrNull,
+            );
 
-  const chats = allChats.filter((chat) => !relatedChats.includes(chat));
-  if (chats.length > 0) {
-    return chats.at(-1);
-  }
+            return [
+              AppNode.makeCompanion({
+                id: linkedSegment(ASSISTANT_COMPANION_VARIANT),
+                label: ['assistant-chat.label', { ns: meta.id }],
+                icon: 'ph--sparkle--regular',
+                data: chat,
+                position: 'first',
+              }),
+            ];
+          }),
+      }),
+
+      GraphBuilder.createExtension({
+        id: 'invocations',
+        match: NodeMatcher.whenAny(
+          NodeMatcher.whenEchoTypeMatches(Sequence.Sequence),
+          NodeMatcher.whenEchoTypeMatches(Routine.Routine),
+        ),
+        connector: () =>
+          Effect.succeed([
+            AppNode.makeCompanion({
+              id: 'invocations',
+              label: ['invocations.label', { ns: meta.id }],
+              icon: 'ph--clock-countdown--regular',
+              data: 'invocations',
+            }),
+          ]),
+      }),
+
+      GraphBuilder.createExtension({
+        id: 'trace',
+        match: NodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed([
+            AppNode.makeDeckCompanion({
+              id: linkedSegment('trace'),
+              label: ['trace.label', { ns: meta.id }],
+              icon: 'ph--line-segments--regular',
+              data: 'trace' as const,
+              position: 'last',
+            }),
+          ]),
+      }),
+    ]);
 
-  const { data } = await dispatch(createIntent(AssistantAction.CreateChat, { space }));
-  invariant(Obj.instanceOf(Assistant.Chat, data?.object));
-  await dispatch(createIntent(SpaceAction.AddObject, { target: space, object: data.object }));
-  return data.object;
-};
+    return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions);
+  }),
+);

package/src/capabilities/blueprint-definition.ts

@@ -2,65 +2,55 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, type Capability, contributes } from '@dxos/app-framework';
-import { templates } from '@dxos/assistant';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
 import {
-  Agent,
-  AssistantToolkit,
-  Discord,
+  AgentBlueprint,
+  AgentBlueprintHandlers,
+  AgentHandlers,
+  AgentWizardBlueprint,
+  AgentWizardHandlers,
+  BlueprintManagerBlueprint,
+  BlueprintManagerHandlers,
+  BrowserBlueprint,
+  DatabaseBlueprint,
+  DatabaseHandlers,
   DiscordBlueprint,
-  EntityExtraction,
-  Linear,
   LinearBlueprint,
-  Research,
-  ResearchBlueprint,
-  SystemToolkit,
+  PlanningBlueprint,
   WebSearchBlueprint,
+  MemoryBlueprint,
+  AutomationBlueprint,
 } from '@dxos/assistant-toolkit';
-import { Blueprint } from '@dxos/blueprints';
-import { type FunctionDefinition } from '@dxos/functions';
-
-import { analysis, list, load } from '../functions';
-
-// TODO(burdon): Document plugin structure (blueprint, functions, toolkit.)
-// TODO(burdon): Test framework for developing functions. Error handling.
-// TODO(burdon): Function naming pattern (noun-verb); fully-qualified?
-
-// TODO(wittjosiah): Factor out to a generic app-framework blueprint.
-const deckTools = ['open-item'];
-
-const functions: FunctionDefinition[] = [analysis, list, load];
-const tools = [...AssistantToolkit.tools, ...SystemToolkit.tools, ...deckTools];
-
-export const ASSISTANT_BLUEPRINT_KEY = 'dxos.org/blueprint/assistant';
-
-export const createBlueprint = (): Blueprint.Blueprint =>
-  Blueprint.make({
-    key: ASSISTANT_BLUEPRINT_KEY,
-    name: 'Assistant',
-    tools: Blueprint.toolDefinitions({ functions, tools }),
-    instructions: templates.system,
-  });
-
-const blueprint = createBlueprint();
-
-export default (): Capability<any>[] => [
-  contributes(Capabilities.Functions, functions),
-  contributes(Capabilities.BlueprintDefinition, blueprint),
-
-  // TODO(burdon): Factor out.
-  contributes(Capabilities.Functions, [Research.create, Research.research]),
-  contributes(Capabilities.BlueprintDefinition, ResearchBlueprint),
-
-  // TODO(burdon): Factor out.
-  contributes(Capabilities.Functions, [Agent.prompt, EntityExtraction.extract]),
-  contributes(Capabilities.BlueprintDefinition, WebSearchBlueprint),
-
-  // TODO(burdon): Factor out.
-  contributes(Capabilities.Functions, [Discord.fetch]),
-  contributes(Capabilities.BlueprintDefinition, DiscordBlueprint),
-
-  // TODO(burdon): Factor out.
-  contributes(Capabilities.Functions, [Linear.sync]),
-  contributes(Capabilities.BlueprintDefinition, LinearBlueprint),
-];
+// eslint-disable-next-line unused-imports/no-unused-imports
+import type { Blueprint } from '@dxos/compute';
+
+import { AssistantBlueprint } from '#blueprints';
+
+// TODO(dmaretskyi): Force this type for all Capability.makeModule calls.
+const blueprintDefinition: () => Effect.Effect<Capability.Capability<unknown>[]> = Capability.makeModule(() =>
+  Effect.succeed([
+    Capability.contributes(AppCapabilities.BlueprintDefinition, AssistantBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, BrowserBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, DatabaseBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, WebSearchBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, DiscordBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, LinearBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, AgentBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, PlanningBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, MemoryBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, AutomationBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, BlueprintManagerBlueprint),
+    Capability.contributes(AppCapabilities.BlueprintDefinition, AgentWizardBlueprint),
+
+    Capability.contributes(Capabilities.OperationHandler, AgentHandlers),
+    Capability.contributes(Capabilities.OperationHandler, AgentBlueprintHandlers),
+    Capability.contributes(Capabilities.OperationHandler, BlueprintManagerHandlers),
+    Capability.contributes(Capabilities.OperationHandler, DatabaseHandlers),
+    Capability.contributes(Capabilities.OperationHandler, AgentWizardHandlers),
+  ]),
+);
+
+export default blueprintDefinition;

package/src/capabilities/companion-chat-provisioner.ts

@@ -0,0 +1,163 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Registry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Graph, type Node } from '@dxos/app-graph';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Chat } from '@dxos/assistant-toolkit';
+import { Obj } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { DeckCapabilities, PLANK_COMPANION_TYPE, type StoredDeckState } from '@dxos/plugin-deck';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { byPosition } from '@dxos/util';
+
+import { ASSISTANT_COMPANION_VARIANT } from '#meta';
+import { AssistantCapabilities, AssistantOperation } from '#types';
+
+/**
+ * Non-React capability that watches deck companion state and provisions transient chats
+ * for active planks when the assistant companion is selected.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const operationInvoker = yield* Capability.get(Capabilities.OperationInvoker);
+    const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+    const registry: Registry.Registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const deckStateAtom = yield* Capability.get(DeckCapabilities.State);
+    const cacheAtom = yield* Capability.get(AssistantCapabilities.CompanionChatCache);
+    const stateAtom = yield* Capability.get(AssistantCapabilities.State);
+
+    const plankSubs = new Map<string, () => void>();
+
+    /** Unsubscribe a single plank and remove it from the map. */
+    const unsubPlank = (plankId: string) => {
+      plankSubs.get(plankId)?.();
+      plankSubs.delete(plankId);
+    };
+
+    /** Unsubscribe all per-plank subscriptions. */
+    const unsubAllPlanks = () => {
+      for (const unsub of plankSubs.values()) {
+        unsub();
+      }
+      plankSubs.clear();
+    };
+
+    /**
+     * Attempt to provision for a single plank.
+     * Returns true when the plank is resolved (provisioned or already cached)
+     * so the caller can tear down the connection subscription.
+     */
+    const provisionForPlank = (plankId: string, companionVariant: string | undefined): boolean => {
+      const node: Node.Node | null = Graph.getNode(graph, plankId).pipe(Option.getOrNull);
+      if (!node || !Obj.isObject(node.data) || Obj.instanceOf(Chat.Chat, node.data)) {
+        return false;
+      }
+
+      if (resolveEffectiveVariant(graph, plankId, companionVariant) !== ASSISTANT_COMPANION_VARIANT) {
+        return false;
+      }
+
+      const object = node.data;
+      const companionUri = Obj.getURI(object);
+      const cache = registry.get(cacheAtom);
+      if (cache[companionUri]) {
+        return true;
+      }
+
+      const db = Obj.getDatabase(object);
+      if (!db) {
+        return false;
+      }
+
+      void operationInvoker
+        .invokePromise(AssistantOperation.EnsureCompanionChat, { db, companionTo: object })
+        .catch((error) => log.warn('Failed to provision companion chat', { plankId, error }));
+
+      return false;
+    };
+
+    const provision = () => {
+      const deckState: StoredDeckState = registry.get(deckStateAtom);
+      const deck = deckState.decks[deckState.activeDeck];
+      if (!deck?.companionOpen) {
+        unsubAllPlanks();
+        return;
+      }
+
+      const plankIds = new Set(deck.solo ? [deck.solo] : deck.active);
+
+      // Remove subscriptions for planks that are no longer active.
+      for (const trackedId of plankSubs.keys()) {
+        if (!plankIds.has(trackedId)) {
+          unsubPlank(trackedId);
+        }
+      }
+
+      for (const plankId of plankIds) {
+        const resolved = provisionForPlank(plankId, deck.companionVariant);
+
+        if (resolved) {
+          // Already provisioned — no need to watch connections.
+          unsubPlank(plankId);
+        } else if (!plankSubs.has(plankId)) {
+          // Not yet resolved — subscribe to child connections so we re-try
+          // when graph builder extensions add companion nodes (after expand).
+          plankSubs.set(
+            plankId,
+            registry.subscribe(graph.connections(plankId, 'child'), () => {
+              if (provisionForPlank(plankId, deck.companionVariant)) {
+                unsubPlank(plankId);
+              }
+            }),
+          );
+        }
+      }
+    };
+
+    provision();
+
+    const unsub1 = registry.subscribe(deckStateAtom, provision);
+    const unsub2 = registry.subscribe(stateAtom, provision);
+
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        unsub1();
+        unsub2();
+        unsubAllPlanks();
+      }),
+    );
+  }),
+);
+
+/**
+ * Mirrors useSelectedCompanion fallback logic outside of React.
+ * Returns the variant that would actually be rendered for a given plank.
+ */
+const resolveEffectiveVariant = (
+  graph: Graph.BaseGraph,
+  plankId: string,
+  preferredVariant: string | undefined,
+): string | undefined => {
+  const companions = Graph.getConnections(graph, plankId, 'child')
+    .filter((node) => node.type === PLANK_COMPANION_TYPE)
+    .toSorted((a, b) => byPosition(a.properties, b.properties));
+
+  if (companions.length === 0) {
+    return undefined;
+  }
+
+  if (preferredVariant) {
+    const preferred = companions.find((companion) => getLinkedVariant(companion.id) === preferredVariant);
+    if (preferred) {
+      return getLinkedVariant(preferred.id);
+    }
+  }
+
+  return getLinkedVariant(companions[0].id);
+};