gloomberb 0.9.4 → 0.9.6

package/src/remote/controller.ts

@@ -0,0 +1,434 @@
+import type { Dispatch } from "react";
+import {
+  dockPane,
+  floatPane,
+  getDockLeafLayouts,
+  gridlockAllPanes,
+  insertAtRootEdge,
+  removeFloatingPanes,
+} from "../plugins/pane-manager";
+import type { PluginRegistry } from "../plugins/registry";
+import type { AppAction, AppState } from "../state/app/context";
+import { setPaneSettings } from "../pane-settings";
+import type { DesktopWindowBridge } from "../types/desktop-window";
+import { applyJsonPatch } from "./json-patch";
+import { revisionFor } from "./revision";
+import type {
+  RemoteControlRequest,
+  RemoteControlResponse,
+  RemoteJsonPatchOperation,
+  RemoteStateInclude,
+} from "./types";
+import type { RemoteUiRegistry } from "./semantic-tree";
+import { commandBarResultsFromNodes, isCommandBarInputNode } from "./command-bar";
+import { REMOTE_AGENT_HELP, remoteControlSchema } from "./schema";
+import {
+  asRecord,
+  fail,
+  mutationSummary,
+  numberInput,
+  ok,
+  optionalNumber,
+  optionalString,
+  stringInput,
+} from "./controller-utils";
+import {
+  buildGridDockRoot,
+  regionToDockPosition,
+  regionToRootEdge,
+  requirePaneInstance,
+  visiblePaneIds,
+} from "./layout-helpers";
+import { createRemoteResources } from "./resources";
+
+interface AppRemoteControllerOptions {
+  dispatch: Dispatch<AppAction>;
+  getState: () => AppState;
+  pluginRegistry: PluginRegistry;
+  uiRegistry: RemoteUiRegistry | null;
+  desktopWindowBridge?: DesktopWindowBridge;
+  afterMutation?: () => Promise<void> | void;
+}
+
+const DEFAULT_MUTATION_INCLUDE: RemoteStateInclude[] = ["app", "layout", "panes", "commandBar"];
+const DEFAULT_BATCH_INCLUDE: RemoteStateInclude[] = ["app", "layout", "panes", "commandBar"];
+
+export function createAppRemoteController({
+  dispatch,
+  getState,
+  pluginRegistry,
+  uiRegistry,
+  desktopWindowBridge,
+  afterMutation = () => {},
+}: AppRemoteControllerOptions) {
+  const { buildIncludedState, getResource, patchTarget } = createRemoteResources({
+    dispatch,
+    getState,
+    pluginRegistry,
+    uiRegistry,
+  });
+
+  const getAfterMutation = async (resource: string): Promise<unknown> => {
+    await afterMutation();
+    return getResource(resource);
+  };
+
+  const getAfterMutationSummary = async (extra?: Record<string, unknown>): Promise<unknown> => {
+    await afterMutation();
+    return mutationSummary(getState(), extra);
+  };
+
+  const openCommandBar = async (input: Record<string, unknown>): Promise<unknown> => {
+    const mode = optionalString(input, "mode") ?? "command";
+    const query = optionalString(input, "query") ?? "";
+    if (getState().commandBarOpen) {
+      dispatch({ type: "SET_COMMAND_BAR", open: false });
+      await afterMutation();
+    }
+    if (mode === "ticker") {
+      dispatch({ type: "SET_COMMAND_BAR", open: true, launch: { kind: "ticker-search", query } });
+      await afterMutation();
+      return mutationSummary(getState(), { commandBar: getResource("app://command-bar") });
+    }
+    if (mode !== "command" && mode !== "default") {
+      throw new Error(`Unsupported command-bar mode "${mode}".`);
+    }
+    dispatch({ type: "SET_COMMAND_BAR", open: true, query });
+    await afterMutation();
+    return mutationSummary(getState(), { commandBar: getResource("app://command-bar") });
+  };
+
+  const setVisibleCommandBarQuery = async (query: string): Promise<void> => {
+    dispatch({ type: "SET_COMMAND_BAR_QUERY", query });
+    await afterMutation();
+    const inputNode = (uiRegistry?.snapshot() ?? [])
+      .find((node) => isCommandBarInputNode(node) && node.metadata?.focused === true && node.actions.includes("setValue"));
+    if (!inputNode) return;
+    if (inputNode.metadata?.value === query) return;
+    await uiRegistry?.invoke(inputNode.id, "setValue", { value: query });
+    await afterMutation();
+  };
+
+  const activateCommandBarResult = async (input: Record<string, unknown>): Promise<unknown> => {
+    const nodeId = optionalString(input, "nodeId");
+    const index = optionalNumber(input, "index");
+    const itemId = optionalString(input, "itemId");
+    const label = optionalString(input, "label");
+    const results = commandBarResultsFromNodes(uiRegistry?.snapshot() ?? []);
+    const result = nodeId
+      ? results.find((entry) => entry.nodeId === nodeId)
+      : itemId
+        ? results.find((entry) => entry.itemId === itemId)
+        : label
+          ? results.find((entry) => entry.label === label)
+      : typeof index === "number"
+        ? results.find((entry) => entry.index === index)
+        : results.find((entry) => entry.selected) ?? results[0];
+    if (!result) throw new Error("No matching command-bar result is visible.");
+    if (!result.actions.includes("activate")) {
+      throw new Error(`Command-bar result "${result.nodeId}" does not expose activate.`);
+    }
+    await uiRegistry?.invoke(result.nodeId, "activate", result.actionInput);
+    return getAfterMutationSummary({ activatedResult: result });
+  };
+
+  const invokeMatchingUiNode = async (input: Record<string, unknown>): Promise<unknown> => {
+    const role = optionalString(input, "role");
+    const label = optionalString(input, "label");
+    const contains = optionalString(input, "contains");
+    const index = optionalNumber(input, "index");
+    const action = optionalString(input, "action") ?? "press";
+    const metadataFilter = asRecord(input.metadata);
+    const candidates = (uiRegistry?.snapshot() ?? []).filter((node) => {
+      if (role && node.role !== role) return false;
+      if (label && node.label !== label && node.metadata?.item && typeof node.metadata.item === "object") {
+        const item = node.metadata.item as Record<string, unknown>;
+        if (item.label !== label && item.id !== label) return false;
+      } else if (label && node.label !== label) {
+        return false;
+      }
+      if (contains) {
+        const haystack = [
+          node.label,
+          node.role,
+          JSON.stringify(node.metadata ?? {}),
+        ].filter((entry): entry is string => typeof entry === "string").join(" ").toLowerCase();
+        if (!haystack.includes(contains.toLowerCase())) return false;
+      }
+      for (const [key, value] of Object.entries(metadataFilter)) {
+        if (node.metadata?.[key] !== value) return false;
+      }
+      if (!node.actions.includes(action)) return false;
+      if (node.disabled) return false;
+      return true;
+    });
+    const node = typeof index === "number" ? candidates[index] : candidates[0];
+    if (!node) throw new Error("No matching semantic UI node is visible.");
+    const result = await uiRegistry?.invoke(node.id, action, input.input);
+    return getAfterMutationSummary({ invokedNode: node, result });
+  };
+
+  const call = async (operation: string, rawInput: unknown, dryRun?: boolean): Promise<unknown> => {
+    const input = asRecord(rawInput);
+    const dryRunResult = () => ({ operation, input, dryRun: true });
+    if (dryRun) return dryRunResult();
+
+    switch (operation) {
+      case "app.openCommandBar":
+        return openCommandBar(input);
+      case "app.closeCommandBar":
+        dispatch({ type: "SET_COMMAND_BAR", open: false });
+        return getAfterMutationSummary();
+      case "app.setCommandBarQuery":
+        await setVisibleCommandBarQuery(stringInput(input, "query"));
+        return mutationSummary(getState(), { commandBar: getResource("app://command-bar") });
+      case "app.search":
+        return openCommandBar(input);
+      case "app.switchPanel":
+        dispatch({ type: "SET_ACTIVE_PANEL", panel: input.panel === "right" ? "right" : "left" });
+        return getAfterMutationSummary();
+      case "app.notify":
+        pluginRegistry.notify({ body: stringInput(input, "body"), type: input.type as never });
+        return null;
+      case "commandBar.activateResult":
+        return activateCommandBarResult(input);
+      case "pane.show":
+        pluginRegistry.showPane(stringInput(input, "paneId"));
+        return getAfterMutationSummary();
+      case "pane.focus":
+        pluginRegistry.focusPane(stringInput(input, "paneId"));
+        return getAfterMutationSummary();
+      case "pane.close": {
+        const paneId = stringInput(input, "paneId");
+        pluginRegistry.hidePane(paneId);
+        return getAfterMutationSummary({ affectedPaneIds: [paneId] });
+      }
+      case "pane.createFromTemplate":
+        await pluginRegistry.createPaneFromTemplateAsyncFn(
+          stringInput(input, "templateId"),
+          asRecord(input.options),
+        );
+        return getAfterMutationSummary();
+      case "pane.setState":
+        dispatch({
+          type: "UPDATE_PANE_STATE",
+          paneId: stringInput(input, "paneId"),
+          patch: asRecord(input.patch),
+        });
+        return getAfterMutationSummary({ affectedPaneIds: [stringInput(input, "paneId")] });
+      case "pane.setSetting": {
+        const paneId = stringInput(input, "paneId");
+        const key = stringInput(input, "key");
+        const descriptor = pluginRegistry.resolvePaneSettings(paneId);
+        const field = descriptor?.settingsDef.fields.find((entry) => entry.key === key);
+        if (field) {
+          await pluginRegistry.applyPaneSettingValueFn(descriptor!.paneId, field, input.value);
+        } else {
+          const instanceId = descriptor?.paneId ?? paneId;
+          const current = pluginRegistry.resolvePaneSettings(instanceId)?.context.settings ?? {};
+          pluginRegistry.updateLayoutFn(setPaneSettings(getState().config.layout, instanceId, {
+            ...current,
+            [key]: input.value,
+          }));
+        }
+        return getAfterMutationSummary({ affectedPaneIds: [paneId] });
+      }
+      case "ticker.navigate":
+        pluginRegistry.navigateTicker(stringInput(input, "symbol"), { sourcePaneId: optionalString(input, "sourcePaneId") });
+        return getAfterMutationSummary({ symbol: stringInput(input, "symbol") });
+      case "ticker.pin":
+        pluginRegistry.pinTicker(stringInput(input, "symbol"), {
+          floating: input.floating === true,
+          forceNewPane: input.forceNewPane === true,
+          paneType: optionalString(input, "paneType"),
+        });
+        return getAfterMutationSummary({ symbol: stringInput(input, "symbol") });
+      case "ticker.select":
+        pluginRegistry.selectTicker(stringInput(input, "symbol"), optionalString(input, "paneId"));
+        return getAfterMutationSummary({ symbol: stringInput(input, "symbol") });
+      case "ticker.switchTab":
+        pluginRegistry.switchTab(stringInput(input, "tabId"), optionalString(input, "paneId"));
+        return getAfterMutationSummary({ tabId: stringInput(input, "tabId") });
+      case "layout.switch":
+        dispatch({ type: "SWITCH_LAYOUT", index: numberInput(input, "index") });
+        return getAfterMutationSummary();
+      case "layout.new":
+        dispatch({ type: "NEW_LAYOUT", name: stringInput(input, "name") });
+        return getAfterMutationSummary();
+      case "layout.rename":
+        dispatch({ type: "RENAME_LAYOUT", index: numberInput(input, "index"), name: stringInput(input, "name") });
+        return getAfterMutationSummary();
+      case "layout.duplicate":
+        dispatch({ type: "DUPLICATE_LAYOUT", index: numberInput(input, "index") });
+        return getAfterMutationSummary();
+      case "layout.delete":
+        dispatch({ type: "DELETE_LAYOUT", index: numberInput(input, "index") });
+        return getAfterMutationSummary();
+      case "layout.undo":
+        dispatch({ type: "UNDO_LAYOUT" });
+        return getAfterMutationSummary();
+      case "layout.redo":
+        dispatch({ type: "REDO_LAYOUT" });
+        return getAfterMutationSummary();
+      case "layout.gridlock": {
+        const { width, height } = pluginRegistry.getTermSizeFn();
+        pluginRegistry.updateLayoutFn(gridlockAllPanes(
+          getState().config.layout,
+          { x: 0, y: 0, width, height },
+          pluginRegistry.panes,
+        ));
+        return getAfterMutationSummary();
+      }
+      case "layout.closeFloating": {
+        const floatingPaneIds = getState().config.layout.floating.map((entry) => entry.instanceId);
+        pluginRegistry.updateLayoutFn(removeFloatingPanes(getState().config.layout));
+        return getAfterMutationSummary({ affectedPaneIds: floatingPaneIds });
+      }
+      case "layout.placePane": {
+        const pane = requirePaneInstance(getState().config.layout, stringInput(input, "paneId"));
+        const region = stringInput(input, "region");
+        const { width, height } = pluginRegistry.getTermSizeFn();
+        const def = pluginRegistry.panes.get(pane.paneId);
+        const nextLayout = region === "floating"
+          ? floatPane(getState().config.layout, pane.instanceId, width, height, def)
+          : optionalString(input, "relativeTo")
+            ? dockPane(getState().config.layout, pane.instanceId, {
+              relativeTo: requirePaneInstance(getState().config.layout, optionalString(input, "relativeTo")!).instanceId,
+              position: regionToDockPosition(region),
+            })
+            : insertAtRootEdge(getState().config.layout, pane.instanceId, regionToRootEdge(region));
+        pluginRegistry.updateLayoutFn(nextLayout);
+        return getAfterMutationSummary({ affectedPaneIds: [pane.instanceId] });
+      }
+      case "layout.focusRegion": {
+        const region = stringInput(input, "region");
+        const { width, height } = pluginRegistry.getTermSizeFn();
+        const leaves = getDockLeafLayouts(getState().config.layout, { x: 0, y: 0, width, height });
+        if (leaves.length === 0) throw new Error("No docked panes are visible.");
+        const target = leaves
+          .map((leaf) => {
+            const centerX = leaf.rect.x + leaf.rect.width / 2;
+            const centerY = leaf.rect.y + leaf.rect.height / 2;
+            const score = region === "left" ? centerX
+              : region === "right" ? -centerX
+                : region === "top" ? centerY
+                  : region === "bottom" ? -centerY
+                    : Math.abs(centerX - width / 2) + Math.abs(centerY - height / 2);
+            return { leaf, score };
+          })
+          .sort((a, b) => a.score - b.score)[0]!.leaf;
+        dispatch({ type: "FOCUS_PANE", paneId: target.instanceId });
+        return getAfterMutationSummary({ affectedPaneIds: [target.instanceId] });
+      }
+      case "layout.setGrid": {
+        const rawPaneIds = Array.isArray(input.paneIds) ? input.paneIds : visiblePaneIds(getState().config.layout);
+        const paneIds = rawPaneIds.map((id) => requirePaneInstance(getState().config.layout, String(id)).instanceId);
+        const nextLayout = {
+          ...getState().config.layout,
+          dockRoot: buildGridDockRoot(paneIds, optionalNumber(input, "columns")),
+          floating: getState().config.layout.floating.filter((entry) => !paneIds.includes(entry.instanceId)),
+          detached: (getState().config.layout.detached ?? []).filter((entry) => !paneIds.includes(entry.instanceId)),
+        };
+        pluginRegistry.updateLayoutFn(nextLayout);
+        return getAfterMutationSummary({ affectedPaneIds: paneIds });
+      }
+      case "desktop.popOutPane":
+        await desktopWindowBridge?.popOutPane?.(stringInput(input, "paneId"));
+        return getAfterMutationSummary({ affectedPaneIds: [stringInput(input, "paneId")] });
+      case "desktop.dockPane":
+        await desktopWindowBridge?.dockDetachedPane?.(stringInput(input, "paneId"));
+        return getAfterMutationSummary({ affectedPaneIds: [stringInput(input, "paneId")] });
+      case "desktop.closeDetachedPane":
+        await desktopWindowBridge?.closeDetachedPane?.(stringInput(input, "paneId"));
+        return getAfterMutationSummary({ affectedPaneIds: [stringInput(input, "paneId")] });
+      case "desktop.focusDetachedPane":
+        await desktopWindowBridge?.focusDetachedPane?.(stringInput(input, "paneId"));
+        return getAfterMutationSummary({ affectedPaneIds: [stringInput(input, "paneId")] });
+      case "capability.invoke":
+        return await pluginRegistry.capabilities.invoke(
+          stringInput(input, "capabilityId"),
+          stringInput(input, "operationId"),
+          input.payload ?? {},
+        );
+      case "ui.invoke": {
+        const result = await uiRegistry?.invoke(
+          stringInput(input, "nodeId"),
+          optionalString(input, "action") ?? "press",
+          input.input,
+        );
+        return getAfterMutationSummary({ result });
+      }
+      case "ui.invokeMatching":
+        return invokeMatchingUiNode(input);
+      default:
+        throw new Error(`Unknown remote operation "${operation}".`);
+    }
+  };
+
+  const handle = async (request: RemoteControlRequest): Promise<RemoteControlResponse> => {
+    try {
+      switch (request.type) {
+        case "help":
+          return ok(REMOTE_AGENT_HELP, revisionFor(REMOTE_AGENT_HELP));
+        case "schema":
+          return ok(remoteControlSchema());
+        case "get": {
+          const data = getResource(request.resource);
+          return ok(data, revisionFor(data), buildIncludedState(request.include));
+        }
+        case "call": {
+          const data = await call(request.operation, request.input, request.dryRun);
+          return ok(data, undefined, buildIncludedState(request.include, request.dryRun ? [] : DEFAULT_MUTATION_INCLUDE));
+        }
+        case "patch": {
+          const target = patchTarget(request.resource);
+          const currentRev = revisionFor(target.value);
+          if (request.expectRev && request.expectRev !== currentRev) {
+            throw new Error(`Revision mismatch for ${request.resource}: expected ${request.expectRev}, got ${currentRev}.`);
+          }
+          const nextValue = applyJsonPatch(target.value, request.patch as RemoteJsonPatchOperation[]);
+          if (!request.dryRun) {
+            await target.apply(nextValue);
+            await afterMutation();
+          }
+          return ok(
+            nextValue,
+            revisionFor(nextValue),
+            buildIncludedState(request.include, request.dryRun ? [] : DEFAULT_MUTATION_INCLUDE),
+          );
+        }
+        case "batch": {
+          const responses = [];
+          const haltOnError = request.haltOnError !== false;
+          let haltedAt: number | null = null;
+          for (const entry of request.requests) {
+            const entryRequest = request.dryRun && (entry.type === "call" || entry.type === "patch")
+              ? { ...entry, dryRun: true, include: entry.include ?? [] } as RemoteControlRequest
+              : (entry.type === "call" || entry.type === "patch")
+                ? { ...entry, include: entry.include ?? [] } as RemoteControlRequest
+                : entry;
+            const response = await handle(entryRequest);
+            responses.push(response);
+            if (request.settle === "afterEach") await afterMutation();
+            if (!response.ok && haltOnError) {
+              haltedAt = responses.length - 1;
+              break;
+            }
+          }
+          if (request.settle === "afterBatch") await afterMutation();
+          return ok({
+            ok: responses.every((response) => response.ok),
+            haltedAt,
+            responses,
+          }, undefined, buildIncludedState(request.include, request.dryRun ? [] : DEFAULT_BATCH_INCLUDE));
+        }
+        default:
+          throw new Error(`Unknown remote request type: ${(request as { type?: unknown }).type}`);
+      }
+    } catch (error) {
+      return fail("remote_error", error);
+    }
+  };
+
+  return { handle };
+}

package/src/remote/endpoint.ts

@@ -0,0 +1,41 @@
+import { readFile, rm, writeFile, mkdir } from "fs/promises";
+import { dirname, join } from "path";
+import type { RemoteAppKind, RemoteEndpoint } from "./types";
+
+const DEFAULT_ENDPOINT_FILE = "remote-control.json";
+
+export function remoteEndpointPath(dataDir: string, appKind?: RemoteAppKind): string {
+  return join(dataDir, appKind ? `remote-control.${appKind}.json` : DEFAULT_ENDPOINT_FILE);
+}
+
+export async function readRemoteEndpoint(dataDir: string, appKind?: RemoteAppKind): Promise<RemoteEndpoint> {
+  const raw = await readFile(remoteEndpointPath(dataDir, appKind), "utf-8");
+  return JSON.parse(raw) as RemoteEndpoint;
+}
+
+export async function writeRemoteEndpointFiles(dataDir: string, endpoint: RemoteEndpoint): Promise<void> {
+  await writeRemoteEndpoint(remoteEndpointPath(dataDir, endpoint.appKind), endpoint);
+  await writeRemoteEndpoint(remoteEndpointPath(dataDir), endpoint);
+}
+
+export async function removeRemoteEndpointFiles(dataDir: string, endpoint: RemoteEndpoint): Promise<void> {
+  await Promise.all([
+    removeRemoteEndpointIfOwned(remoteEndpointPath(dataDir, endpoint.appKind), endpoint),
+    removeRemoteEndpointIfOwned(remoteEndpointPath(dataDir), endpoint),
+  ]);
+}
+
+async function writeRemoteEndpoint(filePath: string, endpoint: RemoteEndpoint): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(endpoint, null, 2), { encoding: "utf-8", mode: 0o600 });
+}
+
+async function removeRemoteEndpointIfOwned(filePath: string, endpoint: RemoteEndpoint): Promise<void> {
+  try {
+    const existing = JSON.parse(await readFile(filePath, "utf-8")) as RemoteEndpoint;
+    if (existing.pid !== endpoint.pid || existing.token !== endpoint.token || existing.port !== endpoint.port) return;
+    await rm(filePath, { force: true });
+  } catch {
+    await rm(filePath, { force: true });
+  }
+}

package/src/remote/json-patch.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { applyJsonPatch } from "./json-patch";
+
+describe("applyJsonPatch", () => {
+  test("adds, replaces, and removes nested values without mutating the source", () => {
+    const source: { panes: Array<{ id: string; state: Record<string, unknown> }> } = {
+      panes: [
+        { id: "one", state: { symbol: "NVDA", stale: true } },
+      ],
+    };
+
+    const patched = applyJsonPatch(source, [
+      { op: "replace", path: "/panes/0/state/symbol", value: "AAPL" },
+      { op: "remove", path: "/panes/0/state/stale" },
+      { op: "add", path: "/panes/0/state/tab", value: "chart" },
+    ]);
+
+    expect(patched).toEqual({
+      panes: [
+        { id: "one", state: { symbol: "AAPL", tab: "chart" } },
+      ],
+    });
+    expect(source.panes[0]!.state).toEqual({ symbol: "NVDA", stale: true });
+  });
+
+  test("appends to arrays with dash pointer", () => {
+    expect(applyJsonPatch({ values: ["a"] }, [
+      { op: "add", path: "/values/-", value: "b" },
+    ])).toEqual({ values: ["a", "b"] });
+  });
+});

package/src/remote/json-patch.ts

@@ -0,0 +1,89 @@
+import type { RemoteJsonPatchOperation } from "./types";
+
+function decodePointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function pointerSegments(path: string): string[] {
+  if (path === "") return [];
+  if (!path.startsWith("/")) {
+    throw new Error(`JSON patch path must start with "/": ${path}`);
+  }
+  return path.slice(1).split("/").map(decodePointerSegment);
+}
+
+function cloneJson<T>(value: T): T {
+  return value == null ? value : JSON.parse(JSON.stringify(value)) as T;
+}
+
+function containerFor(root: unknown, path: string): { parent: unknown; key: string } {
+  const segments = pointerSegments(path);
+  if (segments.length === 0) {
+    throw new Error("Patch path cannot target the document root.");
+  }
+  let parent = root;
+  for (const segment of segments.slice(0, -1)) {
+    if (Array.isArray(parent)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= parent.length) {
+        throw new Error(`Invalid array index in JSON patch path: ${segment}`);
+      }
+      parent = parent[index];
+    } else if (parent && typeof parent === "object") {
+      parent = (parent as Record<string, unknown>)[segment];
+    } else {
+      throw new Error(`Cannot descend into non-object patch path: ${path}`);
+    }
+  }
+  return { parent, key: segments[segments.length - 1]! };
+}
+
+function applyOperation(root: unknown, operation: RemoteJsonPatchOperation): void {
+  const { parent, key } = containerFor(root, operation.path);
+  if (Array.isArray(parent)) {
+    const index = key === "-" ? parent.length : Number(key);
+    if (!Number.isInteger(index) || index < 0 || index > parent.length) {
+      throw new Error(`Invalid array index in JSON patch path: ${key}`);
+    }
+    if (operation.op === "remove") {
+      if (index >= parent.length) throw new Error(`Cannot remove missing array index: ${key}`);
+      parent.splice(index, 1);
+      return;
+    }
+    if (operation.op === "add") {
+      parent.splice(index, 0, operation.value);
+      return;
+    }
+    if (index >= parent.length) throw new Error(`Cannot replace missing array index: ${key}`);
+    parent[index] = operation.value;
+    return;
+  }
+
+  if (!parent || typeof parent !== "object") {
+    throw new Error(`Cannot patch non-object at path: ${operation.path}`);
+  }
+
+  const target = parent as Record<string, unknown>;
+  if (operation.op === "remove") {
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+      throw new Error(`Cannot remove missing key: ${key}`);
+    }
+    delete target[key];
+    return;
+  }
+  if (operation.op === "replace" && !Object.prototype.hasOwnProperty.call(target, key)) {
+    throw new Error(`Cannot replace missing key: ${key}`);
+  }
+  target[key] = operation.value;
+}
+
+export function applyJsonPatch<T>(value: T, patch: RemoteJsonPatchOperation[]): T {
+  const next = cloneJson(value);
+  for (const operation of patch) {
+    if (operation.op !== "add" && operation.op !== "replace" && operation.op !== "remove") {
+      throw new Error(`Unsupported JSON patch operation: ${(operation as { op?: unknown }).op}`);
+    }
+    applyOperation(next, operation);
+  }
+  return next;
+}

package/src/remote/layout-helpers.ts

@@ -0,0 +1,62 @@
+import {
+  getDockedPaneIds,
+} from "../plugins/pane-manager";
+import type { DockLayoutNode, LayoutConfig, PaneInstanceConfig } from "../types/config";
+
+export function requirePaneInstance(layout: LayoutConfig, paneId: string): PaneInstanceConfig {
+  const instance = layout.instances.find((entry) => entry.instanceId === paneId)
+    ?? layout.instances.find((entry) => entry.paneId === paneId);
+  if (!instance) throw new Error(`Unknown pane "${paneId}".`);
+  return instance;
+}
+
+export function buildGridDockRoot(paneIds: string[], columns?: number): DockLayoutNode | null {
+  if (paneIds.length === 0) return null;
+  const columnCount = Math.max(1, Math.min(
+    paneIds.length,
+    Number.isInteger(columns) && columns! > 0 ? columns! : Math.ceil(Math.sqrt(paneIds.length)),
+  ));
+  const rows: DockLayoutNode[] = [];
+  for (let index = 0; index < paneIds.length; index += columnCount) {
+    rows.push(buildSplit(
+      paneIds.slice(index, index + columnCount).map((instanceId) => ({ kind: "pane", instanceId })),
+      "horizontal",
+    ));
+  }
+  return buildSplit(rows, "vertical");
+}
+
+export function visiblePaneIds(layout: LayoutConfig): string[] {
+  const ids = new Set<string>();
+  getDockedPaneIds(layout).forEach((id) => ids.add(id));
+  layout.floating.forEach((entry) => ids.add(entry.instanceId));
+  (layout.detached ?? []).forEach((entry) => ids.add(entry.instanceId));
+  return [...ids];
+}
+
+export function regionToDockPosition(region: string): "left" | "right" | "above" | "below" {
+  if (region === "left" || region === "right") return region;
+  if (region === "top") return "above";
+  if (region === "bottom") return "below";
+  throw new Error(`Unsupported dock region "${region}".`);
+}
+
+export function regionToRootEdge(region: string): "left" | "right" | "top" | "bottom" {
+  if (region === "left" || region === "right" || region === "top" || region === "bottom") return region;
+  throw new Error(`Unsupported root-edge region "${region}".`);
+}
+
+function buildSplit(nodes: DockLayoutNode[], axis: "horizontal" | "vertical"): DockLayoutNode {
+  if (nodes.length === 0) throw new Error("Cannot build an empty dock split.");
+  if (nodes.length === 1) return nodes[0]!;
+  const splitIndex = Math.ceil(nodes.length / 2);
+  const firstNodes = nodes.slice(0, splitIndex);
+  const secondNodes = nodes.slice(splitIndex);
+  return {
+    kind: "split",
+    axis,
+    ratio: firstNodes.length / nodes.length,
+    first: buildSplit(firstNodes, axis),
+    second: buildSplit(secondNodes, axis),
+  };
+}