@synnaxlabs/client 0.56.1 → 0.57.0

package/src/actions/external.ts

@@ -8,3 +8,14 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/actions/actions";
+export {
+  Controller,
+  type ControllerParams,
+  type Domain,
+  type Options,
+  type Preprocess,
+  type Reducer,
+  type SendDispatch,
+  type StackEntry,
+  type Transaction,
+} from "@/actions/controller";

package/src/arc/actions.gen.ts

@@ -0,0 +1,313 @@
+// 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, crdt, record, spatial, zod } from "@synnaxlabs/x";
+import { type Draft } from "immer";
+import { z } from "zod";
+
+import { actions } from "@/actions";
+import { graph } from "@/arc/graph";
+import { ir } from "@/arc/ir";
+import { type Arc, arcZ, keyZ } from "@/arc/types.gen";
+
+/**
+ * Create replaces the document with the given created state. Emitted by the Core on
+ * create so remote caches ingest new documents; clients never dispatch it.
+ */
+export const createPayloadZ = z.object({
+  arc: arcZ,
+});
+
+export type CreatePayload = z.infer<typeof createPayloadZ>;
+
+/** Rename renames the Arc module. */
+export const renamePayloadZ = z.object({
+  name: z.string(),
+});
+
+export type RenamePayload = z.infer<typeof renamePayloadZ>;
+
+/**
+ * SetNode inserts the node if no node with the same key exists, otherwise replaces the
+ * existing node in place. Operates only on the node's position; the node's function
+ * type and inputs are set separately via SetNodeInputs.
+ */
+export const setNodePayloadZ = z.object({
+  node: graph.nodeZ,
+});
+
+export type SetNodePayload = z.infer<typeof setNodePayloadZ>;
+
+/** SetNodePosition moves a graph node to a new canvas position. */
+export const setNodePositionPayloadZ = z.object({
+  key: z.string(),
+  position: spatial.xyZ,
+});
+
+export type SetNodePositionPayload = z.infer<typeof setNodePositionPayloadZ>;
+
+/**
+ * SetNodeInputs merges the given inputs into the entry for the given key in the graph
+ * inputs map. Top-level fields present in the payload overwrite existing fields; fields
+ * absent from the payload are preserved. The node's function type is held under "type".
+ */
+export const setNodeInputsPayloadZ = z.object({
+  key: z.string(),
+  inputs: caseconv.preserveCase(record.unknownZ().default(() => ({}))),
+});
+
+export type SetNodeInputsPayload = z.infer<typeof setNodeInputsPayloadZ>;
+
+/**
+ * RemoveNode removes the node with the given key along with its inputs entry and any
+ * edges connected to it.
+ */
+export const removeNodePayloadZ = z.object({
+  key: z.string(),
+});
+
+export type RemoveNodePayload = z.infer<typeof removeNodePayloadZ>;
+
+/**
+ * AddEdge appends the edge to the graph. No-op when an edge with the same source and
+ * target handles already exists, so concurrent additions of the same connection
+ * converge regardless of differing keys.
+ */
+export const addEdgePayloadZ = z.object({
+  edge: graph.edgeZ,
+});
+
+export type AddEdgePayload = z.infer<typeof addEdgePayloadZ>;
+
+/** RemoveEdge removes the edge with the given key, if present. */
+export const removeEdgePayloadZ = z.object({
+  key: z.string(),
+});
+
+export type RemoveEdgePayload = z.infer<typeof removeEdgePayloadZ>;
+
+/**
+ * ReconnectEdge rewrites the endpoints of the edge with the given key, preserving its
+ * key and kind. No-op when no edge with the key exists.
+ */
+export const reconnectEdgePayloadZ = z.object({
+  key: z.string(),
+  source: ir.handleZ,
+  target: ir.handleZ,
+});
+
+export type ReconnectEdgePayload = z.infer<typeof reconnectEdgePayloadZ>;
+
+/**
+ * InsertChar carries a single collaborative-edit character insertion against the
+ * module's text. The payload is a sequence CRDT operation; the server relays it to the
+ * other editors of the module without interpreting it.
+ */
+export const insertCharPayloadZ = z.object({
+  id: crdt.idZ,
+  origin: crdt.idZ,
+  side: spatial.xLocationZ,
+  char: z.int32(),
+});
+
+export type InsertCharPayload = z.infer<typeof insertCharPayloadZ>;
+
+/**
+ * DeleteChar carries a single collaborative-edit character deletion against the
+ * module's text. The payload is a sequence CRDT operation; the server relays it to the
+ * other editors of the module without interpreting it.
+ */
+export const deleteCharPayloadZ = z.object({
+  id: crdt.idZ,
+});
+
+export type DeleteCharPayload = z.infer<typeof deleteCharPayloadZ>;
+
+/**
+ * ForgetChars removes the given already-deleted characters from the module's text
+ * document, dropping both their insert and delete operations from the replicated
+ * op-log. The server emits it after a quiet editing period to reclaim the space held by
+ * tombstoned characters. Because the characters are already deleted, and thus
+ * invisible, applying it never changes the materialized text.
+ */
+export const forgetCharsPayloadZ = z.object({
+  ids: crdt.idZ.array().default(() => []),
+});
+
+export type ForgetCharsPayload = z.infer<typeof forgetCharsPayloadZ>;
+
+export const actionZ = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("create"), create: createPayloadZ }),
+  z.object({ type: z.literal("rename"), rename: renamePayloadZ }),
+  z.object({ type: z.literal("set_node"), setNode: setNodePayloadZ }),
+  z.object({
+    type: z.literal("set_node_position"),
+    setNodePosition: setNodePositionPayloadZ,
+  }),
+  z.object({
+    type: z.literal("set_node_inputs"),
+    setNodeInputs: setNodeInputsPayloadZ,
+  }),
+  z.object({ type: z.literal("remove_node"), removeNode: removeNodePayloadZ }),
+  z.object({ type: z.literal("add_edge"), addEdge: addEdgePayloadZ }),
+  z.object({ type: z.literal("remove_edge"), removeEdge: removeEdgePayloadZ }),
+  z.object({ type: z.literal("reconnect_edge"), reconnectEdge: reconnectEdgePayloadZ }),
+  z.object({ type: z.literal("insert_char"), insertChar: insertCharPayloadZ }),
+  z.object({ type: z.literal("delete_char"), deleteChar: deleteCharPayloadZ }),
+  z.object({ type: z.literal("forget_chars"), forgetChars: forgetCharsPayloadZ }),
+]);
+
+export type Action = z.infer<typeof actionZ>;
+
+export const create = (payload: z.input<typeof createPayloadZ>): Action => ({
+  type: "create",
+  create: zod.parse(createPayloadZ, payload, {
+    label: "Arc create action payload",
+  }),
+});
+
+export const rename = (payload: z.input<typeof renamePayloadZ>): Action => ({
+  type: "rename",
+  rename: zod.parse(renamePayloadZ, payload, {
+    label: "Arc rename action payload",
+  }),
+});
+
+export const setNode = (payload: z.input<typeof setNodePayloadZ>): Action => ({
+  type: "set_node",
+  setNode: zod.parse(setNodePayloadZ, payload, {
+    label: "Arc set_node action payload",
+  }),
+});
+
+export const setNodePosition = (
+  payload: z.input<typeof setNodePositionPayloadZ>,
+): Action => ({
+  type: "set_node_position",
+  setNodePosition: zod.parse(setNodePositionPayloadZ, payload, {
+    label: "Arc set_node_position action payload",
+  }),
+});
+
+export const setNodeInputs = (
+  payload: z.input<typeof setNodeInputsPayloadZ>,
+): Action => ({
+  type: "set_node_inputs",
+  setNodeInputs: zod.parse(setNodeInputsPayloadZ, payload, {
+    label: "Arc set_node_inputs action payload",
+  }),
+});
+
+export const removeNode = (payload: z.input<typeof removeNodePayloadZ>): Action => ({
+  type: "remove_node",
+  removeNode: zod.parse(removeNodePayloadZ, payload, {
+    label: "Arc remove_node action payload",
+  }),
+});
+
+export const addEdge = (payload: z.input<typeof addEdgePayloadZ>): Action => ({
+  type: "add_edge",
+  addEdge: zod.parse(addEdgePayloadZ, payload, {
+    label: "Arc add_edge action payload",
+  }),
+});
+
+export const removeEdge = (payload: z.input<typeof removeEdgePayloadZ>): Action => ({
+  type: "remove_edge",
+  removeEdge: zod.parse(removeEdgePayloadZ, payload, {
+    label: "Arc remove_edge action payload",
+  }),
+});
+
+export const reconnectEdge = (
+  payload: z.input<typeof reconnectEdgePayloadZ>,
+): Action => ({
+  type: "reconnect_edge",
+  reconnectEdge: zod.parse(reconnectEdgePayloadZ, payload, {
+    label: "Arc reconnect_edge action payload",
+  }),
+});
+
+export const insertChar = (payload: z.input<typeof insertCharPayloadZ>): Action => ({
+  type: "insert_char",
+  insertChar: zod.parse(insertCharPayloadZ, payload, {
+    label: "Arc insert_char action payload",
+  }),
+});
+
+export const deleteChar = (payload: z.input<typeof deleteCharPayloadZ>): Action => ({
+  type: "delete_char",
+  deleteChar: zod.parse(deleteCharPayloadZ, payload, {
+    label: "Arc delete_char action payload",
+  }),
+});
+
+export const forgetChars = (payload: z.input<typeof forgetCharsPayloadZ>): Action => ({
+  type: "forget_chars",
+  forgetChars: zod.parse(forgetCharsPayloadZ, payload, {
+    label: "Arc forget_chars action payload",
+  }),
+});
+
+export type HandlerResult = actions.HandlerResult<Action>;
+
+export type ReduceAllResult = actions.ReduceAllResult<Arc, Action>;
+
+export interface Handlers {
+  create: (state: Draft<Arc>, payload: CreatePayload) => HandlerResult;
+  rename: (state: Draft<Arc>, payload: RenamePayload) => HandlerResult;
+  setNode: (state: Draft<Arc>, payload: SetNodePayload) => HandlerResult;
+  setNodePosition: (
+    state: Draft<Arc>,
+    payload: SetNodePositionPayload,
+  ) => HandlerResult;
+  setNodeInputs: (state: Draft<Arc>, payload: SetNodeInputsPayload) => HandlerResult;
+  removeNode: (state: Draft<Arc>, payload: RemoveNodePayload) => HandlerResult;
+  addEdge: (state: Draft<Arc>, payload: AddEdgePayload) => HandlerResult;
+  removeEdge: (state: Draft<Arc>, payload: RemoveEdgePayload) => HandlerResult;
+  reconnectEdge: (state: Draft<Arc>, payload: ReconnectEdgePayload) => HandlerResult;
+  insertChar: (state: Draft<Arc>, payload: InsertCharPayload) => HandlerResult;
+  deleteChar: (state: Draft<Arc>, payload: DeleteCharPayload) => HandlerResult;
+  forgetChars: (state: Draft<Arc>, payload: ForgetCharsPayload) => HandlerResult;
+}
+
+export const createReduceAll = (handlers: Handlers) =>
+  actions.createReduceAll<Arc, Action>((state, action) => {
+    switch (action.type) {
+      case "create":
+        return handlers.create(state, action.create);
+      case "rename":
+        return handlers.rename(state, action.rename);
+      case "set_node":
+        return handlers.setNode(state, action.setNode);
+      case "set_node_position":
+        return handlers.setNodePosition(state, action.setNodePosition);
+      case "set_node_inputs":
+        return handlers.setNodeInputs(state, action.setNodeInputs);
+      case "remove_node":
+        return handlers.removeNode(state, action.removeNode);
+      case "add_edge":
+        return handlers.addEdge(state, action.addEdge);
+      case "remove_edge":
+        return handlers.removeEdge(state, action.removeEdge);
+      case "reconnect_edge":
+        return handlers.reconnectEdge(state, action.reconnectEdge);
+      case "insert_char":
+        return handlers.insertChar(state, action.insertChar);
+      case "delete_char":
+        return handlers.deleteChar(state, action.deleteChar);
+      case "forget_chars":
+        return handlers.forgetChars(state, action.forgetChars);
+    }
+  });
+
+export const scopedActionZ = actions.scopedZ(keyZ, actionZ);
+
+export const dispatchReqZ = actions.dispatchReqZ(keyZ, actionZ);

package/src/arc/actions.ts

@@ -0,0 +1,192 @@
+// 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 crdt, type record } from "@synnaxlabs/x";
+
+import { actions } from "@/actions";
+import {
+  type Action,
+  addEdge,
+  createReduceAll,
+  type Handlers,
+  reconnectEdge,
+  removeEdge,
+  removeNode,
+  rename,
+  setNode,
+  setNodeInputs,
+  setNodePosition,
+} from "@/arc/actions.gen";
+import { type ir } from "@/arc/ir";
+
+const idToString = (id: crdt.ID): string => `${id.replica}:${id.counter}`;
+
+const sameEndpoints = (a: ir.Edge, source: ir.Handle, target: ir.Handle): boolean =>
+  a.source.node === source.node &&
+  a.source.param === source.param &&
+  a.target.node === target.node &&
+  a.target.param === target.param;
+
+const handlers: Handlers = {
+  create: (state, payload) => {
+    Object.assign(state, payload.arc);
+    return { inverse: [], targets: [payload.arc.key] };
+  },
+
+  rename: (state, payload) => {
+    const oldName = state.name;
+    state.name = payload.name;
+    return { inverse: [rename({ name: oldName })], targets: [state.key] };
+  },
+  setNode: (state, payload) => {
+    const idx = state.graph.nodes.findIndex((n) => n.key === payload.node.key);
+    if (idx === -1) {
+      state.graph.nodes.push(payload.node);
+      return {
+        inverse: [removeNode({ key: payload.node.key })],
+        targets: [payload.node.key],
+      };
+    }
+    const oldNode = actions.snapshotDraft(state.graph.nodes[idx]);
+    state.graph.nodes[idx] = payload.node;
+    return { inverse: [setNode({ node: oldNode })], targets: [payload.node.key] };
+  },
+  setNodePosition: (state, payload) => {
+    const node = state.graph.nodes.find((n) => n.key === payload.key);
+    if (node == null) return actions.NO_OP_RESULT;
+    const oldPosition = { x: node.position.x, y: node.position.y };
+    node.position = payload.position;
+    return {
+      inverse: [setNodePosition({ key: payload.key, position: oldPosition })],
+      targets: [payload.key],
+    };
+  },
+  // The inverse of SetNodeInputs is imperfect for keys the action newly introduces:
+  // SetNodeInputs only merges, so it cannot remove keys that did not previously exist.
+  // The inverse here restores values for keys that DID exist before the merge; keys
+  // added by the action remain on undo as phantom fields. A future ReplaceNodeInputs
+  // action can close the gap by enabling wholesale replacement.
+  setNodeInputs: (state, payload) => {
+    const existingRaw = state.graph.inputs[payload.key];
+    if (existingRaw == null) {
+      state.graph.inputs[payload.key] = payload.inputs;
+      return { inverse: [], targets: [payload.key] };
+    }
+    const existing = actions.snapshotDraft(existingRaw);
+    const restoreFields: record.Unknown = {};
+    for (const k of Object.keys(payload.inputs))
+      if (existing[k] !== undefined) restoreFields[k] = existing[k];
+    state.graph.inputs[payload.key] = { ...existing, ...payload.inputs };
+    if (Object.keys(restoreFields).length === 0)
+      return { inverse: [], targets: [payload.key] };
+    return {
+      inverse: [setNodeInputs({ key: payload.key, inputs: restoreFields })],
+      targets: [payload.key],
+    };
+  },
+  removeNode: (state, payload) => {
+    const idx = state.graph.nodes.findIndex((n) => n.key === payload.key);
+    if (idx === -1) return actions.NO_OP_RESULT;
+    const oldNode = actions.snapshotDraft(state.graph.nodes[idx]);
+    const oldInputs = actions.snapshotDraft(state.graph.inputs[payload.key]);
+    const removedEdges = state.graph.edges
+      .filter((e) => e.source.node === payload.key || e.target.node === payload.key)
+      .map((e) => actions.snapshotDraft(e));
+    state.graph.nodes.splice(idx, 1);
+    delete state.graph.inputs[payload.key];
+    state.graph.edges = state.graph.edges.filter(
+      (e) => e.source.node !== payload.key && e.target.node !== payload.key,
+    );
+    const inverse: Action[] = [setNode({ node: oldNode })];
+    if (oldInputs != null)
+      inverse.push(setNodeInputs({ key: payload.key, inputs: oldInputs }));
+    inverse.push(...removedEdges.map((e) => addEdge({ edge: e })));
+    return { inverse, targets: [payload.key] };
+  },
+  addEdge: (state, payload) => {
+    const { edge } = payload;
+    if (state.graph.edges.some((e) => sameEndpoints(e, edge.source, edge.target)))
+      return actions.NO_OP_RESULT;
+    state.graph.edges.push(edge);
+    return { inverse: [removeEdge({ key: edge.key })], targets: [edge.key] };
+  },
+  removeEdge: (state, payload) => {
+    const idx = state.graph.edges.findIndex((e) => e.key === payload.key);
+    if (idx === -1) return actions.NO_OP_RESULT;
+    const oldEdge = actions.snapshotDraft(state.graph.edges[idx]);
+    state.graph.edges.splice(idx, 1);
+    return { inverse: [addEdge({ edge: oldEdge })], targets: [payload.key] };
+  },
+  reconnectEdge: (state, payload) => {
+    const edge = state.graph.edges.find((e) => e.key === payload.key);
+    if (edge == null) return actions.NO_OP_RESULT;
+    const oldSource = actions.snapshotDraft(edge.source);
+    const oldTarget = actions.snapshotDraft(edge.target);
+    edge.source = payload.source;
+    edge.target = payload.target;
+    return {
+      inverse: [
+        reconnectEdge({ key: payload.key, source: oldSource, target: oldTarget }),
+      ],
+      targets: [payload.key],
+    };
+  },
+  // Undo/redo is handled the editor, which emits the corresponding
+  // insertChar, deleteChar actions.
+  insertChar: (state, payload) => {
+    state.text.doc.inserts.push(payload);
+    return { inverse: [], targets: [] };
+  },
+  deleteChar: (state, payload) => {
+    state.text.doc.deletes.push(payload);
+    return { inverse: [], targets: [] };
+  },
+  // Server-emitted maintenance: drop the insert and delete ops of already-deleted
+  // characters. The characters are tombstoned and invisible, so removing their ops does
+  // not change the materialized text.
+  forgetChars: (state, payload) => {
+    if (payload.ids.length === 0) return { inverse: [], targets: [] };
+    const forget = new Set(payload.ids.map(idToString));
+    state.text.doc.inserts = state.text.doc.inserts.filter(
+      (i) => !forget.has(idToString(i.id)),
+    );
+    state.text.doc.deletes = state.text.doc.deletes.filter(
+      (d) => !forget.has(idToString(d.id)),
+    );
+    return { inverse: [], targets: [] };
+  },
+};
+
+export const reduceAll = createReduceAll(handlers);
+
+// createOf hands the dispatch controller the document carried by a create
+// action so frames for never-cached documents ingest instead of drop.
+export const createOf = (action: Action) =>
+  action.type === "create" ? action.create.arc : undefined;
+
+// isUndoable reports whether an action should push onto the undo stack. Graph mutations
+// are user-driven and undoable; collaborative text edits are not (they carry no inverse
+// and belong to the CRDT, not the graph undo stack), nor is the server's tombstone
+// reclamation.
+export const isUndoable = (action: Action): boolean =>
+  action.type !== "insert_char" &&
+  action.type !== "delete_char" &&
+  action.type !== "forget_chars";
+
+// kindOf classifies an action batch for the undo coalesce window. A
+// node drag dispatches a stream of set_node_position actions for a single
+// gesture; classifying them all as "move" collapses them into one undoable.
+export const kindOf = (actions: Action[]): string => {
+  if (actions.length === 0) return "default";
+  const hasMove = actions.some((a) => a.type === "set_node_position");
+  const onlyMove = actions.every((a) => a.type === "set_node_position");
+  if (hasMove && onlyMove) return "move";
+  if (actions.length === 1) return actions[0].type;
+  return "transaction";
+};