@synnaxlabs/client 0.56.2 → 0.57.1

package/src/panel/client.ts

@@ -0,0 +1,327 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { array, type destructor, primitive, zod } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { actions } from "@/actions";
+import { ontology } from "@/ontology";
+import { createOf, kindOf, reduceAll } from "@/panel/actions";
+import {
+  type Action,
+  dispatchReqZ,
+  rename as renameAction,
+  scopedActionZ,
+} from "@/panel/actions.gen";
+import {
+  type Key,
+  keyZ,
+  type New,
+  ontologyID,
+  type Panel,
+  panelZ,
+} from "@/panel/types.gen";
+import { query } from "@/query";
+
+export const SET_CHANNEL_NAME = "sy_panel_set";
+export const DELETE_CHANNEL_NAME = "sy_panel_delete";
+
+const retrieveReqZ = z.object({
+  keys: keyZ.array().optional(),
+  parent: ontology.idZ.optional(),
+  searchTerm: z.string().optional(),
+  offset: z.int().optional(),
+  limit: z.int().optional(),
+  ignoreNotFoundError: z.boolean().optional(),
+});
+const retrieveMultiParamsZ = retrieveReqZ.or(query.keyListZ(keyZ));
+export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
+const createReqZ = z.object({ panels: panelZ.array() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
+
+const retrieveResZ = z.object({ panels: panelZ.array().default(() => []) });
+const createResZ = z.object({ panels: panelZ.array() });
+const emptyResZ = z.object({});
+
+const isChildOf = (rel: ontology.Relationship, parent: ontology.ID): boolean =>
+  ontology.matchRelationship(rel, {
+    from: parent,
+    type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+    to: { type: "panel" },
+  });
+
+/**
+ * Client-side matching for a request: exact for key sets. Server-computed
+ * shapes (search, limit/offset) never reach this filter; they refetch instead.
+ */
+const requestFilter = (req: RetrieveRequest): ((p: Panel) => boolean) => {
+  const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+  return (p) => keySet == null || keySet.has(p.key);
+};
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  ontology: ontology.Client;
+  cache: query.Cache;
+}
+
+export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Panel> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, Panel>;
+  private readonly dispatcher: actions.Controller<Key, Panel, Action>;
+
+  constructor(cfg: ClientConfig) {
+    const { cache, ontology: ontologyClient } = cfg;
+    // Dispatch mutates documents server-side, so fetched copies never clobber
+    // a doc holding locally replayed edits: the table hydrates if-absent.
+    const store = cache.createTable<Key, Panel>({
+      name: "panels",
+      hydrate: "if-absent",
+      fetch: async (keys) =>
+        await this.execRetrieve({ keys, ignoreNotFoundError: true }),
+      listen: [query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ)],
+    });
+    const dispatcher = new actions.Controller<Key, Panel, Action>({
+      store,
+      onError: cache.onError,
+      reduce: reduceAll,
+      kindOf,
+      createOf,
+    });
+    cache.listen(dispatcher.listener(SET_CHANNEL_NAME, scopedActionZ));
+    super(cache, {
+      name: "panel",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.fetchRequest(req),
+        matches: (panel, req) => {
+          if (!requestFilter(req)(panel)) return false;
+          const parent = "parent" in req ? req.parent : undefined;
+          return parent == null || this.isCachedChild(parent, panel.key);
+        },
+        watch: [
+          query.watch(
+            ontologyClient.cache.relationships,
+            (event, req: RetrieveRequest) => {
+              if (req.parent == null) return null;
+              const rel =
+                event.variant === "set"
+                  ? event.value
+                  : ontology.relationshipZ.parse(event.key);
+              if (!isChildOf(rel, req.parent)) return null;
+              return [rel.to.key];
+            },
+          ),
+        ],
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
+    this.dispatcher = dispatcher;
+  }
+
+  /** All panels currently in the cache. */
+  listCached(): Panel[] {
+    return this.store.get();
+  }
+
+  private isCachedChild(parent: ontology.ID, key: Key): boolean {
+    return this.cfg.ontology.cache.relationships.has(
+      ontology.relationshipToString({
+        from: parent,
+        type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+        to: ontologyID(key),
+      }),
+    );
+  }
+
+  async create(panel: New, opts?: query.WriteOptions<Panel[]>): Promise<Panel>;
+  async create(panels: New[], opts?: query.WriteOptions<Panel[]>): Promise<Panel[]>;
+  async create(
+    panels: New | New[],
+    opts: query.WriteOptions<Panel[]> = {},
+  ): Promise<Panel | Panel[]> {
+    const isMany = Array.isArray(panels);
+    const optimistic = array
+      .toArray(panels)
+      .map((p) => zod.parse(panelZ, p, { label: "panel" }));
+    const res = await query.optimistic({
+      rollbacks: [this.store.set(optimistic)],
+      onOptimistic: () => opts.onOptimistic?.(optimistic),
+      commit: async () => {
+        // onOptimistic may dispatch further local mutations against these keys
+        // before the panels exist on the cluster. Send the latest cached docs so
+        // the server response doesn't stomp those changes back out.
+        const latest = optimistic.map((p) => this.store.get(p.key) ?? p);
+        return await this.cfg.unary.send(
+          "/panel/create",
+          { panels: latest },
+          createReqZ,
+          createResZ,
+        );
+      },
+    });
+    this.store.set(res.panels);
+    return isMany ? res.panels : res.panels[0];
+  }
+
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const rename = () => [
+      query.partialUpdate(this.store, key, { name }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+    ];
+    // Rename routes through dispatch so the action channel broadcasts the change
+    // to other connected clients.
+    await query.optimistic({
+      rollbacks: rename(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () => await this.sendDispatch(key, "", [renameAction({ name })]),
+    });
+    rename();
+  }
+
+  /**
+   * Applies actions to the cached panel and sends them to the server, recording an
+   * undoable entry. Returns false without side effects when the panel isn't cached.
+   * Rolls back the local apply and rethrows on send failure.
+   */
+  async dispatch(
+    key: Key,
+    actions: Action | Action[],
+    opts: actions.Options<Panel, Action> = {},
+  ): Promise<boolean> {
+    return await this.dispatcher.dispatch(
+      key,
+      array.toArray(actions),
+      this.dispatchSender(key),
+      opts,
+    );
+  }
+
+  /**
+   * Reverts the panel's most recent undoable entry. Returns false when
+   * nothing is undoable.
+   */
+  async undo(key: Key): Promise<boolean> {
+    return await this.dispatcher.undo(key, this.dispatchSender(key));
+  }
+
+  /**
+   * Re-applies the panel's most recently undone entry. Returns false when
+   * nothing is redoable.
+   */
+  async redo(key: Key): Promise<boolean> {
+    return await this.dispatcher.redo(key, this.dispatchSender(key));
+  }
+
+  /** Whether the panel has a live undo entry. */
+  hasUndo(key: Key): boolean {
+    return this.dispatcher.hasUndo(key);
+  }
+
+  /** Whether the panel has a live redo entry. */
+  hasRedo(key: Key): boolean {
+    return this.dispatcher.hasRedo(key);
+  }
+
+  /**
+   * Subscribes to changes in the panel's undo/redo stacks. Returns a
+   * destructor that unsubscribes.
+   */
+  onUndoStateChange(callback: () => void, key?: Key): destructor.Destructor {
+    return this.dispatcher.onUndoStateChange(callback, key);
+  }
+
+  /** Stages actions committed atomically as one undoable entry. */
+  beginTransaction(key: Key, kind?: string): actions.Transaction<Action> {
+    return this.dispatcher.transaction(key, this.dispatchSender(key), kind);
+  }
+
+  private dispatchSender(key: Key): actions.SendDispatch<Action> {
+    return async (actions, dispatchKey) =>
+      await this.sendDispatch(key, dispatchKey, actions);
+  }
+
+  private async sendDispatch(
+    key: Key,
+    dispatchKey: string,
+    actions: Action[],
+  ): Promise<void> {
+    await this.cfg.unary.send(
+      "/panel/dispatch",
+      { key, dispatchKey, actions },
+      dispatchReqZ,
+      emptyResZ,
+    );
+  }
+
+  async delete(key: Key, opts?: query.WriteOptions): Promise<void>;
+  async delete(keys: Key[], opts?: query.WriteOptions): Promise<void>;
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => [
+      this.cfg.ontology.cache.deleteResources(ontologyID(keysArr)),
+      this.store.delete(keysArr),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/panel/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
+  }
+
+  /** Subscribes to every panel delete delivered to the cache. */
+  onDelete(handler: (key: Key) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "delete") handler(event.key);
+    });
+  }
+
+  /** Subscribes to every panel set delivered to the cache. */
+  onSet(handler: (panel: Panel) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "set") handler(event.value);
+    });
+  }
+
+  private async execRetrieve(req: RetrieveRequest): Promise<Panel[]> {
+    const res = await this.cfg.unary.send(
+      "/panel/retrieve",
+      req,
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return res.panels;
+  }
+
+  // Parent queries resolve membership through the ontology graph, then fetch
+  // the member panels; the panel retrieve endpoint knows nothing of parents.
+  private async fetchRequest(req: RetrieveRequest): Promise<Panel[]> {
+    const { parent, ...rest } = req;
+    if (parent != null) {
+      const children = await this.cfg.ontology.children.retrieve({
+        ids: parent,
+        types: ["panel"],
+      });
+      const keys = children.map(({ id }) => id.key);
+      if (keys.length === 0) return [];
+      rest.keys = keys;
+    }
+    return await this.execRetrieve(rest);
+  }
+}

package/src/panel/external.ts

@@ -0,0 +1,14 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * from "@/panel/actions";
+export * from "@/panel/actions.gen";
+export * from "@/panel/client";
+export * from "@/panel/tree";
+export * from "@/panel/types.gen";

package/src/panel/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as panel from "@/panel/external";

package/src/panel/tree.ts

@@ -0,0 +1,163 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type location, type spatial } from "@synnaxlabs/x";
+
+import { type ontology } from "@/ontology";
+import { type LeafNode, type Node, type Tab, type TabKey } from "@/panel/types.gen";
+
+// Nodes in the panel tree are identified by path-derived numeric keys: the root
+// is ROOT_NODE_KEY, and a split's children are childNodeKey(key, "first" | "last").
+// The scheme is shared with the Go and TypeScript reducers; every consumer that
+// addresses nodes (dispatching InsertTab/MoveTab, adapting the tree for
+// rendering) must use these helpers rather than re-deriving the math.
+export const ROOT_NODE_KEY = 1;
+
+/** childNodeKey returns the path key of a split's child on the given side. */
+export const childNodeKey = (pathKey: number, side: spatial.Order): number =>
+  side === "first" ? pathKey * 2 : pathKey * 2 + 1;
+
+/**
+ * splitSide returns the child slot the new empty leaf occupies when a leaf is
+ * split at the given location: "first" for left/top, "last" otherwise. The
+ * convention is shared by location-bearing InsertTab/MoveTab and SplitTab.
+ */
+export const splitSide = (loc: location.Outer): spatial.Order =>
+  loc === "left" || loc === "top" ? "first" : "last";
+
+const pathDirections = (pathKey: number): boolean[] => {
+  if (pathKey <= ROOT_NODE_KEY) return [];
+  const bits: boolean[] = [];
+  while (pathKey > ROOT_NODE_KEY) {
+    bits.unshift((pathKey & 1) === 1);
+    pathKey >>= 1;
+  }
+  return bits;
+};
+
+/**
+ * findNode returns the node at the given path key, or null when the path does
+ * not exist in the tree.
+ */
+export const findNode = (root: Node | undefined, pathKey: number): Node | undefined => {
+  if (root == null) return undefined;
+  let n: Node = root;
+  for (const isLast of pathDirections(pathKey)) {
+    if (n.variant !== "split") return undefined;
+    n = isLast ? n.last : n.first;
+  }
+  return n;
+};
+
+/** findTab returns the tab with the given key, or null when absent. */
+export const findTab = (node: Node | undefined, key?: string): Tab | undefined => {
+  if (node == null || key == null) return undefined;
+  if (node.variant === "leaf") return node.tabs.find((t) => t.key === key);
+  return findTab(node.first, key) ?? findTab(node.last, key);
+};
+
+/**
+ * findTabByResource returns the tab whose resource variant displays the given
+ * ontology ID, or null when no tab backs that resource. A resource may back at
+ * most one tab per panel, so openers use this to select the existing tab
+ * instead of inserting a duplicate.
+ */
+export const findTabByResource = (
+  node: Node | undefined,
+  resource: ontology.ID,
+): Tab | undefined => {
+  if (node == null) return undefined;
+  if (node.variant === "leaf")
+    return node.tabs.find(
+      (t) =>
+        t.variant === "resource" &&
+        t.resource.type === resource.type &&
+        t.resource.key === resource.key,
+    );
+  return (
+    findTabByResource(node.first, resource) ?? findTabByResource(node.last, resource)
+  );
+};
+
+/**
+ * findTabByType returns the tab whose view variant carries the given type, or
+ * null when no view of that type is present. Openers of singleton views use this
+ * to select the existing tab instead of inserting a duplicate.
+ */
+export const findTabByType = (
+  node: Node | undefined,
+  type: string,
+): Tab | undefined => {
+  if (node == null) return undefined;
+  if (node.variant === "leaf")
+    return node.tabs.find((t) => t.variant === "view" && t.type === type);
+  return findTabByType(node.first, type) ?? findTabByType(node.last, type);
+};
+
+/** leafTabGroups returns each leaf's ordered tab keys, leaves in traversal order. */
+export const leafTabGroups = (node: Node | undefined): TabKey[][] => {
+  if (node == null) return [];
+  if (node.variant === "leaf") return [node.tabs.map((t) => t.key)];
+  return [...leafTabGroups(node.first), ...leafTabGroups(node.last)];
+};
+
+/** firstTab returns the first tab in traversal order, or null for an empty tree. */
+export const firstTab = (node: Node | undefined): Tab | undefined => {
+  if (node == null) return undefined;
+  if (node.variant === "leaf") return node.tabs[0];
+  return firstTab(node.first) ?? firstTab(node.last);
+};
+
+const findLeafPath = (
+  node: Node | undefined,
+  path: number,
+  match: (tabs: Tab[]) => boolean,
+): number | undefined => {
+  if (node == null) return undefined;
+  if (node.variant === "leaf") return match(node.tabs) ? path : undefined;
+  return (
+    findLeafPath(node.first, childNodeKey(path, "first"), match) ??
+    findLeafPath(node.last, childNodeKey(path, "last"), match)
+  );
+};
+
+/** tabLeafPath returns the path key of the leaf holding the given tab, or null. */
+export const tabLeafPath = (
+  root: Node | undefined,
+  tabKey: string,
+): number | undefined =>
+  findLeafPath(root, ROOT_NODE_KEY, (tabs) => tabs.some((t) => t.key === tabKey));
+
+/** findTabLeaf returns the leaf node holding the given tab, or null when absent. */
+export const findTabLeaf = (
+  root: Node | undefined,
+  tabKey: string,
+): LeafNode | undefined => {
+  const leafPath = tabLeafPath(root, tabKey);
+  if (leafPath == null) return undefined;
+  const leaf = findNode(root, leafPath);
+  return leaf?.variant === "leaf" ? leaf : undefined;
+};
+
+/**
+ * canSplitTab reports whether the tab can be split off into its own pane: true
+ * when the tab shares its leaf with at least one other tab. Splitting the only
+ * tab in a leaf is a no-op (the SplitTab action rejects it), so menu
+ * affordances for the split should gate on this.
+ */
+export const canSplitTab = (root: Node | undefined, tabKey: string): boolean => {
+  const leafPath = tabLeafPath(root, tabKey);
+  if (leafPath == null) return false;
+  const leaf = findNode(root, leafPath);
+  return leaf?.variant === "leaf" && leaf.tabs.length >= 2;
+};
+
+/** firstLeafPath returns the path key of the first leaf in traversal order. */
+export const firstLeafPath = (root: Node | undefined): number | undefined =>
+  findLeafPath(root, ROOT_NODE_KEY, () => true);

package/src/panel/types.gen.ts

@@ -0,0 +1,164 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { caseconv, record, spatial, uuid } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { ontology } from "@/ontology";
+
+/**
+ * View is an inline, self-describing view: a Console-owned type plus an opaque
+ * configuration payload, with no backing core document. Used for app-views and tools
+ * (docs, explorers, task forms, and the selector pickers).
+ */
+export const viewZ = z.object({
+  /**
+   * type is the Console-owned view type identifier (e.g., 'docs', 'selector') used to
+   * select a renderer.
+   */
+  type: z.string(),
+  /**
+   * args is an opaque, Console-owned configuration payload for the view. Core never
+   * interprets it; it round-trips as-is.
+   */
+  args: caseconv.preserveCase(record.unknownZ().default(() => ({}))),
+});
+export interface View extends z.infer<typeof viewZ> {}
+
+export const tabKeyZ = z.uuid();
+export type TabKey = z.infer<typeof tabKeyZ>;
+
+export const keyZ = z.uuid();
+export type Key = z.infer<typeof keyZ>;
+
+/** TabBase carries the identity shared by every tab variant. */
+export const tabBaseZ = z.object({
+  /**
+   * key is the stable unique identifier of this tab within the panel. It is independent
+   * of the tab's content, so a tab's content may be swapped without changing the tab's
+   * identity or position.
+   */
+  key: tabKeyZ.default(uuid.create),
+});
+export interface TabBase extends z.infer<typeof tabBaseZ> {}
+
+/** ResourceTab is a tab displaying a backing core document. */
+export const resourceTabZ = tabBaseZ.extend({
+  variant: z.literal("resource"),
+  /**
+   * resource is the visualization resource displayed by this tab, set via
+   * SetTabResource.
+   */
+  resource: ontology.idZ,
+});
+export interface ResourceTab extends z.infer<typeof resourceTabZ> {}
+
+/**
+ * ViewTab is a tab displaying an inline, self-describing view. Unlike a resource, a
+ * view has no backing core document: it carries its own type and opaque args. Used for
+ * app-views and tools (docs, explorers, task forms, and the selector pickers).
+ */
+export const viewTabZ = tabBaseZ.extend(viewZ.shape).extend({
+  variant: z.literal("view"),
+});
+export interface ViewTab extends z.infer<typeof viewTabZ> {}
+
+export const TAB_TYPES = ["resource", "view"] as const;
+export const tabTypeZ = z.enum(TAB_TYPES);
+export type TabType = z.infer<typeof tabTypeZ>;
+
+/**
+ * Tab is a single tab in a leaf. Tab content is a discriminated union: a resource (a
+ * backing core document, e.g. a line plot) or a view (an inline, self-describing
+ * app-view, e.g. docs). A freshly created tab is a view whose type is a selector
+ * picker; SetTabResource or SetTabView swaps content in place. Display attributes
+ * (name, icon, closability) are resolved at render time from the content. A resource
+ * may back at most one tab per panel; views may repeat.
+ */
+export const tabZ = z.discriminatedUnion("variant", [resourceTabZ, viewTabZ]);
+export type Tab = ResourceTab | ViewTab;
+
+export const TAB_SCHEMAS: {
+  [K in TabType]: z.ZodType<Extract<Tab, { variant: K }>>;
+} = {
+  resource: resourceTabZ,
+  view: viewTabZ,
+};
+export type NewTab = z.input<typeof tabZ>;
+
+/** LeafNode is a leaf node in the panel tree displaying a tab strip. */
+export const leafNodeZ = z.object({
+  variant: z.literal("leaf"),
+  /** tabs is the ordered list of tabs in this leaf. */
+  tabs: tabZ.array().default(() => []),
+});
+export interface LeafNode extends z.infer<typeof leafNodeZ> {}
+
+/** SplitNode is an interior split node dividing its area between two children. */
+export const splitNodeZ = z.object({
+  variant: z.literal("split"),
+  /** direction is the axis along which this node is split. */
+  direction: spatial.directionZ,
+  /**
+   * size is the fraction in [0, 1] of the parent area allocated to first. The remainder
+   * is allocated to last.
+   */
+  size: spatial.decimalZ,
+  /** first is the first child (left for x, top for y). */
+  get first(): z.ZodType<Node> {
+    return nodeZ;
+  },
+  /** last is the second child (right for x, bottom for y). */
+  get last(): z.ZodType<Node> {
+    return nodeZ;
+  },
+});
+export interface SplitNode extends z.infer<typeof splitNodeZ> {}
+
+export const NODE_TYPES = ["leaf", "split"] as const;
+export const nodeTypeZ = z.enum(NODE_TYPES);
+export type NodeType = z.infer<typeof nodeTypeZ>;
+
+/**
+ * Node is a node in the panel tree: either a leaf displaying a tab strip or an interior
+ * split. Nodes are identified by path-derived numeric keys during traversal (1 = root,
+ * 2k = first child, 2k+1 = last child).
+ */
+export const nodeZ = z.discriminatedUnion("variant", [leafNodeZ, splitNodeZ]);
+export type Node = LeafNode | SplitNode;
+
+export const NODE_SCHEMAS: {
+  [K in NodeType]: z.ZodType<Extract<Node, { variant: K }>>;
+} = {
+  leaf: leafNodeZ,
+  split: splitNodeZ,
+};
+
+/** Panel is a project-owned tree of visualization tabs. */
+export const panelZ = z.object({
+  /** key is the unique identifier for this panel. */
+  key: keyZ.default(uuid.create),
+  /** name is a human-readable name for the panel. */
+  name: z.string().min(1, "name is required"),
+  /** root is the root of the panel tree. */
+  root: nodeZ.prefault({ variant: "leaf", tabs: [] }),
+  /**
+   * parent is the parent resource for the panel in the ontology, required on create.
+   * Parenthood lives in the ontology graph, so the field is not persisted on the panel
+   * record and is absent on retrieve.
+   */
+  parent: ontology.idZ.optional(),
+});
+export interface Panel extends z.infer<typeof panelZ> {}
+export interface New extends z.input<typeof panelZ> {}
+
+export const ontologyID = ontology.createIDFactory<Key>("panel");
+export const TYPE_ONTOLOGY_ID = ontologyID("");